🔪 git-surgeon

Surgical git history rewriting: a modular CLI toolkit wrapping git-filter-repo.

Rewrite authors, scrub sensitive data, clean commit messages, flatten merges, and filter commits, all in a single pass with automatic backup & undo.

Features

Usage Instructions

pip install git-surgeon-cli

or

uv add git-surgeon-cli

Requires Python ≥3.12 and git on PATH.

cd /path/to/your/repo

# Option A: Interactive wizard
git-surgeon

# Option B: CLI commands
git-surgeon init
git-surgeon rewrite-authors --name "Jane" --email "jane@example.com" --default --save
git-surgeon scrub --find "secret-api-key" --replace "***REMOVED***"
git-surgeon run          # creates backup, rewrites history
git-surgeon undo         # restore if needed

Architecture

graph TD
    classDef cli fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#000;
    classDef core fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000;
    classDef ops fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#000;
    classDef ext fill:#eceff1,stroke:#607d8b,stroke-width:2px,color:#000;

    U([User Input]) --> CLI[CLI & Wizard]:::cli
    CLI --> Core[Engine Orchestrator]:::core
    Core <--> Ops[Pluggable Operations]:::ops
    Core --> GFR[git-filter-repo]:::ext
    GFR --> Git[Git Repository]:::ext

For a detailed breakdown of the system architecture and data flow, see the Architecture Documentation.

Documentation

For full guides on usage, configuration, internals, and operations, please visit the Documentation Index or build the docs using MkDocs. For AI agent integration, see docs/mcp-setup.md.

WIP

Safety

Every git-surgeon run automatically creates a git bundle backup at .git-surgeon/backup.bundle before touching history. Run git-surgeon undo to fully restore. Use --dry-run on any command to preview without modifying anything.

About

License

Apache License 2.0. See LICENSE for details.

Pypi