Skip to content

README.zh-CN.md

Latest commit

 

History

History
322 lines (228 loc) · 8.24 KB

README.zh-CN.md

File metadata and controls

322 lines (228 loc) · 8.24 KB
Raw

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
--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
2. 清洗提交消息中的敏感信息 
# messages.txt
password==>[removed]

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

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

3. 重写作者/提交者身份历史 
# .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
4. 移除大文件 / 仓库瘦身 
# 按大小阈值
filter-repo-rs --max-blob-size 5M --write-report

# 按指定 blob ID
filter-repo-rs --strip-blobs-with-ids big-oids.txt --write-report
5. 批量重命名 tag/branch 
filter-repo-rs --tag-rename v1.:legacy/v1.
filter-repo-rs --branch-rename feature/:exp/
6. 重构目录结构 
# 提取子目录为新根
filter-repo-rs --subdirectory-filter frontend

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

# 重命名路径前缀
filter-repo-rs --path-rename old/:new/
7. 从历史中删除特定文件 
# 单个文件
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
8. 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

链接

Built with ❤️ and 🦀 by Cactusinhand