igittigitt

igittigitt

igittigitt is a spec-compliant .gitignore parser for Python - a library and a command-line tool. Point it at .gitignore rules (or pass rules as strings) and ask whether a path is ignored, or use it directly as the ignore= callback of shutil.copytree.

Features

• 100% git-compatible matching. The matching engine reproduces git's algorithm exactly - a single ordered pass with last-matching-pattern-wins, correct negations (!pattern), the rule that a file cannot be re-included when a parent directory is excluded, per-directory .gitignore precedence, anchors, trailing-slash (directory-only), **, *, ? and [...] character classes. Compatibility is proven by a differential test suite that compares igittigitt against real git check-ignore on hundreds of generated cases. (This fixes the negation and nested-precedence limitations of older releases.)
• Include / whitelist mode. IncludeParser inverts the logic: patterns describe what to keep. It is directory-aware (rsync-like), so it works correctly as a copytree filter even for deeply nested includes.
• Memory-safe for millions of files. Both modes stream per directory and decide each path in O(depth x rules). Memory scales with the number of rules, never with the number of files or directories - so it stays flat on trees with millions of entries.
• Scriptable CLI with piping. igittigitt check mirrors git check-ignore, and igittigitt filter is a Unix filter that reads paths from stdin and prints the survivors - newline- or NUL-separated (-z), streamed, with clean SIGPIPE handling, so it drops cleanly into find ... | igittigitt filter.
• Typed library, pure Python. Ships py.typed, no runtime dependency on the git binary.

---

Install

uv is the recommended installer.

# as a project dependency
uv add igittigitt

# as a standalone CLI tool (isolated environment, added to PATH)
uv tool install igittigitt

# run once without installing
uvx igittigitt --help

# or classic pip / pipx
pip install igittigitt
pipx install igittigitt

The project targets Python 3.10+ and is tested on Linux, macOS and Windows across CPython 3.10-3.14. See INSTALL.md for every install method.

---

Library usage

Ignore mode

import igittigitt

parser = igittigitt.IgnoreParser()

# discover and parse every .gitignore below base_dir (per-directory precedence)
parser.parse_rule_files(base_dir="/home/user/project")

# ... or add rules explicitly
parser.add_rule("*.py[cod]", base_path="/home/user/project")
parser.add_rule("!keep.pyc", base_path="/home/user/project")

parser.match("/home/user/project/main.pyc")   # True  (ignored)
parser.match("/home/user/project/keep.pyc")   # False (re-included by the negation)

Use it as a shutil.copytree filter to copy a tree without the ignored files:

import shutil, igittigitt

parser = igittigitt.IgnoreParser()
parser.parse_rule_files(base_dir="src_tree")
shutil.copytree("src_tree", "dst_tree", ignore=parser.shutil_ignore)

Whitelist / include mode

IncludeParser keeps only what matches; everything else is dropped. Including a directory keeps its whole subtree, and unanchored patterns are found at any depth:

import shutil, igittigitt

inc = igittigitt.IncludeParser()
inc.add_rule("*.py", base_path="src_tree")          # keep only python files...
inc.add_rule("docs/", base_path="src_tree")         # ...and the whole docs/ subtree