git filter-repo 清理大文件或敏感内容比 git filter-branch 快 5–10 倍且能真正删干净，但必须在所有协作者同步前完成，否则引发 push 拒绝、历史错乱或本地分支丢失；git rm 和 git commit --amend 仅影响最新提交，无法删除历史中的 blob 对象。
直接说结论：用 git filter-repo 清理大文件或敏感内容，比 git filter-branch 快 5–10 倍，且能真正删干净——但必须在所有协作者同步前完成，否则会引发 push 拒绝、历史错乱甚至本地分支丢失。
为什么不能只用 git rm 或 git commit --amend
因为 git rm 只删工作区和暂存区，不碰历史提交里的 blob；git commit --amend 只改最新一次提交的 parent，老提交里仍完整存着大文件或密钥。只要有人执行 git log --all --oneline 再加 git show <old-commit>:<path></path></old-commit>，就能原样还原出你“以为删掉了”的东西。
常见错误现象：
- 执行
git rm large-file.zip && git commit -m "remove"后，.git目录大小几乎不变 - GitHub/GitLab 页面上点“Delete this file”，只是新增一个空提交，历史记录里仍可查到该文件所有版本
- 用
git filter-branch处理 >10k 提交的仓库时，卡住超 2 小时，中途失败后难以恢复
怎么用 git filter-repo 精准删掉指定路径的大文件
核心命令是 git filter-repo --invert-paths --path <file-path> --force</file-path>，它会重写所有含该路径的提交，把对应 blob 彻底从对象库中剥离。
实操要点：
- 必须先
git clone --mirror <url></url>，不是普通克隆——--mirror才包含所有 ref（包括 tags、remote branches），清理才完整 - 路径要写对：比如想删根目录下的
build/output.jar，就写--path build/output.jar；若该路径在子模块里，需先进入子模块单独处理 - 删多个文件不要分多次跑命令，用一个命令传多个
--path：例如git filter-repo --invert-paths --path a.log --path b.dump --path c.zip --force - 运行完会输出新 commit hash 映射表（
commit-map），建议保存一份，后续排查 diff 或 cherry-pick 时有用
删敏感词（如 API Key、密码）不能只靠 --path
--path 只按文件路径删，对散落在代码/配置里的明文密钥无效。此时要用 --replace-text 配合正则替换，或用 --mailmap 替换作者邮箱。
例如清理 appsettings.json 中的密码字段：
echo "s/\"Password\": \".*?\"/\"Password\": \"REDACTED\"/g" > rules.txt git filter-repo --replace-text rules.txt --force
注意：
- 正则必须用 Perl 兼容语法（
git filter-repo底层用 Python 的re模块，但--replace-text要求 Perl 风格的s///） - 替换后所有匹配行都会被改写，如果某次提交里有合法测试值（如
"Password": "test123"），也会被覆盖成REDACTED，无法回溯 - 敏感词若出现在二进制文件（如
.jar、.exe）里，--replace-text无效，只能整个文件删掉
清理后推送到远程必须全员重拉，没有折中方案
因为 git filter-repo 会重写所有 commit hash，旧分支指针全部失效。你 push -f 后，其他人的 git pull 会报错 “non-fast-forward”，强行 merge 会导致重复提交、冲突爆炸。
安全做法只有两种：
- 所有人先把未推送的本地修改
git stash或临时 commit 到远程新分支，等你清理完、强制推送后，他们git clone新仓库，再把stash或 patch 手动打上去 - 若团队用 fork 工作流，先让所有人把 PR 合并进主仓库，确保所有代码已在原始 remote 上，再清理；清理完后所有人删掉本地 fork，重新 fork 新仓库
最容易被忽略的一点：git filter-repo 不会自动清理 remote 的 reflog、prune 过的 objects，也不影响 LFS 对象。如果你之前用过 Git LFS 存大文件，删了 Git 历史里的路径，LFS server 上的 blob 还在，得手动进平台后台删 LFS 文件，否则空间根本没释放。
