技能介绍

需要解决的问题

当仓库已经推送到远端，或者团队开始 clone 之后，才发现历史里混入了不该存在的东西：硬编码的 API key、误提交的 .env、被顺手 add 进仓库的几百 MB 构建产物，或者一次错误的子树拆分留下了杂乱的提交记录。git rm 只能处理工作区，常规的 git filter-branch 脚本脆弱且难维护，尤其在涉及大量提交和多个远端引用时容易出错。

技能如何工作

技能基于 git-filter-repo，它会先分析仓库历史，定位需要清除的路径、文件模式或提交范围。随后构建一条 git filter-repo 命令，用 --path 匹配目标文件，--invert-paths 反向保留其余内容，或者用 --subject-filter 改写提交信息。命令执行后，历史中的所有匹配路径会被彻底移除，相关 blob 和树对象也会被回收。

技能还会生成一份后续检查清单，覆盖：

使用 git push --force-with-lease 更新远端分支
通知协作者重新 clone，避免本地旧历史再次被推送
检查 GitHub 或其他平台的 PR、Issue 中是否还残留引用
如有必要，吊销已泄露的凭据

适用边界与注意点

重写历史是破坏性操作，执行前必须确认没有其他人正在基于当前历史工作。git-filter-repo 要求 git >= 2.36.0 和 python3 >= 3.6，并且仓库应先进行完整备份。对于已经 fork 或被大量引用的仓库，重写后的 SHA 变更会导致 diff 失效，需要同步清理外部 CI 缓存和依赖该仓库的下游项目。