GitHub GH001 报错：意外推送超大文件，完整清理仓库历史、删除大文件教程
内容提要
提交并推送大文件会触发GH001警告，仅删除文件无效，因为大文件仍保留在Git历史中。单人仓库可采用三种方案：重建孤立分支以清空历史；用amend修改最近一次提交；用git filter-repo从全部历史中删除指定文件并保留提交记录。清理后需配置.gitignore防止再次误提交，并强制推送。多人仓库不建议重写历史。
延伸解读
为什么删了文件警告还在？
GH001 警告的根源是 Git 历史中仍保留大文件的 blob 对象。即使你在最新提交中删除了文件，Git 也只是新增一条删除记录，历史快照里的大文件依然存在，GitHub 扫描历史时仍会检测到并持续警告。因此，单纯删除文件无法缩小仓库体积，必须重写历史才能彻底清除。
三种清理方案怎么选？
方案一（孤立分支重建）适合不关心旧提交记录、只想保留当前代码的场景，操作最简单但会清空全部历史；方案二（amend）仅适用于大文件刚提交且之后没有新提交的情况；方案三（filter-repo）能保留提交历史并从全历史删除指定文件，不受大文件提交时间限制，功能最强，适合大文件提交后已有大量后续提交的场景。
强制推送的风险与限制
强制推送（git push -f）会覆盖远程分支历史，仅适用于单人仓库。多人协作仓库重写历史会导致其他协作者本地分支与远程断裂，拉取时产生大量冲突，因此不建议使用。此外，GitHub 默认分支保护规则可能拦截强制推送，需临时关闭保护；清理后 GitHub 仓库大小统计有延迟，不要立即以页面显示判断是否生效。
清理后如何防止再次误提交？
清理历史只是修复已发生的问题，长期防护需配合 .gitignore。在重建分支或 filter-repo 清理后，务必配置忽略规则（如 *.lock、*.bak、*.log、*.zip 等），并确认本地无用大文件已删除，否则执行 git add . 时大文件会被重新提交，再次触发 GH001 警告。.gitignore 只能阻止新文件被跟踪，无法自动清理历史，两者需搭配使用。
Q&A
Git push 后收到 GH001 大文件警告，为什么直接在最新提交里删除文件没用？
因为 Git 会保留全部提交历史，大文件仍然存在于历史记录中。单纯新增一次删除文件的提交只是标记删除，文件 blob 对象还在仓库历史里，GitHub 扫描历史依然能检测到大文件，所以警告不会消失，仓库体积也不会缩小。必须重写历史才能彻底清除。
单人仓库清理大文件历史有哪几种方案？分别适合什么场景？
有三种方案：1）重建孤立分支（git checkout --orphan）清空全部历史，适合不想要旧历史、只想保留当前干净代码的项目；2）git commit --amend 修改最近一次提交，仅适合大文件刚提交且没有后续新提交的情况；3）git filter-repo 从全部历史中删除指定文件并保留提交记录，适合大文件提交后又有大量后续提交、想保留历史的情况。
使用 git filter-repo 清理历史大文件的具体步骤是什么？
1）安装：sudo apt install git-filter-repo；2）查看跟踪文件：git ls-files | grep -E "\.bak|\.lock|\.state"；3）执行清理：git filter-repo --path 目标文件或目录 --invert-paths（可多次执行清理多个路径）；4）添加 .gitignore 防止再次误提交；5）强制推送：git push -f origin main。注意 filter-repo 会重写所有提交哈希，这是正常现象。
执行 git push -f 时被远程拒绝怎么办？
GitHub 仓库默认开启分支保护规则，会拦截强制推送。需要进入仓库设置，找到分支保护规则，临时关闭 main 分支的保护，推送完成后再重新开启。私有仓库和个人仓库很容易遇到这个限制。
清理历史后如何验证大文件是否真的从 Git 历史中清除了？
可以使用命令 git log --all -- '*大文件名称*' 遍历历史检索指定文件名，如果没有输出，代表历史中不再存在该文件记录。另外，filter-repo 执行后本地仓库体积可能没变，因为旧对象还在引用中，可以执行 git reflog expire --expire=now --all 和 git gc --prune=now --aggressive 释放空间。GitHub 页面仓库大小有缓存延迟，不要刚推送完就立即判断。
多人协作仓库遇到 GH001 警告可以强制推送重写历史吗？
强烈不建议。强制推送改写历史后，其他协作者本地分支和远程历史断裂，拉取代码会出现大量冲突。多人场景正确做法是：新增一次提交删除文件并写入 .gitignore，或者使用 Git LFS 托管大文件。如果大文件需要持续版本管理（如安装包、素材、模型文件），应使用 Git LFS；如果是临时缓存、日志、备份文件，直接加入 .gitignore 并清理历史即可。
