历史改写工具怎么用
官方文档推荐的仓库历史改写工具，是一个独立脚本：可以删除文件、替换文本、按目录拆分仓库。使用要求是尽量在新鲜克隆上操作并复核结果，因为它会重写所有相关提交的哈希与内容。
基本信息
| 安装方式 | 把独立脚本放入命令行路径，或通过包管理器安装 |
|---|---|
| 常用参数 | --path 保留路径、--invert-paths 反向排除、--replace-text 替换文本、--path-rename 重命名路径 |
| 前置分析 | --analyze 生成仓库统计，用于评估改写影响 |
| 操作位置 | 在裸克隆上执行，改写完成后各工作副本重新克隆 |
| 配套收尾 | 清理陈旧引用、回收对象、强推并通知团队 |
典型使用场景
- 从历史中彻底删除误提交的密钥或大文件
- 按目录把单一仓库拆分成多个仓库
- 合并多个仓库时统一目录前缀
- 替换历史中的邮箱或内部域名
- 清理过大的历史以加快克隆速度
常用示例
常用示例
git clone --no-local /srv/git/app.git app-rewrite # 在裸克隆上操作
cd app-rewrite
git filter-repo --analyze # 先看统计评估影响
git filter-repo --path configs/prod.env --invert-paths # 删除该文件及其历史
git filter-repo --replace-text replacements.txt # 批量替换敏感文本
git log --oneline -3 # 核对改写后的历史常用参数
| 参数 | 作用 |
|---|---|
| --path | 只保留指定路径的内容 |
| --invert-paths | 排除指定路径，用于删除文件 |
| --replace-text | 按规则文件替换历史中的文本 |
| --path-rename | 调整历史中的目录或文件路径 |
改写会改变所有相关提交的哈希，因此要先冻结推送、协调时间窗，并在完成后让所有工作副本重新克隆或按说明重置。
对已有本地改动的仓库直接改写风险很高，务必使用新鲜克隆，并保留原始仓库作为回退依据。
动手前先用统计功能评估影响范围，能把改动会波及哪些路径与提交提前说清楚，减少事后返工。
正式操作前在副本上完整演练一遍，包含推送与清理步骤，可以把工具报错与遗漏的引用提前暴露出来。