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.15. See INSTALL.md for every install method.

Why we recommend uv: supply-chain protection

This repository commits a uv.lock. It pins every package the project needs, transitive
dependencies included, to an exact version and to the hashes of that version's files. The
exclude-newer setting under [tool.uv] in pyproject.toml adds a cooldown: uv leaves any
release younger than that out of the lock. CI installs from the lock, so a hijacked release that
gets pulled again within the cooldown never reaches our builds, and a file whose hash does not
match is refused.

That protection stays in this repository. The installable package declares only lower bounds
(>=) for its dependencies, so a plain pip install takes the newest release of every transitive
dependency at the moment you run it. If one of them was hijacked an hour earlier, you get the
hijacked version. pipx install and uv tool install without options do the same.

To install the command line tool with a cooldown of your own (uv then skips any release younger
than 7 days, transitive ones included), or to run the exact tree our CI tests:

uv tool install --exclude-newer "7 days" igittigitt
git clone https://github.com/bitranox/igittigitt.git && cd igittigitt && uv sync --locked && uv run igittigitt --help

If you depend on igittigitt in your own project, give that project the same cooldown (7 days here, as
an example) and commit the uv.lock that uv add igittigitt writes:

[tool.uv]
exclude-newer = "7 days"

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.