gitignorant — A parser for gitignore files

0.4.0 verified Mon Apr 27 auth: no python

Gitignorant is a Python library for parsing and evaluating .gitignore rules. It provides a simple API to check whether a given path would be ignored by a set of gitignore patterns. The current version is 0.4.0, targeting Python >=3.7, with infrequent releases.

pip install gitignorant

Common errors

error TypeError: 'str' object is not callable ↓

cause Passing a single pattern string instead of a list causes Python to iterate over characters.

fix

Use patterns=['*.log'] instead of patterns='*.log'

error FileNotFoundError: [Errno 2] No such file or directory: '<path>' ↓

cause base_path or patterns file path does not exist.

fix

Ensure base_path is an existing directory. If loading from a file, use from pathlib import Path and check Path('file').exists().

error AttributeError: module 'gitignorant' has no attribute 'is_ignored' ↓

cause Confusing the module function (not present) with the method on a matcher instance.

fix

Create a GitIgnoreMatcher instance and call its is_ignored method.

Warnings

gotcha Paths are relative to base_path; do not pass absolute paths or paths with leading slashes. ↓

fix Pass paths relative to the base_path (e.g., 'subdir/file.py' not '/abs/path/subdir/file.py').

gotcha Patterns must be list of strings; a single string will cause silent failure (iterates over characters). ↓

fix Always wrap a single pattern in a list: GitIgnoreMatcher(patterns=['pattern'], ...).

gotcha The library does not automatically ignore .git folder; you must include it if needed. ↓

fix Add '.git/' to your patterns list explicitly.

Imports

GitIgnoreMatcher
```
from gitignorant import GitIgnoreMatcher
```
The class GitIgnoreMatcher is the primary entry point.

Quickstart

Create a matcher from a list of patterns and check if paths are ignored.

from gitignorant import GitIgnoreMatcher

matcher = GitIgnoreMatcher(
    patterns=['*.pyc', '__pycache__/'],
    base_path='/project'
)
print(matcher.is_ignored('foo.py'))  # False
print(matcher.is_ignored('bar.pyc'))  # True
print(matcher.is_ignored('__pycache__/cache.py'))  # True