github.com/Cactusinhand/filter-repo-rs @v1.0.5

# filter-repo-rs

English | 中文

🦀 快速、安全的 Git 历史重写工具 — 清除密钥、瘦身仓库、重构路径。

解决什么问题？

😱 痛点	✅ 一条命令
密钥/Token 不小心提交了	filter-repo-rs --replace-text secrets.txt --sensitive
需要检测历史中的潜在敏感信息	filter-repo-rs --detect-secrets --dry-run
仓库太大，clone 半天	filter-repo-rs --max-blob-size 10M
想把子目录拆成独立仓库	filter-repo-rs --subdirectory-filter frontend
批量改 tag/branch 前缀	filter-repo-rs --tag-rename v1.:legacy/v1.
删除历史中的某个文件	filter-repo-rs --path docs/secret.md --invert-paths
统一作者/提交者身份信息	filter-repo-rs --mailmap .mailmap
分析仓库健康度	filter-repo-rs --analyze

快速示例

清除泄露的密钥

# 1. 先备份（强烈推荐）
filter-repo-rs --backup

# 2. 编写替换规则 (secrets.txt)
#    API_KEY_12345==>REDACTED
#    regex:password\s*=\s*"[^"]+==>[REMOVED]

# 3. 清洗所有历史
filter-repo-rs --replace-text secrets.txt --sensitive --write-report

# 4. 强制推送
git push --force --all && git push --force --tags

自动检测潜在敏感信息

# 扫描可达历史中的潜在敏感信息
filter-repo-rs --detect-secrets --dry-run

# 需要时可追加自定义正则（可重复）
filter-repo-rs --detect-secrets \
  --detect-pattern 'ZZZ-CUSTOM-SECRET-[0-9]{4}' \
  --detect-pattern 'my_internal_token_[A-Za-z0-9_-]{16,}' \
  --dry-run

# 输出文件: detected-secrets.txt
# 审核检测结果后再执行正式清理:
filter-repo-rs --replace-text detected-secrets.txt --sensitive --write-report

仓库瘦身

# 先分析
filter-repo-rs --analyze

# 移除超过 10MB 的文件
filter-repo-rs --max-blob-size 10M --write-report

说明：--analyze 中依赖历史遍历的 blob/路径指标只统计可达对象；悬空/不可达对象会被跳过。

重构路径

# 提取子目录为新根
filter-repo-rs --subdirectory-filter src/frontend

# 将根目录移入子目录
filter-repo-rs --to-subdirectory-filter packages/core

# 批量重命名路径
filter-repo-rs --path-rename old/:new/

重写作者/提交者身份

# 方案 A: 使用 .mailmap 规则
# 格式: New Name <new@email> <old@email>
filter-repo-rs --mailmap .mailmap --write-report

# 方案 B: 使用显式规则文件
# author.txt / committer.txt: oldName==>newName
# email.txt: oldEmail==>newEmail
filter-repo-rs --author-rewrite author.txt \
  --committer-rewrite committer.txt \
  --email-rewrite email.txt \
  --write-report

说明：--mailmap 优先级更高。若传入 --mailmap，则会忽略 --author-rewrite、--committer-rewrite、--email-rewrite。

安全第一

参数	用途
--backup	重写前创建带时间戳的备份
--dry-run	预演，不实际修改
--write-report	生成变更审计报告
--sensitive	覆盖所有 refs（含远端）
--path-compat-policy	Windows 路径兼容策略（sanitize|skip|error）
--detect-secrets	检测可达历史中的潜在敏感信息

安装

环境要求： Git、Rust 工具链 (stable)、Linux/macOS/Windows

# 从 crates.io 安装（推荐）
cargo install filter-repo-rs

# 或从源码构建
cargo build -p filter-repo-rs --release
# 产物位置: target/release/filter-repo-rs

交叉编译

# 使用构建脚本（推荐）
./scripts/build-cross.sh                    # 所有平台
./scripts/build-cross.sh x86_64-apple-darwin # 指定目标

# 或手动使用 cross
cargo install cross --git https://github.com/cross-rs/cross
cross build --target x86_64-unknown-linux-gnu --release -p filter-repo-rs

平台	目标
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. 清除文件内容中的敏感信息

# secrets.txt - 支持字面值和正则
SECRET_TOKEN==>REDACTED
regex:(API|TOKEN|SECRET)[A-Za-z0-9_-]+==>REDACTED

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

1. 清洗提交消息中的敏感信息

# messages.txt
password==>[removed]

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

提示：若要删除 Co-authored-by 尾注，可在 messages.txt 中加入规则 regex:(?m)^\s*Co-authored-by:.*$==>。

1. 重写作者/提交者身份历史

# .mailmap
Jane Doe <jane@company.com> <jane@users.noreply.github.com>

filter-repo-rs --mailmap .mailmap --write-report

# author-rules.txt / committer-rules.txt
old name==>new name

# email-rules.txt
old@email.com==>new@email.com

filter-repo-rs --author-rewrite author-rules.txt \
  --committer-rewrite committer-rules.txt \
  --email-rewrite email-rules.txt \
  --write-report

1. 移除大文件 / 仓库瘦身

# 按大小阈值
filter-repo-rs --max-blob-size 5M --write-report

# 按指定 blob ID
filter-repo-rs --strip-blobs-with-ids big-oids.txt --write-report

1. 批量重命名 tag/branch

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

1. 重构目录结构

# 提取子目录为新根
filter-repo-rs --subdirectory-filter frontend

# 将根移入子目录
filter-repo-rs --to-subdirectory-filter app/

# 重命名路径前缀
filter-repo-rs --path-rename old/:new/

1. 从历史中删除特定文件

# 单个文件
filter-repo-rs --path secrets/production.env --invert-paths

# 按 glob 模式
filter-repo-rs --path-glob "*.log" --invert-paths

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

1. CI 健康检查

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

可达性说明：分析输出中对象/路径相关的指标仅统计从 refs 可达的对象。

在 .filter-repo-rs.toml 配置阈值：

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

备份与恢复

# 备份产物: .git/filter-repo/backup-YYYYMMDD-HHMMSS.bundle
filter-repo-rs --backup

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

产物

运行后查看 .git/filter-repo/：

• commit-map — 旧提交 → 新提交映射
• ref-map — 旧引用 → 新引用映射
• report.txt — 变更摘要（需 --write-report）
• windows-path-report.txt — Windows 路径兼容详情（当发生 sanitize/skip 时自动生成）

限制

• 合并简化策略仍在优化，复杂拓扑可能需手动处理
• 暂不支持增量处理（--state-branch）
• --path-compat-policy 当前仅在 Windows 主机上生效

致谢

本项目受 git-filter-repo（Elijah Newren 开发）启发 — Git 官方推荐的历史重写工具。

• 选择 git-filter-repo — 需要最完整的功能
• 选择 filter-repo-rs — 看重性能和内存安全

许可证

MIT

链接

• GitHub
• Issues
• Discussions
• 测试策略

---

_{Built with ❤️ and 🦀 by Cactusinhand}