git filter-repo 是彻底删除 git 历史中大文件的最可靠工具，因其跨平台、维护活跃、语义清晰，且官方推荐替代已弃用的 git filter-branch 和功能受限的 bfg。
Git 仓库里已经提交过的大文件，光用 git rm 或删掉再提交根本没用——它还牢牢躺在 .git/objects 里，克隆、拉取、检出全得带它走。真要彻底删，必须重写历史，而 git filter-repo 是目前最可靠、最主流的选择。
为什么不用 git filter-branch 或 BFG？
git filter-branch 已被 Git 官方标记为“deprecated”，文档明确建议迁移到 git filter-repo；BFG 虽快，但只支持 Java 环境，且对路径匹配、子模块、引用重写等场景支持较弱。而 git filter-repo 基于 Python，原生跨平台，错误提示清晰，参数语义直观，维护活跃（2026 年仍在持续更新）。
- 不兼容 Windows PowerShell 默认编码？加
--force参数绕过校验 - 运行前必须确保工作区干净，否则会中止并报
Working tree is dirty - 它不会动你当前分支的 HEAD，而是生成全新提交链，所以本地所有分支都会被重写
怎么用 git filter-repo 删除单个大文件？
核心命令就一句，但路径必须写对：相对仓库根目录，且不能带前导 /。比如你要删 docs/manual.pdf，就得这么写：
git filter-repo --path docs/manual.pdf --invert-paths
注意：--invert-paths 表示“保留除此路径外的所有内容”，也就是删除它；如果漏掉这个参数，结果是反的——只留下那个 PDF，其余全丢。
- 想删多个文件？重复写多个
--path，如--path a.bin --path b.zip --invert-paths - 想删整个目录？直接写目录名，如
--path assets/ --invert-paths（末尾斜杠可选，但推荐加上以明确意图） - 不确定文件是否在历史中存在？先用
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | grep '^blob' | sort -k3 -n | tail -10找出最大 blob 对应的路径
删完必须做这三件事，否则别人 clone 还是大
filter-repo 只改本地仓库，远程和协作者完全不受影响。不主动推，等于白干。
- 强制推送所有分支：
git push --force --all（别漏--all，否则只推当前分支） - 强制推送所有 tag：
git push --force --tags（tag 也是引用，不推就不会更新） - 清理本地冗余对象：
git reflog expire --expire=now --all && git gc --prune=now --aggressive，否则.git目录体积不会明显下降
协作者不能 git pull，必须重新 git clone ——这是硬性限制，没有例外。如果团队已有人基于旧历史做了新提交，那些提交会被永久断开，无法自动合并。
容易被忽略的边界情况
真正踩坑的往往不是主流程，而是这些细节：
-
.gitignore里的规则对历史无效，哪怕你早就加了*.mp4，只要它曾被git add过，就得用filter-repo清 - 子模块（submodule）目录下的大文件，
--path不会穿透进去，得进子模块单独处理 - 如果仓库启用了 Git LFS，
filter-repo默认不处理 LFS 指针对象，需额外加--replace-refs delete-no-add配合清理 - Windows 用户遇到
UnicodeDecodeError，多数是因为 commit message 含非 UTF-8 字符，加--mailmap或提前用iconv转换日志
重写历史不是“删文件”而是“再造仓库”，每一步都不可逆。备份 .git 目录本身比备份整个工作区更关键——毕竟代码可以重下，但原始历史一旦覆盖就真的没了。
