Git 历史记录清理：使用 filter-branch 改写提交历史

当你的 Git 历史记录中包含敏感信息、大文件或错误的提交信息时，你可能需要清理这些记录。git filter-branch 是一个强大的工具，可以批量改写历史提交，但使用它需要格外小心。本文将带你通过几个典型场景，学习如何使用 filter-branch 安全地重写 Git 历史记录。

为什么需要清理 Git 历史记录？

Git 历史记录是项目发展的完整日志，但有时它会包含一些不理想的内容：

• 意外提交的密码或 API 密钥
• 误提交的大文件（如二进制文件、日志文件）
• 错误的作者信息或提交信息
• 包含敏感数据的文件

这些内容不仅影响仓库整洁度，还可能带来安全风险。例如，如果在历史中提交过密码，即使后续删除，密码仍会留在历史中，可能被他人获取。

filter-branch 的基本用法

filter-branch 允许你对每个提交执行过滤操作。基本语法如下：

git filter-branch --filter <command> -- --all

其中 --filter 指定要执行的过滤命令，-- --all 表示对所有分支和标签进行操作。

典型场景一：从历史中删除大文件

假设你误提交了一个 100MB 的压缩包，现在想从所有历史提交中移除它。可以使用 --index-filter 来修改索引：

git filter-branch --index-filter 'git rm --cached --ignore-unmatch big-file.zip' -- --all

这个命令会在每个提交中删除 big-file.zip，并忽略不存在的文件（--ignore-unmatch）。执行后，该文件将从所有历史提交中消失。

典型场景二：修改作者信息

如果你需要修改历史中的作者姓名或邮箱，可以使用 --env-filter：

git filter-branch --env-filter '
if [ "$GIT_AUTHOR_EMAIL" = "old@example.com" ]; then
    export GIT_AUTHOR_EMAIL="new@example.com"
    export GIT_AUTHOR_NAME="New Name"
fi
' -- --all

这个脚本会检查每个提交的作者邮箱，如果匹配旧邮箱，就替换为新的信息。注意，你还需要同时处理 GIT_COMMITTER_EMAIL 和 GIT_COMMITTER_NAME，除非你只想修改作者而非提交者。

典型场景三：从历史中移除敏感数据

假设你意外提交了一个包含密码的配置文件，需要彻底清除。可以使用 --tree-filter 或 --index-filter 删除该文件，但更重要的是确保文件内容不会在任何历史版本中残留。推荐使用 --index-filter 结合 git rm 命令，因为它在每个提交上操作索引，效率更高。

git filter-branch --index-filter 'git rm --cached --ignore-unmatch config/passwords.txt' -- --all

执行后，该文件将从所有历史提交中移除，但请注意，如果文件内容已经被他人克隆过，那么这些克隆仍然包含它，你需要提醒所有协作者重新克隆或执行清理。

操作后的清理步骤

filter-branch 会保留原始引用，你需要手动清理以彻底删除旧历史：

1. 删除所有原始引用：git for-each-ref --format='%(refname)' refs/original/ | xargs -n 1 git update-ref -d
2. 强制推送所有分支和标签：git push --force --all && git push --force --tags
3. 清理本地仓库：git reflog expire --expire=now --all && git gc --prune=now

这些步骤会彻底移除被 filter-branch 替换掉的旧对象，释放仓库空间。

注意事项与风险

使用 filter-branch 重写历史是破坏性操作，必须注意：

• 不可逆性：一旦推送，旧历史将无法恢复，除非有备份。
• 影响所有协作者：其他人需要重新克隆或 rebase，否则会破坏仓库。
• 性能问题：对于大型仓库，filter-branch 可能运行缓慢，且会创建大量新对象。
• 备份建议：操作前务必创建完整备份，如 git clone --mirror。

另外，filter-branch 官方文档提示它存在一些缺陷，并推荐使用 git filter-repo 作为替代，但 filter-repo 需要单独安装。对于简单任务，filter-branch 仍然可用。

何时考虑替代方案

如果历史记录问题比较复杂，例如需要合并多个仓库、重命名大量文件，或者需要更精细的控制，考虑使用 git filter-repo。它更快速、更安全，且提供了更多功能。此外，如果只是删除最近一次提交中的文件，可以直接使用 git rm 和 git commit --amend，无需重写整个历史。

结论

git filter-branch 是清理 Git 历史记录的有效工具，适用于删除大文件、敏感信息和修改作者信息等场景。但操作前必须评估风险，做好备份，并通知所有协作者。对于更复杂的需求，可以评估使用更现代的替代工具。

参考资料

• Python 官方文档（用于理解脚本编写）
• MDN Web 开发文档（用于理解版本控制概念）

延伸阅读

• Git 版本控制 技术文章
• 编程开发 专题