Getting started

occam-gitignore is a Python toolchain for producing deterministic .gitignore files. It ships as a uv workspace of independent packages: a pure core, plus four thin adapters.

Requirements

• Python 3.11+
• uv 0.10+

Install (workspace mode)

git clone https://github.com/fabriziosalmi/gitignore.git
cd gitignore/occam-gitignore
uv sync

This installs all six packages in editable mode and pins their dev tooling (pytest, mypy, ruff).

Generate a .gitignore

uv run occam-gitignore generate ./path/to/repo

The CLI walks the tree, fingerprints features, and emits a deterministic file with provenance comments:

# Generated by occam-gitignore. Deterministic. Do not edit by hand.

# --- template ---
__pycache__/
*.py[cod]
.venv/
.DS_Store
.idea/
.vscode/
Thumbs.db

# --- mined ---
.env

Validate determinism

uv run pytest -q
uv run ruff check .
uv run mypy .

The core test suite enforces:

• byte-identical output across runs
• input-order invariance
• snapshot stability against golden files
• presence of output_hash, core_version, rules_table_version

Run the benchmark

uv run occam-gitignore-bench run bench/corpus \
  --templates data/templates \
  --rules-table data/rules_table.json \
  --repeats 10 --diff \
  --min-recall 0.85 --max-p99-ms 5.0

You should see something like:

core=0.1.3 rules_table=sha256:72fd0c323cc1 cases=7
macro: P=0.443 R=1.000 F1=0.608
micro: P=0.425 R=1.000 F1=0.597
stability=1.000 latency p50=0.047ms p99=0.119ms

Continue with Architecture →