π¦ Fast, safe Git history rewriting in Rust β remove secrets, slim repos, restructure paths.
| π± Your Problem | β One Command |
|---|---|
| Leaked API keys/tokens in history | filter-repo-rs --replace-text secrets.txt --sensitive |
| Repo too large, clone takes forever | filter-repo-rs --max-blob-size 10M |
| Need to extract subdirectory as new repo | filter-repo-rs --subdirectory-filter frontend |
| Bulk rename tags/branches | filter-repo-rs --tag-rename v1.:legacy/v1. |
| Remove specific file from all history | filter-repo-rs --path docs/secret.md --invert-paths |
| Analyze repo health | filter-repo-rs --analyze |
# 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# Analyze first
filter-repo-rs --analyze
# Remove files larger than 10MB
filter-repo-rs --max-blob-size 10M --write-report# 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/| Flag | Purpose |
|---|---|
--backup |
Create timestamped bundle before rewriting |
--dry-run |
Preview changes without modifying anything |
--write-report |
Generate audit report of all changes |
--sensitive |
Cover all refs including remotes |
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-rsCross-platform builds
# 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| Platform | Target |
|---|---|
| Linux x64 | x86_64-unknown-linux-gnu |
| Linux ARM64 | aarch64-unknown-linux-gnu |
| macOS Intel | x86_64-apple-darwin |
| macOS Apple Silicon | aarch64-apple-darwin |
| Windows x64 | x86_64-pc-windows-msvc |
1. Remove secrets from file contents
# 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-report2. Clean sensitive commit messages
# messages.txt
password==>[removed]
filter-repo-rs --replace-message messages.txt --write-report3. Remove large files / slim repo
# 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-report4. Rename tags/branches in bulk
filter-repo-rs --tag-rename v1.:legacy/v1.
filter-repo-rs --branch-rename feature/:exp/5. Restructure directory layout
# 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/6. Remove specific files from history
# 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-paths7. CI health checks
filter-repo-rs --analyze --analyze-jsonConfigure thresholds in .filter-repo-rs.toml:
[analyze.thresholds]
warn_blob_bytes = 10_000_000
warn_commit_msg_bytes = 4096# Backup creates: .git/filter-repo/backup-YYYYMMDD-HHMMSS.bundle
filter-repo-rs --backup
# Restore
git clone /path/to/backup.bundle restored-repoAfter running, check .git/filter-repo/:
commit-mapβ old β new commit mappingref-mapβ old β new reference mappingreport.txtβ change summary (with--write-report)
- Merge simplification still being optimized for complex topologies
- No incremental processing (
--state-branch) yet - Windows path policy fixed to "sanitize" mode
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
Built with β€οΈ and π¦ by Cactusinhand