Snapshot your linter errors and track only new issues in CI — perfect for adopting linters incrementally on large codebases without breaking existing workflows.

snaplint captures a baseline of current linter findings and lets you diff future runs against it. Only new errors cause CI failures, while existing issues are tracked separately.

Install via pip or uv:

pip install snaplint
# or
uv tool install snaplint

1. Create a baseline snapshot of your current linter output:

flake8 src/ | snaplint take-snapshot
# Creates .snaplint/snapshot.flake8.json.gz

2. Check for new issues in CI or locally:

flake8 src/ | snaplint diff
# Exit code 0: no new issues ✓
# Exit code 1: new issues found ✗

The diff command shows you:

• ✗ New errors (red) — will fail CI
• ✓ Removed errors (green) — improvements!
• File-level changes — error count and ordering changes per file

snaplint automatically detects your linter (ruff, flake8, mypy, pylint, or generic format) and creates appropriately named snapshots in .snaplint/:

# Each linter gets its own snapshot
ruff check . --output-format concise | snaplint take-snapshot # → .snaplint/snapshot.ruff.json.gz
flake8 . | snaplint take-snapshot # → .snaplint/snapshot.flake8.json.gz
mypy . | snaplint take-snapshot # → .snaplint/snapshot.mypy.json.gz
pylint src/ | snaplint take-snapshot # → .snaplint/snapshot.pylint.json.gz

Specify a custom path if needed:

flake8 . | snaplint take-snapshot snapshots/baseline.json
flake8 . | snaplint diff snapshots/baseline.json

• 0 — No new issues (safe to merge)
• 1 — New issues detected (CI should fail)
• 2 — Usage error (missing snapshot, no input, etc.)
• 3 — Unexpected internal error

snaplint creates SHA1 fingerprints of each error by hashing the error type + source code line. This makes error tracking resilient to:

• Line number changes (refactoring, adding imports)
• File reorganization
• Whitespace changes in unrelated code

When comparing snapshots:

• Per-file tracking shows which files improved or regressed
• Order changes are detected when errors move within a file
• Count changes show if the total number of issues changed
• File-level errors (line 0) are fully supported

Snapshots are stored as gzip-compressed JSON (.json.gz) with version metadata for forward compatibility.

- name: Check for new linter issues
 run: |
 flake8 . | snaplint diff || {
 echo "❌ New linting issues detected"
 exit 1
 }

Add to .pre-commit-config.yaml:

- repo: local
 hooks:
 - id: snaplint
 name: Check linting snapshot
 entry: bash -c 'flake8 . | snaplint diff'
 language: system
 pass_filenames: false

snaplint automatically recognizes output from:

• ruff (use --output-format concise)
• flake8 and compatible tools (flake9, etc.)
• mypy
• pylint
• Generic format — any tool outputting path:line:col: message

Unrecognized lines are skipped with a warning to stderr.

If your project needs to support older Python versions (e.g., Python 3.8) but snaplint requires Python 3.10+, you can run the linter with your target Python version and snaplint with a newer interpreter:

# Run linter with Python 3.8
python3.8 -m flake8 src/ > /tmp/lint_output.txt
# Process with snaplint using Python 3.10+
python3.10 -m snaplint take-snapshot < /tmp/lint_output.txt
python3.10 -m snaplint diff < /tmp/lint_output.txt

Or use separate virtual environments:

# Create venv for linting with old Python
python3.8 -m venv .venv-lint
.venv-lint/bin/pip install flake8
# Create venv for snaplint with new Python
python3.10 -m venv .venv-snaplint
.venv-snaplint/bin/pip install snaplint
# Use them together
.venv-lint/bin/flake8 src/ | .venv-snaplint/bin/snaplint diff

This approach lets you maintain compatibility with older Python versions in your codebase while using modern tooling for CI/CD workflows.

# Clone the repository
git clone https://github.com/GENWAY-AI/snaplint.git
cd snaplint
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e ".[dev]"

# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=snaplint --cov-report=html
# Run specific test file
uv run pytest tests/test_e2e.py -v

Install as a global command for testing:

uv tool install -e .
snaplint --version

MIT