git-filter-repo

重写 Git 历史的现代工具

补充说明

git-filter-repo 用于删除敏感文件、重写作者信息、拆分仓库和清理大文件。它会改写提交哈希，属于破坏性操作，必须在协调后对镜像执行。

常用示例

git filter-repo --analyze
git filter-repo --path secret.env --invert-paths
git filter-repo --path docs/ --invert-paths
git filter-repo --replace-text replacements.txt
git filter-repo --mailmap .mailmap
git filter-repo --strip-blobs-bigger-than 10M
git filter-repo --force

replacements.txt：

old-password==>REDACTED
old-email@example.com==>new-email@example.com

易错点与排错

• 先在全新克隆或镜像上操作；不要在唯一的工作副本上直接跑。
• 会改写所有受影响的提交哈希；团队必须同时重置本地分支。
• 运行后默认移除 origin，需要手动重新添加并 force push。
• 旧对象仍可能通过 reflog、缓存或平台 SHA 访问；要清理并联系平台。
• --path 和 --invert-paths 组合语义要确认，避免删错目录。
• .mailmap 只改显示映射；要真正改作者信息用 --mailmap 的 filter-repo 语义。
• 大文件清理后要 gc，并确认 LFS 指针没有被误删。
• 公开仓库的历史重写会影响所有 fork 和外部链接，提前公告。

相关命令

• git — 版本控制
• git-reflog — 恢复误操作
• git-bundle — 操作前备份