Git提交并且已经push大文件，出现GH001: Large files detected警告，remote: warning: See https://gh.io/lfs for more information. this is larger than GitHub’s recommended maximum file size of 50.00 MB怎么清理。本文提供单人仓库重写历史、重建分支、gitignore配置多种方案，适合Git新手，讲解git已经提交push大文件怎么清除历史、git仓库清理历史大文件的完整操作。
很多Git新手都会踩同一个坑：本地不小心add、commit了超大文件，还执行了git push推送到GitHub远程仓库，之后收到GH001大文件警告。很多人以为直接在最新提交删掉文件就完事，但是Git会保留全部提交历史，大文件依然存在仓库历史记录里，GitHub持续抛出大文件警告，仓库体积无法缩小。 还有一种更麻烦的场景：当初提交大文件之后，你又继续做开发、生成了很多后续提交，隔了很久才发现历史里藏着这个大文件，这时简单修改最近一次提交的方式已经无法使用，必须对整条提交历史进行清理。
报错原文：
remote: warning: See [https://gh.io/lfs](https://gh.io/lfs) for more information.
this is larger than GitHub's recommended maximum file size of 50.00 MB
remote: warning: GH001: Large files detected. You may want to try Git Large File Storage - [https://git-lfs.github.com](https://git-lfs.github.com).
如果你正在搜索git push之后删除大文件、git已经提交push大文件怎么清除历史、git强制推送覆盖远程仓库这类问题，本文针对单人独立仓库场景，提供三套方案，从简单重建仓库、修改最近一次提交、完整重写历史，按需选择。多人协作仓库不建议强制重写历史，文末也会说明限制。
前置重要提醒
- 强制推送（git push -f）会覆盖远程分支历史，只适合自己一个人使用的仓库；多人共用仓库不要使用本文强制推送方案。
- 操作前建议备份本地代码目录，防止误操作丢失代码。备份可以直接复制整个项目文件夹，不要在项目内部复制，避免产生新文件被Git跟踪。
- 只在本地确认文件清单、配置好.gitignore之后，再执行强制推送。
- 单纯新增一次提交删除文件，不能消除历史里的大文件，GitHub警告依旧存在。
- .gitignore只能阻止文件被新加入版本库，无法自动清理已经存在于Git历史中的文件，两个操作需要配合使用。
- GitHub有文件扫描延迟，清理完成后不要立刻以页面显示大小判断是否生效。
- 执行历史重写操作前，确认本地工作区干净，没有未commit的改动，避免改动丢失。可以使用
git status检查工作区状态。 - 如果大文件存在于很早的历史提交，并且该提交之后已经产生大量新提交，
git commit --amend不再适用，优先使用filter-repo清理全量历史。
方案一：最简方案，重建孤立分支，清空全部历史（适合：不想要旧历史，只想保留当前干净代码）
如果你不在乎过往提交记录，只想把当前干净代码作为全新仓库内容推上去，这个方案最简单，适合新手。
重点提醒：执行add之前，必须确认两件事：不需要的大文件已经被删除，或者已经写好.gitignore规则，否则本地目录里的大文件会被重新提交，依旧触发GH001警告，很多人在这里反复踩坑。
1. 新建无历史的孤立分支
git checkout --orphan new-main
2. 编辑.gitignore，写入忽略规则，阻止临时文件、大文件被提交
# 锁文件
*.lock
# bak备份文件
*.bak
# 缓存、状态目录
*/.state/
# 日志文件
*.log
# 压缩包
*.zip
*.tar
*.gz
3. 将当前目录文件加入暂存区，git会自动跳过.gitignore中匹配的文件
git add .
4. 生成全新初始提交
git commit -m "init: clean repo, remove large files and add ignore rules"
5. 删除原来main分支
git branch -D main
6. 将新分支重命名为main
git branch -m main
7. 强制推送到远程
git push -f origin main
执行完成后，远程main分支只有这一条提交记录，旧历史全部清除。只要ignore配置正确，大文件不会再次进入仓库。
方案二：只修改最后一次提交，移除大文件（适合：大文件只在最近一次commit里）
如果大文件仅仅是刚刚这一次提交才加入，更早的历史提交都没有包含大文件，可以用amend修改本次提交，不需要清空全部历史。这是修复刚提交大文件最轻量的方式。
重要限制：如果大文件是在更早的提交加入，并且该提交之后已经多次提交新代码，不要使用这个方案，amend只能修改最后一条提交记录，无法回溯修改历史中旧的提交。
1. 先把不需要纳入版本管理的文件从git跟踪中移除，--cached 参数代表只从版本库移除，保留本地磁盘文件
git rm --cached 大文件路径
如果需要同时移除多个文件，可以空格分隔多个文件路径；如果要移除整个目录，在路径末尾加斜杠。
2. 编辑.gitignore，添加忽略规则
# 锁文件
*.lock
# bak备份文件
*.bak
# 缓存、状态目录
*/.state/
# 日志文件
*.log
# 压缩包
*.zip
*.tar
*.gz
3. 把ignore变更加入暂存，修改上一次提交
git add .gitignore
git commit --amend --no-edit
4. 强制推送覆盖远程
git push -f origin main
局限：如果大文件存在于更早的历史提交中，这个方案无效，GitHub依旧报GH001警告。
方案三：git filter-repo 工具，从全部历史里删除指定文件/目录（推荐，保留提交历史，只删掉大文件）
适合场景：提交大文件之后，后续又提交了很多次代码，隔了一段时间才发现历史里存在大文件，想要保留全部正常提交记录，只清除所有历史版本里的大文件。优先使用git filter-repo，这是官方推荐替代老旧filter-branch的工具，也是git仓库清理历史大文件最常用的方案。
注意：不要继续使用git filter-branch，该命令已经被Git官方标记废弃，效率低而且容易产生冗余对象。
Ubuntu安装filter-repo：
sudo apt install git-filter-repo
1. 先查看当前被git跟踪的文件，筛选需要清理的文件
git ls-files | grep -E "\.bak|\.lock|\.state"
2. 执行清理命令，–path后面填写路径，–invert-paths代表删除该路径。可以多次执行这条命令，清理多个不同文件/目录。filter-repo会自动遍历整条提交历史，无论大文件在哪一次提交，都会被清除，并且自动重写后续所有提交的哈希值。
git filter-repo --path 目标文件或者目录 --invert-paths
. 清理完成后，添加.gitignore防止再次误提交
cat >> .gitignore << EOF
*.lock
*.bak
*/.state/
*.log
*.zip
*.tar
*.gz
EOF
git add .gitignore
git commit -m "add gitignore, exclude temp and state files"
4. 强制推送远程
git push -f origin main
补充说明：filter-repo执行完成后，所有在该分支上的提交哈希都会变化，这是正常现象，因为Git修改了历史快照。单人仓库可以正常强制推送。
配套：通用.gitignore模板，预防以后再次误提交大文件
# 锁文件
*.lock
# bak备份文件
*.bak
# 缓存/状态目录
*/.state/
# 日志文件
*.log
# 大体积导出json
*.json
# 压缩包
*.zip
*.tar
*.gz
# 视频、镜像
*.iso
*.mp4
# 数据库备份
*.sql
*.dump
# 软件编译产物
node_modules/
dist/
build/
方案对比，快速选型
方案一（orphan重建分支）：上手最简单，所有旧历史全部清空，适合历史不重要的项目。风险点在于忘记配置ignore，导致大文件重新提交。 方案二（amend修改最近提交）：只处理最后一次提交，历史保留，仅限大文件刚提交、还没有新增其他提交的场景。 方案三（filter-repo）：保留提交历史，从全历史删除文件，不受大文件提交时间限制，哪怕大文件在很早之前提交、后面有大量新增提交，都可以清理，功能最强。
FAQ
Q：我已经在代码里删掉大文件了，为什么GH001警告还在？
A：Git的删除提交只是新增一条记录标记删除，文件blob对象仍然保存在仓库历史中，GitHub扫描历史依然能检测到大文件，必须重写历史。单纯删除文件的提交，解决不了历史遗留大文件的问题。
Q：大文件是很早提交的，后面还有很多提交，我直接删文件提交行不行？
A：不行。新增删除文件的提交只是在最新版本移除文件，历史快照里的大文件还完整保留，GitHub扫描历史依旧会触发GH001警告，仓库大小不会下降。这种场景只能使用filter-repo或者清空历史的方案。
Q：我用 –orphan 清空历史之后，为什么还是报 GH001 大文件警告？
A：最常见原因：本地目录里的大文件还存在，并且没有配置.gitignore。执行git add .的时候，大文件会被重新提交进新版本，GitHub扫描依旧检测到大文件。解决办法：要么手动删除本地无用大文件，要么提前配置.gitignore，再执行add操作。
Q：多人协作仓库能不能git push -f？
A：强烈不建议。强制推送改写历史后，其他协作者本地分支和远程历史断裂，拉取代码会出现大量冲突，单人仓库才适合上面的操作。多人场景正确做法：新增一次提交删除文件，或者使用Git LFS托管大文件。
Q：什么是Git LFS？什么时候选LFS？
A：Git LFS用来专门托管大文件，文件本身不存入Git对象库。如果你确实需要把这个大文件纳入版本跟踪，而不是直接丢弃，就安装Git LFS托管；如果文件是临时缓存、日志、备份文件，直接加到gitignore并且清理历史即可。 Git LFS适合持续需要版本管理的二进制文件，例如安装包、素材、模型文件。
Q：执行filter-repo之后本地仓库体积没变？
A：filter-repo修改历史之后，旧对象还存在本地git引用中，可以手动执行垃圾回收，释放本地磁盘空间：
git reflog expire --expire=now --all
git gc --prune=now --aggressive
Q：GitHub仓库页面看仓库大小更新延迟？
A：GitHub统计仓库大小有缓存，清理历史并强制推送后，等待一段时间才会刷新仓库体积统计，不要刚推送完就反复刷新页面判断是否生效。
Q：我不想改写历史，有没有不使用git push -f的办法？
A：有，但是治标不治本。你可以新增一次提交删除大文件并且写入.gitignore，不做强制推送。这个方式不会破坏历史，适合多人仓库。缺点是历史里的大文件blob还存在，GitHub会持续输出GH001警告，仓库下载包体积也不会变小。适合可以接受警告、只是不想后续继续提交大文件的场景。
Q：执行git push -f的时候提示被远程拒绝怎么办？
A：GitHub仓库默认开启分支保护规则，会拦截强制推送。进入仓库设置，找到分支保护规则，临时关闭main分支保护，推送完成后可以重新开启。私有仓库和个人仓库很容易遇到这个限制。
Q：怎么验证大文件是否真的从历史清除干净？
A：可以使用这个命令遍历历史，检索指定文件名，确认无匹配结果：
git log --all -- '*大文件名称*'
无输出代表历史中不再存在该文件记录。
总结
遇到GH001 Large files detected警告，核心逻辑是区分两件事：文件要不要保留版本，以及大文件是什么时候提交的。如果大文件提交之后已经产生大量后续提交，想要保留项目提交记录，优先选择filter-repo进行全历史清理；不需要保留历史记录可以选择孤立分支重建；只有刚提交还没有新增改动的情况，才适合amend修改最近提交。
单人仓库自由度高，可以选择重建分支或者filter-repo清理历史；多人仓库尽量避免重写历史。.gitignore是长期防护手段，清理历史是修复已经提交的问题，两个步骤搭配起来，才能彻底解决git push大文件之后的GH001报错。
