Git 巨大失误案例记录 (2026-05-01)

Git 巨大失误案例记录 (2026-05-01)

事故概述

清理 Git 仓库大文件时，使用git filter-branch` 操作失误。

---

事故经过

第1步：发现问题

• 远程仓库 大小超过 1024MB
• 本地仓库大小：127.22 MiB
• 最大文件：uite_Setup.exe (54.41 MB)

第2步：尝试清理

git verify-pack -v .git\objects\pack\*.idx
git rev-list --objects --all | sort -k 3 -n -r | head -20

第3步：使用 filter-branch 重写历史

git filter-branch --force --index-filter "git rm -r --cached --ignore-unmatch te_Setup.exe Out/ setup/ Plugins/" --prune-empty --tag-name-filter cat -- --all

第4步：删除备份引用（错误！）

git update-ref -d refs/original/refs/heads/master
git update-ref -d refs/original/refs/remotes/origin/master

第5步：执行 GC

git reflog expire --expire=now --all
git gc --prune=now --aggressive

第6步：尝试推送（失败）

git push -f origin master

失败原因：远程仓库还有旧的大对象未清理，超过 Gitee 1024MB 限制

---

清理前后对比

项目	清理前	清理后
Git 仓库大小	127.22 MiB	1.21 MiB
Git 对象数	974	498
最大文件	ite_Setup.exe (54.41 MB)	g.doc (0.29 MB)
大文件已从历史中删除	setup/ (22个文件	已删除
Plugins/ (48个文件	已删除
Out/ (374个文件	已删除

---

⚠️ 教训总结

✅ 正确做法

1. 先备份！

   # 备份整个 .git 目录
   xcopy .git .git-backup /E /I /H /Y

2. 使用 BFG Repo-Cleaner！

   # 下载 BFG（比 filter-branch 更安全、更快
   java -jar bfg.jar --delete-files uite_Setup.exe

3. 不要删除备份引用！

   • `refs/original/ 是 filter-branch 的安全网，后悔还可以恢复

4. 远程仓库先 GC！

   • Gitee 上执行 GC 清理历史对象
   • 再强制推送

❌ 错误做法

1. 不要直接删除 refs/original/
2. 不要没有备份就操作
3. 不要忽略远程仓库没清理就推送
4. 不要用 git rm 不带 --cached（虽然这次带了，但用户担心）

---

教训文档

• [v2-remaining-work-plan.md
• [yeb-v2-code-review-plan.md
• [code-review-report-plan.md