git-filter-repo 清理 Git 历史大文件:本地清理 + 远程同步 + 服务端 GC 三步走

背景

zdq 仓库膨胀到 2.7GB,根因是 .git.backup 目录(含 2.9GB pack 备份文件)曾被误提交进历史。本条目记录完整清理流程与 Gitee 侧的收尾注意事项。

核心内容

定位

• git count-objects -vH 看松散对象与打包对象大小;松散对象大、pack 小,先 git gc 打包再看。
• 用 git-filter-repo 扫描历史找出大文件路径。本次元凶:.git.backup 里的 2.9GB pack 文件。
• 注意:误提交的往往就是 .git.backup 这类备份目录——备份 .git 不要放在仓库工作区内。

清理与推送

1. git filter-repo --path .git.backup --invert-paths 从历史彻底删除。
2. 重新打包验证:本次从 2.7GB(数万对象)降到 1.54MB / 489 个对象。
3. filter-repo 会移除 remote,需重新添加后强制推送。

Gitee 远程收尾(容易漏的一步)

• 强推后 Gitee 页面仍显示旧大小(本次显示 1172MB),因为服务端 GC 未执行。
• 需在 Gitee 后台手动触发:仓库设置 → 存储库 GC(GC 前超配额还会限制推送次数)。
• GC 后可用浅克隆验证:git clone --depth 1 到临时目录,看 .git 大小(本次约 1.5MB,确认恢复正常)。
• 查看远程仓库占用:仓库设置 → 仓库状态 页面直接显示"仓库大小 / 配额"。

原文链接

提炼自 inbox/trae/20260424_修复并导入15分钟数据.md