Git filter-branch实战指南：彻底清除敏感信息与大文件，安全重写提交历史

Git仓库用久了，谁没做过几件“后悔事”？最常见的就是不小心把密码提交上去，或者把一个几百MB的安装包扔进了仓库。后面的提交当然能把它删掉，但历史里还躺着一个带密码的版本——只要克隆过仓库的人，翻翻git log就能看到。想真正清理干净，唯一的办法是重写历史。Git官方提供的filter-branch，就是干这个活儿的老牌工具。

这篇文章是我长期使用filter-branch的经验总结，不夸张地说，我在它手里栽过好几次跟头。看完你应该能搞明白三件事：filter-branch到底能解决什么问题、它的几个核心参数怎么用、实操中会遇到哪些坑以及怎么避开。如果你正准备给仓库做一次“历史大扫除”，这篇可以直接抄作业。

1. 认识 filter-branch：重写历史的“手术刀”

1.1 它究竟能解决什么问题

filter-branch是 Git 官方的历史重写命令。和普通提交不同，它不只是在最新提交上删除某个文件或修改某行信息，而是把整个提交历史从头到尾“过滤”一遍，再基于过滤后的结果重新构造出一条全新的历史链。

它的典型使用场景包括：

• 从所有历史提交中删除某个误提交的敏感文件，比如.env、密钥、配置文件；
• 把仓库里的大文件从历史中彻底移除，给仓库“瘦身”；
• 批量替换提交信息中的文字或邮箱；
• 统一修改历史提交者和作者信息；
• 把某个子目录拆出来单独成一个仓库；
• 把某类文件从整个项目历史中彻底清除。

为什么普通提交不行？因为 Git 的对象模型决定了“删除记录”本身也是历史的一部分。你删掉了文件，但旧的提交对象仍然存在，旧提交的树对象里仍然有那个文件的快照。只要别人通过git log或提交哈希访问到旧提交，就能把文件翻出来。而filter-branch做的事情，是重新生成一批新的提交对象，让旧的、藏有问题的对象彻底失去引用，最终被 Git 的垃圾回收机制清理掉。

1.2 使用前必须想清楚的边界

先泼一盆冷水：这不是一个随手就能跑的命令，它改变的是所有协作者共享的历史基线。

重写之后，仓库里几乎所有提交的哈希都会变。任何一个基于旧历史创建的分支、标签、Pull Request 都会受到影响。如果你的仓库只有你自己在用，那无所谓；但如果这是一个多人协作的项目，尤其是有大量未合并分支的项目，改写历史等于给所有同事制造了一场“强迫同步事故”。分支合并过的仓库更麻烦，重写历史后旧的 merge-base 不复存在，重新合并时可能会冒出一堆莫名其妙的冲突。

所以我在实际操作中给自己定了三条规矩：

1. 只对还没有推送过的本地分支随意用；
2. 如果已经推送到了公共远程仓库，先和团队打招呼，约好统一的“历史重置时间点”；
3. 动手之前一定先做一份完整备份，哪怕只是git clone --mirror保留一个裸仓库副本。

另外，filter-branch本身并不是不可逆的。只要你在执行前记住了ORIG_HEAD，或者通过reflog找到旧指针，是可以恢复到重写之前的状态的。但万一你顺手跑了git gc --prune=now，旧对象被彻底清除，那就真的是“覆水难收”了。备份永远是第一步。

2. 核心参数逐个拆解：把几个子命令吃透

filter-branch有一个主命令和若干 filter 参数。理解每个参数对应 Git 对象的哪个环节，是正确使用的关键。Git 的每次提交都由几个部分组成：提交信息（message）、作者信息（author）、提交者信息（committer）、文件快照（tree）、父提交列表（parent）。每个 filter 参数就是用来改其中一个部分的。

2.1 --msg-filter：批量改写提交信息

--msg-filter接收一段 shell 命令，把原始的提交信息通过标准输入传给这段命令，命令的标准输出则作为新的提交信息。最常见的用途是批量加前缀，或者替换信息里的敏感词。

git filter-branch --msg-filter ' if [ "$(cat)" = "old message" ]; then echo "new message" else cat fi ' -- --all

我自己的经验是，这种脚本里最容易踩坑的是 sed 的特殊字符。比如你想把所有提交信息里的https://old.example.com替换成https://new.example.com，直接写sed 's/old/new/g'可能没事，但一旦原字符串里含有关键字&、/、\这些特殊字符，替换结果就会和你预期完全不一样。稳妥做法是改用环境变量配合awk，或者干脆用perl -pe，转义规则更统一。

2.2 --index-filter：高效操作文件快照

这是filter-branch里我用得最多的参数。它的工作方式是在每个提交的暂存区（index）上直接执行命令，不把文件真正检出到工作区。因为不用频繁读写磁盘，大仓库下速度优势非常明显。

比如从所有历史提交中删除一个密码文件：

git filter-branch --index-filter ' git rm --cached --ignore-unmatch config/secrets.yml ' -- --all

注意这里必须加--ignore-unmatch。历史提交里并不一定都存在config/secrets.yml，如果某个提交没有这个文件，git rm会直接报错并中断整个重写过程。加上这个参数后，文件不存在时只是静默跳过，不会中断脚本。很多第一次用filter-branch的人都在这里栽过跟头。

--index-filter还有一个延展用法：通过git ls-files配合git update-index实现更复杂的文件批量修改，但日常场景下git rm --cached加通配符已经能覆盖绝大多数需求。

2.3 --commit-filter：精细控制每个提交的取舍

--commit-filter是灵活度最高的参数。它接收一个 shell 命令，命令的各个参数分别是：

• $commit：原始提交的哈希；
• $@：父提交的哈希列表。

你可以在这里决定“这个提交保留、修改还是直接丢弃”。最经典的用法是删掉某个作者的所有提交：

git filter-branch --commit-filter ' if [ "$GIT_AUTHOR_EMAIL" = "bad@example.com" ]; then skip_commit "$@"; else git commit-tree "$@"; fi ' -- --all

skip_commit是filter-branch提供的辅助函数，效果是把当前提交“摘掉”，让它的子提交直接接到它的父提交上。这里有一点必须说明：一旦你修改了提交结构，就要负责把新的父提交列表传递给git commit-tree，否则重建出来的提交会把父指针指向旧历史，最终产物会是断裂的。

这个参数的实际坑点在于：跳过提交之后，仓库里会出现大量空提交。比如某人提交了 50 次，但内容已经被更新提交覆盖，删掉这 50 次后，后面的提交内容没变，历史里就留下一堆“空壳”。需要在执行时配合--prune-empty自动清理空提交。

2.4 --env-filter：修改作者与提交者信息

--env-filter用来修改提交的环境变量，包括GIT_AUTHOR_NAME、GIT_AUTHOR_EMAIL、GIT_AUTHOR_DATE、GIT_COMMITTER_NAME、GIT_COMMITTER_EMAIL等。很多团队统一 Git 提交者信息时用的就是它。

git filter-branch --env-filter ' if [ "$GIT_AUTHOR_EMAIL" = "old@example.com" ]; then export GIT_AUTHOR_NAME="New Name" export GIT_AUTHOR_EMAIL="new@example.com" export GIT_COMMITTER_NAME="New Name" export GIT_COMMITTER_EMAIL="new@example.com" fi ' -- --all

要注意GIT_AUTHOR_*和GIT_COMMITTER_*是两组不同的变量。AUTHOR是“原作者”，COMMITTER是“实际提交人”。很多时候一个人写的代码被另一个人提交，两者并不相同。如果你只想统一显示名，两个都要改，否则git log里还是会看到“作者是 A，提交人是 B”的割裂状态。

2.5 两个容易忽略的配套参数

--prune-empty是上面提到的“空提交清理器”。如果某个提交经过 filter 之后内容为空，这个参数会自动把提交丢弃。注意它是全局参数，要写在filter-branch命令里，而不是放在--之后。

--tag-name-filter则是给历史里的 tag 做同步更新的参数。默认情况下，执行filter-branch会重写分支指针，但 tag 指向的提交哈希不会自动更新。如果你不处理，旧 tag 会和重写后的历史脱节，形成一个“看着还在，实际指向孤儿提交”的烂摊子。

git filter-branch --tag-name-filter cat -- --all

cat在这里的意思是“保持 tag 名称不变”，但引用对象换成新历史里对应的提交。如果你想把所有 tag 改名加个后缀，也可以写成sed 's/^/new-/'。

3. 完整实操：三个真实场景全过程演示

纸上谈兵聊完参数，下面进入实战。我选三个最常遇到的场景，把完整命令、执行逻辑和验证方法都过一遍。所有操作都在 Git Bash（Windows）或终端（macOS/Linux）下执行，仓库状态务必保持干净。

3.1 场景一：把误提交的密码文件从历史中抹掉

项目上线前发现根目录下的config/credentials.json被提交进了仓库，而且已经推送到了远程，前后经过了 30 个提交。这下不光要删当前版本，所有历史版本都得清理。

第一步，从所有历史提交中移除该文件：

git filter-branch --index-filter ' git rm --cached --ignore-unmatch config/credentials.json ' --prune-empty -- --all

执行过程会逐条重放提交，每个提交的哈希都会改变。跑完后检查一下关键文件是否还在某个历史版本里：

git log --all --oneline -- config/credentials.json

正常情况这条命令应该没有输出，说明该文件已经从所有提交中消失。

第二步，清理本地残留的引用。filter-branch会把原始的 ref 备份到.git/refs/original/目录下，如果不删掉，旧提交对象仍然会被它引用着，垃圾回收永远没法执行：

rm -rf .git/refs/original/ git reflog expire --expire=now --all git gc --prune=now --aggressive

第三步，强制推送重写后的历史：

git push origin --force --all git push origin --force --tags

如果远程仓库开了分支保护规则，--force会被服务器拒绝。这种时候需要先在仓库设置里临时关掉保护，推送成功后再开启。我遇到过一次同事在强推后被拒绝的问题，最后排查半天发现是 SSH 认证和权限配置的问题，这个也会在第四节细说。

3.2 场景二：给仓库“瘦身”，把大文件从历史里彻底请出去

仓库体积涨到 1.2GB，查了一下发现罪魁祸首是一份 500MB 的release.tar.gz，而且它存在于历史中的 20 个提交里。有人会问：当前版本不是已经删掉了吗？为什么仓库还是这么大？

因为 Git 的对象库是“只增不减”的。当前树对象里虽然没有了这个大文件，但历史上引用它的提交对象和 blob 对象都还在，git gc也不会清理有引用的对象。唯一的办法还是重写历史。

git filter-branch --index-filter ' git rm --cached --ignore-unmatch release.tar.gz ' --prune-empty -- --all

执行完同样要走清理流程。跑完git gc --prune=now --aggressive之后，再用git count-objects -vH看仓库体积，基本就恢复正常了。整个过程里，--index-filter比--tree-filter快得多。--tree-filter会在每个提交上把文件树解压到临时目录、执行操作、再重新打包，一个 1GB 的仓库可能需要跑几个小时；而--index-filter只操作暂存区索引，通常几分钟就能跑完。

这个场景里我还想提醒一句：大文件删除后，如果团队里有人仍然保留着旧仓库的克隆，他下一次git push会把大文件又推回远程。所以“仓库瘦身”是一个团队行为，需要大家统一重新克隆，或者至少确保旧克隆不会再推送有问题的历史引用。

3.3 场景三：统一重写所有历史提交的作者信息

公司合并账号，原来用zhangsan@old-company.com提交的历史，要全部改成lisi@new-company.com。这种批量替换在生产中很常见，尤其是有多台电脑、多个 Git 账号的人。

git filter-branch --env-filter ' if [ "$GIT_AUTHOR_EMAIL" = "zhangsan@old-company.com" ]; then export GIT_AUTHOR_NAME="lisi" export GIT_AUTHOR_EMAIL="lisi@new-company.com" export GIT_COMMITTER_NAME="lisi" export GIT_COMMITTER_EMAIL="lisi@new-company.com" fi ' --tag-name-filter cat -- --all

这里我把--tag-name-filter cat也加上了，确保历史里的 tag 同步指向新的提交。执行完之后，除了验证git log里的作者信息，还要检查git log --format='%an %ae %cn %ce'，把四列分别对一遍，确认作者名、作者邮箱、提交者名、提交者邮箱都符合预期。

需要注意的是，如果仓库里有大量不同的旧邮箱，比如个人邮箱和公司邮箱混用，脚本里的判断条件会变得很长。我的做法是先跑一条命令把所有邮箱枚举出来：

git log --all --format='%ae' | sort -u

拿到全量清单后再写映射规则，避免漏改。

4. 常见问题与排查技巧实录

4.1 遇到 warning 了怎么办

Git 在 2.24 版本之后，每次执行filter-branch都会打印一段很长的警告，大意是“这个命令容易出错、使用风险较高，推荐使用 filter-repo 替代”。

我个人的看法是：警告归警告，filter-branch在日常小规模仓库上仍然完全可用，我的生产环境里跑过很多次都没出过问题。但在下面两种情况下，我确实会改用filter-repo：

• 仓库很大，提交数量超过几千个，filter-branch的纯 shell 脚本性能会明显拖后腿；
• 需要做更复杂的重写逻辑，比如按目录拆分仓库、重命名多个路径、合并历史片段等。

filter-repo是官方推荐的替代方案，优点是性能好、默认清理更干净、配置方式更现代化，但它不是 Git 自带的工具，需要单独安装。对于只是临时删个文件、改个邮箱的场景，用filter-branch就够了。

4.2 重写历史之后如何恢复

filter-branch重写历史不是瞬间“原地替换”的，它会把原始 ref 保存在.git/refs/original/里，同时ORIG_HEAD也会记录执行前的 HEAD。这意味着只要你没有立刻清理这些引用，就有后悔药吃。

恢复方法很简单：

git reset --hard ORIG_HEAD

执行完后，分支指针会回到重写之前的位置。如果你连ORIG_HEAD都找不到了，git reflog里通常还能看到重写前的提交哈希。最彻底的安全网是在重写之前先执行一次镜像克隆：

git clone --mirror old-repo.git backup-repo.git

这个备份仓库包含所有分支、tag、远程 ref，是完整的仓库快照。我强烈建议，在任何超过 100 个提交的仓库上跑filter-branch之前，都先做这个动作。

4.3 filter-branch 常见报错速查表

4.4 强制同步后，团队成员的旧克隆怎么处理

这是被问得最多的问题。仓库历史重写并强推后，老成员如果直接git pull，很容易出现“本地历史和远程历史分叉”的糟糕状态。最干净的做法是让每个成员执行：

git fetch origin git checkout main git reset --hard origin/main

然后删除本地所有旧分支、旧 tag。只要还留着旧引用，旧对象仓库就会一直存在，仓库体积也降不下来。如果有本地未合并的独有提交，务必在 reset 之前单独备份。

从实际执行效果看，只要通知到位，这个同步过程并不复杂。麻烦的是那些长时间不活跃的克隆仓库，它们就像“僵尸”一样安静躺着，某天突然有人往里面git push，脏对象就又被推回远程了。所以重写历史之后，我会额外加一条规则：远程仓库开启“强制推送需要管理员权限”的保护，避免旧仓库重新污染新历史。

写在最后

说实话，filter-branch的学习曲线不算陡，难的是每次动手前都要想清楚“改写历史”这四个字的分量。我经历过一次印象特别深的翻车：在同事的共享分支上删文件，没提前通知全体成员，结果另一位同事当天下午直接强推了他的旧历史，把密码文件又带回了远程。处理完那次事故后，我再也不会在共享分支上“随手”跑历史重写命令了。

如果你现在正要处理一个紧急的敏感信息泄露，我的建议是：先替整个团队做一次镜像备份，然后按这套流程跑完，最后把清理和强推的通知写得明明白白。小仓库舍得改，大仓库先打招呼，手里至少留一份备份。希望这篇实战笔记能帮你少踩几个坑。