pathspec

Starting from version 1.0.0, pathspec supports different backends to allow for faster regular expression matching. You can control which backend is used by passing the backend argument to the following constructors:

• PathSpec()
• PathSpec.from_lines()
• GitIgnoreSpec()
• GitIgnoreSpec.from_lines()

Available backends include:

• The default Python regex backend.
• hyperscan: An optional backend using the hyperscan library. Install it via pip install 'pathspec[hyperscan]'.
• re2: An optional backend using the google-re2 library. Install it via pip install 'pathspec[re2]'.

# Example of specifying a backend (assuming hyperscan is installed)
from pathspec import PathSpec

spec = PathSpec(patterns=['*.txt'], backend='hyperscan')

By default, PathSpec and GitIgnoreSpec positively match files (they return what is included). To find files that should be ignored (e.g., to exclude .gitignore files from a backup), set negate=True in the matching methods.

from pathspec import GitIgnoreSpec

spec = GitIgnoreSpec.from_lines(['*.gitignore'])
# Returns files that match the pattern (the ignored files)
ignore_files = set(spec.match_tree_files('path/to/dir', negate=True))

# Returns files that do NOT match the pattern (the kept files)
keep_files = set(spec.match_tree_files('path/to/dir', negate=False))

PathSpec provides optional backends to improve matching performance. You can compare the performance of the native Python re module (referred to as the simple backend) against high-performance alternatives like hyperscan and re2.

Benchmarks are typically measured using PathSpec.match_files() or GitIgnoreSpec.match_files() across varying numbers of patterns. Performance varies significantly based on the Python runtime (CPython vs. PyPy) and the hardware architecture.

By default, PathSpec and GitIgnoreSpec return files that match the patterns (positive matching). If you want to find files that are not matched by the patterns (e.g., to find all files except those ignored by a .gitignore), set negate=True in the matching methods.

from pathspec import GitIgnoreSpec

spec = GitIgnoreSpec.from_lines(['*.log'])
# Returns files that match '*.log'
matched_files = set(spec.match_tree_files('path/to/dir'))

# Returns files that DO NOT match '*.log'
keep_files = set(spec.match_tree_files('path/to/dir', negate=True))

To build from source, you need the build package (>=0.6.0) installed. Use the following commands to build and install the wheel:

python -m build
pip install dist/pathspec-*-py3-none-any.whl

You can install pathspec via PyPI using pip:

pip install pathspec

To build from source, you will need the build package (>=0.6.0):

python -m build
pip install dist/pathspec-*-py3-none-any.whl

Optional Dependencies

• google-re2: Enables the high-performance "re2" backend.
• hyperscan: Enables the "hyperscan" backend.
• typing-extensions: Improves type hint support.

You can install pathspec directly from PyPI using pip.

pip install pathspec

To improve matching performance, you can install optional dependencies for specialized regular expression backends:

• google-re2: Enables the re2 backend.
• hyperscan: Enables the hyperscan backend.
• typing-extensions: Improves type hints.

When upgrading from version 0.12.1 to 1.0.0, the gitwildmatch pattern type has been replaced by gitignore. You should update your calls to PathSpec.from_lines to use the gitignore argument instead of gitwildmatch.

Note that gitignore patterns have different matching behaviors than gitwildmatch:

• Patterns like foo/* will no longer match files in subdirectories (e.g., foo/bar/hello.c will not match).
• The exact pattern / now matches every file (equivalent to **).

If you require the legacy gitwildmatch behavior, you can use GitIgnoreSpecPattern, though this is discouraged.

# Old way (deprecated)
spec = PathSpec.from_lines('gitwildmatch', patterns)

# New way
spec = PathSpec.from_lines('gitignore', patterns)

To use high-performance matching backends, you can install pathspec with the corresponding optional dependencies:

• For the hyperscan backend: pip install 'pathspec[hyperscan]'
• For the re2 backend: pip install 'pathspec[re2]'

If these libraries are installed in your environment, pathspec will attempt to use them automatically.