Registry / serialization / gitignore-parser

gitignore-parser

library0.1.13pypypi✓ verified 31d ago

gitignore-parser is a spec-compliant Python library for parsing `.gitignore` files and matching paths against their rules. It provides accurate behavior according to the Git documentation for ignore rules. The current version is 0.1.13, and the library receives regular updates for bug fixes and minor improvements.

serialization

pip install gitignore-parser

github ↗package ↗

INSTALL

IMPORT

SIG · GITIGNORE-PARSER

gitignore-parser

serializationpythonv0.1.13

Install

3.0s avg

Import

23ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.13 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.024s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.0s · import 0.022s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse_gitignore

✓ from gitignore_parser import parse_gitignore

parse_gitignore_str

✓ from gitignore_parser import parse_gitignore_str

✗ from gitignore_parser import GitignoreParser

The primary interface is via parsing functions, not a direct class constructor. 'parse_gitignore_str' was added in v0.1.12.

This quickstart demonstrates how to create a gitignore parser instance from both a file path and a string, then use its `match()` method to check if specific file paths are ignored according to the rules.

from pathlib import Path from gitignore_parser import parse_gitignore, parse_gitignore_str # Example 1: Parsing from a file gitignore_path = Path("temp_test.gitignore") gitignore_path.write_text(""" # Ignore build artifacts /build/ *.log !important.log """) # Create a parser instance from the .gitignore file parser_file = parse_gitignore(gitignore_path) # Test matching paths print(f"Is 'build/app.exe' ignored? {parser_file.match('build/app.exe')}") print(f"Is 'temp.log' ignored? {parser_file.match('temp.log')}") print(f"Is 'important.log' ignored? {parser_file.match('important.log')}") gitignore_path.unlink() # Clean up the temporary file # Example 2: Parsing from a string (available from v0.1.12+) gitignore_content = """ # Ignore temporary files *.tmp /cache/ """ parser_str = parse_gitignore_str(gitignore_content) print(f"Is 'file.tmp' ignored (from string)? {parser_str.match('file.tmp')}") print(f"Is 'project/cache/data.json' ignored (from string)? {parser_str.match('project/cache/data.json')}")

Debug

Known issues

gotchaOlder versions (pre-0.1.8 / pre-0.1.7) had incorrect parsing behavior for certain complex patterns, such as implicit anchoring, multi-asterisks, leading exclamation marks, and slashes in ranges. This could lead to rules not matching as expected according to the gitignore specification.

fix

Upgrade to version 0.1.8 or newer to ensure correct, spec-compliant parsing behavior. Review your `.gitignore` files if upgrading from very old versions to ensure rules still behave as intended after the fixes.

affects: <0.1.8

gotchaThe `parse_gitignore_str()` function, which allows parsing gitignore rules directly from a string without needing a file, was introduced in version 0.1.12. Prior versions only supported parsing from a file path using `parse_gitignore()`.

fix

If you need to parse rules from a string, upgrade to version 0.1.12 or newer. For older versions, you must write the rules to a temporary file and use `parse_gitignore()`.

affects: <0.1.12

gotchaVersion 0.1.13 fixed some edge cases related to path matching on Windows, which could lead to incorrect ignore decisions for certain patterns and paths on Windows systems.

fix

Windows users should upgrade to version 0.1.13 or newer to ensure robust and correct parsing behavior across different file system structures and path formats.

affects: <0.1.13

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gitignore_parser'

The `gitignore-parser` library is not installed in your Python environment or there's a typo in the import statement.

fix

Ensure the library is installed using pip: `pip install gitignore-parser`. Also, verify the import statement is `from gitignore_parser import parse_gitignore`.

AttributeError: 'function' object has no attribute 'match'

The `parse_gitignore` function returns a callable object (a function) that directly takes a file path as an argument to check if it matches, not an object with a `.match()` method. This error occurs when trying to call a non-existent `.match()` method on the returned callable.

fix

Call the result of `parse_gitignore` directly with the path you want to check, like `matches('/path/to/file')` instead of `matches.match('/path/to/file')`.

TypeError: 'bool' object is not callable

This error often happens when you incorrectly use the boolean result of a path matching (which is either `True` or `False`) as if it were a function.

fix

The result of `matches(path)` is a boolean indicating whether the path is ignored. Use it in conditional statements directly, for example: `if matches('/path/to/file'): print('ignored')`.

FileNotFoundError: [Errno 2] No such file or directory: '/path/to/.gitignore'

The `parse_gitignore` function expects a valid path to an existing `.gitignore` file, but the provided path does not point to an actual file.

fix

Ensure the `.gitignore` file exists at the specified path and that the path provided to `parse_gitignore` is correct and accessible.

Upgrade

Version history

0.1.13latest on PyPI · released Aug 25, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mherrmann/gitignore_parser ↗

packagehttps://pypi.org/project/gitignore-parser/ ↗