Preflight

What exactly am I about to commit?

Preflight is a deterministic, read-only CLI that inspects the Git index immediately before git commit. It summarizes the staged snapshot and reports evidence-backed repository states developers commonly regret committing.

python -m pip install evo-preflight
preflight

Preflight inspects staged paths and blob sizes, common generated artifacts, tracked files matching .gitignore, foundational repository files, and the repository default branch. Every finding says what was observed, why it matters, and a suggested fix.

It never blocks a commit, changes repository state, runs tests or builds, scans secrets, certifies releases, installs hooks, uses AI, sends telemetry, or accesses the network.

Commands

preflight
preflight --json
preflight --largest
preflight --version
preflight explain large-staged-file
preflight --config preflight.toml

Findings always return exit code 0. Exit code 2 means the repository or configuration is unavailable; 3 means an unexpected internal error occurred.

What it reports

• staged files of at least 100 MB;
• staged snapshots of at least 500 MB, with largest contributors;
• Python caches: __pycache__, *.pyc, and *.pyo;
• virtual environments: .venv and venv;
• build artifacts: build, dist, *.whl, and *.egg-info;
• *.jsonl and configured generated directories;
• tracked files matching standard Git ignore rules;
• a missing root README, LICENSE, or .gitignore;
• a default branch named master, reported without claiming it is wrong;
• the ten largest tracked files when --largest is requested.

Preflight reads staged content from Git, so unstaged edits are never described as part of the next commit.

Configuration

Preflight automatically reads preflight.toml from the repository root. Configuration is declarative, has no commands or scripting, and rejects unknown keys.

version = 1

[limits]
large_file_mb = 100
large_snapshot_mb = 500

[generated]
directories = ["benchmarks/results", "telemetry"]

Development

python -m pip install -e ".[dev]"
ruff check .
mypy
python -m unittest discover -s tests -v
python -m build
twine check dist/*

See CONTRIBUTING.md for the contribution workflow and CHANGELOG.md for release history.