用git filter-repo清理大文件或敏感内容，比git filter-branch快5–10倍且能真正删干净，但必须在所有协作者同步前完成，否则引发push拒绝、历史错乱或本地分支丢失。
能检索到，但必须用对命令；能挽救，但不是“改”历史，而是“换”一套新提交。
git grep --cached 不适用于全历史敏感词扫描
很多人第一反应是 git grep --cached 'API_KEY'，但它只搜当前暂存区或工作区，对已提交的历史完全无效。真正要扫全部历史，得把所有提交哈希都喂给 git grep：
-
git grep -i 'api_key\|password\|secret' $(git rev-list --all)—— 这才是全量扫描，$(git rev-list --all)展开为每个提交的 SHA1 - 加
-A 2 -B 2可显示上下文，避免误判变量名或注释 - 如果仓库大，这个命令可能卡住，建议先用
git log --oneline | head -20快速确认问题是否集中在近期提交
filter-branch --index-filter 是删除敏感文件的首选
想删掉整个文件（比如误提交的 .env 或 config.ini），别用 --tree-filter——它要检出每个提交、执行 shell 命令、再重新提交，慢且易出错。用 --index-filter 直接操作暂存区，快十倍以上：
git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch .env' --prune-empty --tag-name-filter cat -- --all-
--ignore-unmatch很关键：避免某个提交里没这个文件时命令报错中断 -
--prune-empty会自动剔除因删光所有文件而变成空的提交，保持历史简洁 - 执行完本地分支名不变，但所有提交 SHA 都变了，相当于“重放”了一遍历史
强制推送后协作成员必须重新克隆
运行完 filter-branch 并 git push -f origin main 后，远程分支已彻底变样。这时其他协作者如果还基于旧提交继续开发，git pull 会失败或产生重复提交：
- 他们不能
git pull，必须先备份本地修改，然后git fetch origin && git reset --hard origin/main - 更稳妥的做法是直接
rm -rf 项目目录 && git clone，避免任何引用残留 - GitHub/GitLab 上原提交页面（如
/commit/abc123）会 404，这是正常现象——旧提交对象已被 Git 垃圾回收机制标记为可清理
filter-branch 已被标记为“deprecated”，但目前仍最可控
Git 官方文档里明确写了 filter-branch 是 deprecated，推荐用 git filter-repo。但现实是：filter-repo 需要额外安装 Python 依赖，且部分企业内网环境禁用 pip；而 filter-branch 是 Git 自带命令，只要版本 ≥ 2.22 就能用，参数语义也更直白。
真正容易被忽略的点是：无论用哪个工具，**你无法只“擦除某一行”而不影响该文件其他内容的历史追溯**。如果敏感信息混在 README.md 里，filter-branch --tree-filter 'sed -i ...' 确实能删行，但该文件从第一个含敏感信息的提交开始，所有后续 diff 都会失真——因为每次重写都生成新 blob，老 diff 不再匹配。这时候，“删整文件”反而是更干净的选择。
