从 FreeBSD Ports 代码仓库冻结事件谈起：Git 历史重写，以及如何从此类状况中恢复
内容提要
FreeBSD Ports仓库因误提交150MB二进制文件而冻结并重写Git历史。文章详述了用git filter-branch或fast-export移除违规提交的方法，开发者应对上游force-push的策略，以及reflog恢复技巧。作者认为签名提交非必要，但发布tag应签名，并建议用hook预防此类问题。
延伸解读
历史重写的可复现性为何重要
FreeBSD 在重写历史时，特意要求结果能被第三方复现，并公开了脚本和其 SHA256。这是因为可复现性让社区能独立验证重写过程是否正确，避免管理员暗箱操作或出错。相比之下，用 git rebase -i 重写会改变 committer 信息，导致每次运行结果不同，难以审计。因此，在需要重写公共历史时，应优先选择能保留原始元数据且可复现的方法，如 fast-export/fast-import 或 filter-branch。
filter-branch 的陷阱：按树操作而非按差异
文章指出，用 filter-branch 的 --commit-filter 删除提交节点是常见误区。因为 filter-branch 基于树快照工作，跳过节点不会撤销其内容变更，导致被误提交的二进制文件仍残留在后续提交的树中。正确做法是使用 --index-filter 直接修改索引，或像官方那样用 fast-export 删除整个提交块。这提醒我们，理解工具底层原理比盲目套用命令更重要。
上游强制推送后，本地分支如何安全迁移
当上游重写历史并强制推送后，本地若已有基于旧历史的提交，直接 rebase 会重放大量无关提交，甚至带回被删除的违规文件。正确做法是使用 git rebase --onto 显式指定旧基点和新基点，只重放自己的提交。此外，操作前最好用 tag 或 reflog 备份当前状态，因为 reflog 默认保留 90 天，但若执行 git gc --prune=now 则可能永久丢失。
签名提交的理性看待：发布标签比逐提交签名更实用
文章认为，逐提交签名在历史重写时必然失效，且实际中很少有人真正验证，容易造成虚假安全感。而签名发布标签（tag）则提供了对最终状态的绝对背书，并可作为可信参照哈希。因此，与其追求所有提交都签名，不如在关键发布节点签名，既保留重写历史的灵活性，又确保交付物的完整性。
Q&A
FreeBSD Ports 仓库为什么会被冻结？
因为有人误将一个约150MB的编译二进制文件提交到了仓库中，该文件没有明确的再分发许可，且导致GitHub镜像推送被拒绝。为了彻底移除该文件并消除合规风险，FreeBSD核心团队冻结了仓库推送并重写了Git历史。
为什么简单的 revert 不能解决误提交大文件的问题？
因为Git历史是只增不改的，即使后续提交删除了该文件，旧的commit仍然指向那个blob对象，克隆仓库时依然需要下载这些数据，许可证合规风险也没有解除。
FreeBSD 官方是如何重写 Git 历史的？
FreeBSD官方使用git fast-export将待重放的历史导出为文本流，用sed脚本过滤掉两个涉事commit，再用git fast-import导回。这样保留了原始的作者、提交者及时间戳信息，且过程可复现。
使用 git filter-branch 删除误提交的二进制文件的命令是什么？
命令为：git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch misc/github-copilot-cli/copilot' --prune-empty -- a70c5c3fd44b49eb692a4703fe91a62b37c58ce7..HEAD。该命令会遍历指定范围内的所有commit，从索引中删除该文件，并跳过因删除而变空的commit。
上游 force-push 后，如果本地有未推送的提交，应该如何处理？
应该使用git rebase --onto显式指定旧的基点，将本地改动移植到新的起点上。例如：git rebase --onto f9c90a4f96f0700 0a717e9c118aa6，其中0a717e9c118aa6是旧main，f9c90a4f96f0700是新main。直接rebase origin/main会尝试重放所有旧提交，可能重新引入被删除的文件。
如果 git rebase 搞砸了，如何恢复？
可以使用git reflog查看HEAD的移动记录，找到rebase之前的状态标识符（如HEAD@{3}），然后执行git reset --hard HEAD@{3}强行切回。但reflog记录默认保留90天（可达对象）或30天（不可达对象），过期后可能无法恢复。
作者对 signed commit 和 signed tag 的看法是什么？
作者认为signed commit是不必要的，因为历史改写会导致签名失效，且实际中很少有人逐个检查commit签名，容易产生虚假的安全感。但signed tag是必要的，因为tag是对最终状态的终审，提供了可信的参照hash，在关键交付节点提供验证保证。
如何预防类似误提交大文件的问题？
可以在服务器和客户端部署hook，在push或commit时按文件尺寸和类型进行拦截。FreeBSD官方也计划在服务端添加尺寸限制hook。
