git-surgeon-cli 0.1.0

Surgical git history rewriting: author rewrite, message scrub, sensitive data removal, and more.

🔪 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

Feature	Description
Message Scrub	Find-and-replace text in commit messages (literal or regex)
Blob Scrub	Remove secrets, emails, keys from file contents across all history
Merge Flatten	Linearize history by converting merge commits to single-parent
Commit Filter	Remove or keep commits matching specific criteria
Backup & Undo	Automatic git bundle backup + git-surgeon undo to restore
Dry Run	Preview every change before touching the repo
Interactive Wizard	Run git-surgeon with no args for guided setup
Config Persistence	Operations saved to .git-surgeon/config.toml (auto-gitignored)

Quick Start

pip install git-surgeon-cli

or

uv add git-surgeon-cli

Requires Python ≥3.13 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 "[e-mail]" --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.

License

Apache License 2.0. See LICENSE for details.