1 2*pathspec*: Path Specification 3============================== 4 5*pathspec* is a utility library for pattern matching of file paths. So 6far this only includes Git's wildmatch pattern matching which itself is 7derived from Rsync's wildmatch. Git uses wildmatch for its `gitignore`_ 8files. 9 10.. _`gitignore`: http://git-scm.com/docs/gitignore 11 12 13Tutorial 14-------- 15 16Say you have a "Projects" directory and you want to back it up, but only 17certain files, and ignore others depending on certain conditions:: 18 19 >>> import pathspec 20 >>> # The gitignore-style patterns for files to select, but we're including 21 >>> # instead of ignoring. 22 >>> spec = """ 23 ... 24 ... # This is a comment because the line begins with a hash: "#" 25 ... 26 ... # Include several project directories (and all descendants) relative to 27 ... # the current directory. To reference a directory you must end with a 28 ... # slash: "/" 29 ... /project-a/ 30 ... /project-b/ 31 ... /project-c/ 32 ... 33 ... # Patterns can be negated by prefixing with exclamation mark: "!" 34 ... 35 ... # Ignore temporary files beginning or ending with "~" and ending with 36 ... # ".swp". 37 ... !~* 38 ... !*~ 39 ... !*.swp 40 ... 41 ... # These are python projects so ignore compiled python files from 42 ... # testing. 43 ... !*.pyc 44 ... 45 ... # Ignore the build directories but only directly under the project 46 ... # directories. 47 ... !/*/build/ 48 ... 49 ... """ 50 51We want to use the ``GitWildMatchPattern`` class to compile our patterns. The 52``PathSpec`` class provides an interface around pattern implementations:: 53 54 >>> spec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, spec.splitlines()) 55 56That may be a mouthful but it allows for additional patterns to be implemented 57in the future without them having to deal with anything but matching the paths 58sent to them. ``GitWildMatchPattern`` is the implementation of the actual 59pattern which internally gets converted into a regular expression. 60``PathSpec`` is a simple wrapper around a list of compiled patterns. 61 62To make things simpler, we can use the registered name for a pattern class 63instead of always having to provide a reference to the class itself. The 64``GitWildMatchPattern`` class is registered as **gitwildmatch**:: 65 66 >>> spec = pathspec.PathSpec.from_lines('gitwildmatch', spec.splitlines()) 67 68If we wanted to manually compile the patterns we can just do the following:: 69 70 >>> patterns = map(pathspec.patterns.GitWildMatchPattern, spec.splitlines()) 71 >>> spec = PathSpec(patterns) 72 73``PathSpec.from_lines()`` is simply a class method which does just that. 74 75If you want to load the patterns from file, you can pass the file instance 76directly as well:: 77 78 >>> with open('patterns.list', 'r') as fh: 79 >>> spec = pathspec.PathSpec.from_lines('gitwildmatch', fh) 80 81You can perform matching on a whole directory tree with:: 82 83 >>> matches = spec.match_tree('path/to/directory') 84 85Or you can perform matching on a specific set of file paths with:: 86 87 >>> matches = spec.match_files(file_paths) 88 89Or check to see if an individual file matches:: 90 91 >>> is_matched = spec.match_file(file_path) 92 93 94License 95------- 96 97*pathspec* is licensed under the `Mozilla Public License Version 2.0`_. See 98`LICENSE`_ or the `FAQ`_ for more information. 99 100In summary, you may use *pathspec* with any closed or open source project 101without affecting the license of the larger work so long as you: 102 103- give credit where credit is due, 104 105- and release any custom changes made to *pathspec*. 106 107.. _`Mozilla Public License Version 2.0`: http://www.mozilla.org/MPL/2.0 108.. _`LICENSE`: LICENSE 109.. _`FAQ`: http://www.mozilla.org/MPL/2.0/FAQ.html 110 111 112Source 113------ 114 115The source code for *pathspec* is available from the GitHub repo 116`cpburnz/python-path-specification`_. 117 118.. _`cpburnz/python-path-specification`: https://github.com/cpburnz/python-path-specification 119 120 121Installation 122------------ 123 124*pathspec* requires the following packages: 125 126- `setuptools`_ 127 128*pathspec* can be installed from source with:: 129 130 python setup.py install 131 132*pathspec* is also available for install through `PyPI`_:: 133 134 pip install pathspec 135 136.. _`setuptools`: https://pypi.python.org/pypi/setuptools 137.. _`PyPI`: http://pypi.python.org/pypi/pathspec 138 139 140Documentation 141------------- 142 143Documentation for *pathspec* is available on `Read the Docs`_. 144 145.. _`Read the Docs`: http://python-path-specification.readthedocs.io 146 147 148Other Languages 149--------------- 150 151*pathspec* is also available as a `Ruby gem`_. 152 153.. _`Ruby gem`: https://github.com/highb/pathspec-ruby 154