filter-repo-rs

English | 中文

🦀 Fast, safe Git history rewriting in Rust — remove secrets, slim repos, restructure paths.

What Problems Does It Solve?

Quick Examples

Remove Leaked Secrets

# 1. Backup first (strongly recommended)
filter-repo-rs --backup

# 2. Create replacement rules (secrets.txt)
#    API_KEY_12345==>REDACTED
#    regex:password\s*=\s*"[^"]+==>[REMOVED]

# 3. Clean all history
filter-repo-rs --replace-text secrets.txt --sensitive --write-report

# 4. Force push
git push --force --all && git push --force --tags

Slim Down Bloated Repo

# Analyze first
filter-repo-rs --analyze

# Remove files larger than 10MB
filter-repo-rs --max-blob-size 10M --write-report

Restructure Paths

# Extract subdirectory as new root
filter-repo-rs --subdirectory-filter src/frontend

# Move root into subdirectory
filter-repo-rs --to-subdirectory-filter packages/core

# Bulk rename paths
filter-repo-rs --path-rename old/:new/

Safety First

Installation

Requirements: Git on PATH, Rust toolchain (stable), Linux/macOS/Windows

# Build from source
cargo build -p filter-repo-rs --release

# Binary at: target/release/filter-repo-rs

# Using build script (recommended)
./scripts/build-cross.sh                    # All platforms
./scripts/build-cross.sh x86_64-apple-darwin # Specific target

# Or manually with cross
cargo install cross --git https://github.com/cross-rs/cross
cross build --target x86_64-unknown-linux-gnu --release -p filter-repo-rs

All Use Cases

# secrets.txt - supports literal and regex
SECRET_TOKEN==>REDACTED
regex:(API|TOKEN|SECRET)[A-Za-z0-9_-]+==>REDACTED

filter-repo-rs --replace-text secrets.txt --sensitive --write-report

# messages.txt
password==>[removed]

filter-repo-rs --replace-message messages.txt --write-report

# By size threshold
filter-repo-rs --max-blob-size 5M --write-report

# By specific blob IDs
filter-repo-rs --strip-blobs-with-ids big-oids.txt --write-report

filter-repo-rs --tag-rename v1.:legacy/v1.
filter-repo-rs --branch-rename feature/:exp/

# Extract subdirectory as new root
filter-repo-rs --subdirectory-filter frontend

# Move root to subdirectory
filter-repo-rs --to-subdirectory-filter app/

# Rename path prefixes
filter-repo-rs --path-rename old/:new/

# Single file
filter-repo-rs --path docs/STATUS.md --invert-paths

# By glob pattern
filter-repo-rs --path-glob "*.log" --invert-paths

# By regex
filter-repo-rs --path-regex "^temp/.*\.tmp$" --invert-paths

filter-repo-rs --analyze --analyze-json

[analyze.thresholds]
warn_blob_bytes = 10_000_000
warn_commit_msg_bytes = 4096

Backup & Recovery

# Backup creates: .git/filter-repo/backup-YYYYMMDD-HHMMSS.bundle
filter-repo-rs --backup

# Restore
git clone /path/to/backup.bundle restored-repo

Artifacts

After running, check .git/filter-repo/:

• commit-map — old → new commit mapping
• ref-map — old → new reference mapping
• report.txt — change summary (with --write-report)

Limitations

• Merge simplification still being optimized for complex topologies
• No incremental processing (--state-branch) yet
• Windows path policy fixed to "sanitize" mode

Acknowledgments

Inspired by git-filter-repo by Elijah Newren — the official Git-recommended history rewriting tool.

• Choose git-filter-repo for maximum feature completeness
• Choose filter-repo-rs for performance and memory safety

License

MIT

Links

• GitHub
• Issues
• Discussions

_{Built with ❤️ and 🦀 by Cactusinhand}