首页/开发/Git 与协作速查/git-filter-repo 重写历史
进阶与大仓实践69 条

git-filter-repo 重写历史

官方文档推荐的仓库历史改写工具(独立脚本):可删除文件、替换文本、按目录拆分;要求尽量在新鲜克隆上操作并复核结果。

Git 与协作速查开发更新于 2026-10-12
安装独立脚本放入 PATH 或通过包管理器安装
常用--path / --invert-paths / --replace-text / --path-rename
建议在裸克隆(--no-local)上操作,重写后重新克隆各工作副本

常用示例

常用示例
git clone --no-local /srv/git/app.git app-rewrite
cd app-rewrite
git filter-repo --analyze
git log --oneline -3
重写会改变所有相关提交哈希:需协调团队、更新引用与镜像,并通知所有克隆重新拉取。

易错点

  • 对已有本地改动的仓库执行重写风险高,用新鲜克隆并先跑 --analyze 评估影响
  • 重写后旧对象仍在 reflog/远端引用中,需要过期 reflog 与强推才能彻底清除

数据来源与参考

  • git-filter-repo 官方文档(github.com/newren/git-filter-repo)
  • Git 官方文档:git-filter-branch(迁移提示)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌