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

# copy only the kept files (parent directories are descended into automatically)
shutil.copytree("src_tree", "dst_tree", ignore=inc.shutil_include)

inc.match("src_tree/pkg/deep.py")  # True  (kept)

CLI usage

# which of these paths are ignored? (like `git check-ignore`)
igittigitt check -C /path/to/repo a.log src/main.py
#   exit 0 if at least one path is ignored, 1 if none

# show the matching rule (source:line:pattern), like `git check-ignore -v`
igittigitt check -C /path/to/repo -v a.log

# Unix filter: drop ignored paths from a stream
find . -type f | igittigitt filter

# keep only what matches the include patterns
find . -type f | igittigitt filter --include -r '*.py'

# NUL-separated I/O for paths with spaces/newlines
find . -print0 | igittigitt filter -z | xargs -0 ...

# inline rules and explicit ignore files
igittigitt check -r '*.tmp' -f .gitignore --stdin < paths.txt

Global options

Commands

Shared check / filter options: -C/--base-dir, -f/--gitignore FILE (repeatable), -r/--rule PATTERN (repeatable), --scan/--no-scan, --default-patterns, -z/--zero (NUL I/O), and (check only) -v/--verbose and --stdin.

check and filter stream their input and write results immediately, with clean SIGPIPE handling - so ... | igittigitt filter | head works without errors.

Configuration

igittigitt uses lib_layered_config: settings are merged from, lowest to highest precedence,

bundled defaults -> app -> host -> user -> .env file -> environment variables -> --set

Inspect the effective configuration with igittigitt config, and deploy editable copies with igittigitt config-deploy. Override a single value per run with --set, in a .env file as SECTION__KEY=value, or via an environment variable as IGITTIGITT___SECTION__KEY=value. When a configuration file cannot be loaded, config, check and filter exit 78 with one line naming it, while info, config-deploy (which replaces the file) and --help still run; a malformed --set or an invalid --profile name exits 2. See CONFIG.md.

[performance] - engine and CLI tuning

These knobs only affect speed and cache memory, never which paths match. Defaults were chosen by measurement; all keep memory bounded.

Example: igittigitt --set performance.dir_cache_max=32768 filter -C repo.

[lib_log_rich] - logging

Logging is provided by lib_log_rich. The [lib_log_rich] section configures console level/theme, journald/eventlog/Graylog backends, queueing, scrubbing and payload limits. Every key is documented inline in the deployed config.d/90-logging.toml; for example set the console level with igittigitt --set lib_log_rich.console_level=DEBUG info or IGITTIGITT___LIB_LOG_RICH__CONSOLE_LEVEL=DEBUG.

The full, commented settings live in the bundled config files (see config-generate-examples) and in CONFIG.md.

Claude Code skill

This repo is itself a Claude Code plugin/marketplace and ships a skill (skills/python-gitignore/) that teaches Claude how to install, configure and use igittigitt (library, CLI, and bash piping). Install it in any project:

/plugin marketplace add bitranox/igittigitt
/plugin install igittigitt

The same skill is also mirrored in the central bitranox marketplace (https://github.com/bitranox/bitranox-skills) as python-gitignore.

AI transparency

This project was built by a human with AI assistance, used as a tool under human direction.

• ai-stance.md - why we work this way and how we think about AI in software.
• ai-disclosure.md - exactly where AI was and was not used in this project, and what has and has not been tested.

Further Documentation

• INSTALL.md - every installation method.
• DEVELOPMENT.md - make targets, testing, release workflow.
• CHANGELOG.md - release history.
• CONTRIBUTING.md - how to contribute.