如果你只是平时用git add、git commit、git push这套流程，大概率不会注意到.git目录其实是个只进不出的垃圾场。前阵子我接手一个历史项目，代码总量 600M，.git目录却膨胀到 1.8G，排查了半天，发现是两年前有人把整个构建产物目录和几份带密钥的配置文件直接提交了进去，之后所有人在这个基础上继续开发了好几个版本。想把这些痕迹从历史里彻底抹掉，git reset不行，git commit --amend也不行，唯一的路就是历史重写。我在filter-branch上折腾了两天，不是跑到一半报错就是慢得离谱，最后换成 Git Filter-Repo，半天收工。这篇文章就把整个思路、命令和踩过的坑完整记录下来。
1. 为什么历史里删文件这么难：先理解 Git 对象模型
1.1 误提交的大文件到底藏在哪
很多人的第一反应是"直接删文件再提交一次不就行了"。如果你只是想让仓库工作区里不再有这个文件，那确实可以。但要搞清楚，Git 的每一次提交并不是只保存变更内容，而是保存一棵完整的目录树快照，树里的每个 blob 对象都对应一个文件版本。你之前提交过的那个 500M 的压缩包，哪怕后来被删除，它对应的 blob 对象依然躺在.git/objects里，只要有旧提交还引用着它，它就永远存在。
这就是为什么.git会比工作区大好几倍。我接手那个仓库时，用git count-objects -vH看了一眼，size-pack 直接 1.7G，其中绝大部分是历史遗留的大文件对象。
1.2 filter-branch 的根目录问题：慢、脆、难验证
Git 官方早年提供了一个叫git filter-branch的命令，专门用来批量改写历史。它的思路是对每个提交执行一次 shell 过滤器，把所有提交重新生成一遍。听起来很直接，但问题是它慢到难以忍受。因为它要对每个提交启动独立的 filter 进程，在提交数量多、历史深的仓库里，时间会呈指数级恶化。Git 官方文档甚至在 filter-branch 的说明里直接写着"请小心使用，它可能非常慢"，并且明确推荐大家改用别的工具。
更难受的是它的容错能力。我跑过几次 filter-branch，有时候是跑到一半临时文件把磁盘塞满，有时候是某个提交里的路径带特殊字符导致整批任务中断。重跑又是一遍从头再来，根本没法增量恢复。而且它默认不清理旧引用，跑完之后.git/refs/original里还会挂着原始分支引用，如果不手动删，你辛苦重写半天，那些大对象照样被旧引用保活。
1.3 Filter-Repo 的定位：为什么它成了替代方案
git filter-repo是后来出现的重写工具，Git 官方文档里推荐用它替代filter-branch。它最大的不同是把重写过程做成"基于 commit graph 的一次性遍历"，而不是对每个提交启动独立进程。再加上它内部直接操作 commit 和 tree 对象，效率比 filter-branch 高出一大截。
我实测过一个 1.4G、两万多条提交的 monorepo，filter-branch跑了四十多分钟后卡死，而git filter-repo处理完只用了六分半钟，差距就是这么明显。除此之外，它还提供了--analyze分析模式、--path和--invert-paths这类语义清晰的参数，以及默认的安全保护机制。考虑到现在新项目基本都直接用filter-repo，建议不要再往filter-branch上投入学习成本了。
2. 动手前的安装与安全边界
2.1 安装方式和版本底线的选择
Filter-Repo 本身是一个自包含的 Python 脚本，安装方式比较灵活。macOS 上我直接用的 Homebrew：
brew install git-filter-repoLinux 环境或者不想装额外包的话，可以直接从官方仓库下载那个单文件脚本，放到 PATH 里加执行权限就行。很多 CI 环境里我用 pip 装：pip install git-filter-repo，也一切正常。Windows 用户在 Git Bash 或 WSL 里都能跑，不建议在 cmd 里直接执行。
需要注意版本底线：它要求 Git 2.24.0 以上。如果你系统自带的 Git 比较旧，建议先升级，否则会出现一些莫名其妙的报错，比如识别不了某些 pathspec 参数。装完之后先用git filter-repo --version确认一下，再开始动仓库。
2.2 为什么官方强制要求"全新 clone"
Filter-Repo 有个默认保护机制：在非全新 clone 的仓库里运行，它会直接拒绝并提示 "Please run this in a fresh clone"。很多人第一次用会觉得烦，但这个设计非常合理。历史重写会改变所有提交哈希，如果你当前仓库里有未推送的分支、本地 stash、或者一堆和 origin 关联的引用，重写结果很容易和你的预期偏离。
所以标准的准备工作是：git clone --no-local一份新的副本，然后在副本上操作。如果你嫌从远端拉太慢，可以用本机路径但一定要加--no-local。直接git clone /path/to/repo可能会启用硬链接，两个仓库共享对象文件，后面重写时会互相干扰，我在这上面栽过一次。
重写前的三件事我也列一下：
- 备份：把原仓库打一个 bundle 或直接 cp 一份到独立目录。
- 清空 stash：如果还有存储的未提交改动，先处理掉，否则重写范围会变得不可控。
- 确认协作状态：如果这个仓库还有别人在用，先约定好重写时间窗口。
2.3 用 --analyze 摸清仓库底细
Filter-Repo 自带一个分析命令，跑一下就能把仓库里的"毒瘤"全部列出来：
git filter-repo --analyze分析完成后会在.git/filter-repo/analysis目录下生成一堆报告文件，包括每个路径的累计大小、最大的 blob、扩展名统计、作者信息统计等等。我每次都会先用它看一眼path-all-sizes.txt和blob-all-sizes.txt，确认要删的到底是哪些文件，再决定怎么写 filter 参数。
这一步千万别跳过。很多人直接上来就写--path xxx --invert-paths，结果跑完发现漏了一个同目录下更隐蔽的大文件，又得重新来一遍。历史重写不是改个配置文件就能反复试的操作，它会把所有提交哈希全部打乱，每次重写都相当于一次新的破坏。先分析，再动手，能省掉大量返工。
3. 高频场景实操：删文件、拆目录、改作者
3.1 从所有历史里彻底抹除指定路径
最常见的需求是"把某个文件或目录从所有历史提交中删掉"。Filter-Repo 的写法很简洁：
git filter-repo --path secret.conf --invert-paths --force这里关键是理解--path和--invert-paths的组合逻辑。单独写--path xxx的意思是"我只保留路径 xxx，其他全部删掉"，通常用于拆分仓库；再加上--invert-paths，意思就反过来了："路径 xxx 是我不要的，其他全部保留"。
我们可以一次传多个路径：
git filter-repo \ --path dist/ \ --path secret.conf \ --path config/keys.json \ --invert-paths \ --force实测下来这个命令对文件路径、目录路径都有效，而且它会自动重写所有提交里的 tree 对象。跑完之后，你再git log --all --oneline -- secret.conf，应该是空结果。这里要强调一点：如果那个敏感文件曾经被复制到了别的目录，比如secret.conf被复制成了config/secret.conf.bak，你需要把所有可能的路径都列出来，否则它还是会留在历史里。
3.2 把子目录拆成独立仓库
另一种很常见的场景是：一个仓库里同时放着前端和服务端代码，现在想把frontend/目录拆出来单独维护。用 Filter-Repo 也简单：
git filter-repo --path frontend/ --force这会生成一个只包含frontend/目录历史的新仓库。注意，这个新仓库里所有提交都保留原来的目录层级，也就是frontend/src/xxx.js这种路径。如果你希望把frontend/提升为仓库根目录，也就是让历史里直接变成src/xxx.js，官方文档推荐用--path-rename做路径改写。
拆完之后记得重新添加远端地址：
git remote add origin git@github.com:yourname/frontend.git git push -u origin mainFilter-Repo 默认会清理 remote 配置，因为历史已经被改写了，旧的 origin 地址对应的历史已经不存在，直接留着反而有风险。我第一次用的时候忘了加 remote，推不上去还以为是命令有问题，后来才反应过来是它的默认行为。
3.3 批量修正作者和邮箱：mailmap 与 callback 的取舍
如果你需要统一历史里的作者信息，Filter-Repo 提供了两种方式。
第一种是--mailmap参数，用法和 Git 的 mailmap 文件一致。创建一个文本文件，里面写映射关系：
Old Name <old@example.com> New Name <new@example.com> <old2@example.com> <new@example.com>然后执行：
git filter-repo --mailmap /path/to/mailmap --force第二种是--email-callback，适合规则比较复杂的情况。比如你想把所有公司域名邮箱改成个人邮箱，或者根据旧邮箱前缀做条件判断，就可以写一段 Python 回调：
git filter-repo --email-callback ' if b"@old-company.com" in email: return b"user@new-domain.com" return email ' --force这里有个容易踩的坑：回调函数的返回值必须是 bytes 类型，不是字符串。我第一次写的时候直接return "xxx@yyy.com"，结果跑起来报类型错误。另外这种 callback 每次只处理一个提交，如果仓库很大，执行时间会比静态映射要长不少。能只用--mailmap解决的就别上 callback。
3.4 清理之前，先用 rev-list 定位隐藏的大文件
有时候你根本不知道哪些文件占了大头，这时候用--analyze看报告是最快的。但如果你不想装任何分析工具，也可以用 Git 自带命令手动定位。我常用的一条组合命令：
git rev-list --objects --all \ | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \ | awk '/^blob/ {print $3, $4}' \ | sort -rn | head -30这条命令的思路是：git rev-list --objects --all列出所有提交里出现过的对象，再交给cat-file --batch-check批量查询类型和大小，然后用 awk 过滤出 blob 对象并按大小排序。执行完就能看到哪些文件占据了对象库的大头，后面再针对性写--path删除规则。
顺带提一句，这种大对象体检在 IDE 或 GUI 客户端里是做不到的。IDEA 的 Git 面板、小乌龟这类工具只展示当前提交内容，历史对象的体积统计根本没有入口，所以平时排查仓库膨胀问题最好还是回到命令行。
4. 重写完成后，为什么.git目录还是那么大
4.1 清理旧引用的顺序是成败关键
很多人跑完git filter-repo就以为大功告成，结果git count-objects -vH一看，体积没降多少。原因很简单：Filter-Repo 重写的是 commit 和 tree 对象，但旧对象本身并没有被立即删除，它们只是变成了不可达状态。而且旧的 reflog、stash、以及远端分支引用可能还指向它们，只要还有一个引用存在，那些对象就会被保活。
所以标准的收尾流程是先把所有旧引用清一遍：
git reflog expire --expire=now --all git gc --prune=now我习惯还会加一句：
git remote remove originFilter-Repo 其实默认已经帮你删掉了 remote，但如果你用了--force加上某些特殊场景，remote 可能还在。旧 origin 的存在意味着远程 refs 可能也被保留，那些 refs 会引着一大堆旧对象不撒手。
还有一个经常被忽略的点：如果仓库里有 stash，它也是一个独立的 ref，会把对象保活。所以我在前面就强调了，重写前把 stash 清理干净。如果重写时仓库里已经存在 stash，Filter-Repo 的处理结果可能不可控，最稳妥的做法是先git stash list看清楚，该提交的提交，该丢弃的丢弃。
4.2 怎么验证清理真的生效了
清完之后，不要急着看目录大小，直接用这几个命令交叉验证：
git count-objects -vH这个命令会显示 size-pack 和 count，能直观看到对象库体积变化。
git rev-list --objects --all | grep "secret.conf"如果这条命令还有输出，说明那个文件还在某个历史提交里，该路径没有被彻底删干净。
git log --all --oneline -- path/to/secret这条用来确认某个路径下已经没有任何历史提交。
最后一个更严格的检查是git fsck --no-reflogs --unreachable，它会列出所有没有被引用但还留在对象库里的对象。如果这里还有很多旧的 blob 或 commit，说明还是有东西没清干净，通常就是某些 reflog 或者远端引用没处理。这时候再回去看git reflog和git branch -a，把残留引用清掉重新 gc。
4.3 为什么 git commit --amend 不能替代历史重写
聊到这里，顺便把git commit --amend的适用范围说清楚。网上经常有人问"改了密码能不能用 amend 掩盖"，答案是不能。amend的作用只是把当前暂存区的改动合并进最近一次提交，或者修改最近一次提交的说明信息。它的本质是生成一个新的提交对象并替换 HEAD 指针，但被替换掉的那个旧提交对象并不会消失，它依然躺在对象库中，直到变成不可达对象后才会被 gc。
也就是说，如果你误把密钥提交到了最近一次提交，用 amend 修一下，工作区确实干净了，但旧提交对象还在。只要有人知道那个哈希，依然能直接访问。如果这个提交已经被推送到了远端，问题就更大了，远端历史里那个旧提交一直存在，所有 clone 过仓库的人都能看到。所以 amend 只适合"提交还没推送出去"的场景。一旦敏感信息已经进入历史，正确的处理方式就是用 Filter-Repo 这类工具做真正的历史重写。
5. 真实项目上踩过的坑
5.1 大仓库执行时间和资源占用
我用 Filter-Repo 处理过的最大的一个仓库是 1.4G 左右，大概两万多条提交，里面有大量的二进制构建产物。跑完一轮过滤，耗时大约六分半钟，峰值内存占用在 1G 上下。要在老旧的 CI 容器上跑这种任务，内存和临时目录都要提前确认，否则可能中途被 kill。
这里有个操作建议：如果仓库特别大，先把不需要的浅克隆分支排除掉。可以先在--analyze阶段确认哪些分支必须保留，然后用git clone --filter=blob:none做 blobless clone，这样拉取下来的仓库只包含提交历史，不含文件内容，等 Filter-Repo 跑完之后再按需拉取实体文件。不过这个方案对团队协作有额外的网络开销，适合一次性清理任务，不适合日常操作。
5.2 force push 之后的协作阵痛
历史重写意味着所有提交哈希全部改变，远端必须用 force push 才能更新：
git push --force --all origin git push --force --tags origin但这一步只是开始，真正的麻烦在后续。团队里其他人本地还保留着旧历史的 clone，他们下次 pull 时 Git 会发现远端历史和本地历史完全是两条线，轻则大量冲突，重则直接拒绝合并。IDEA 和小乌龟这类 GUI 客户端在这种场景下通常会显示一堆"远程已更改"的提示，很多人不知道怎么回事就开始乱合并，结果把已经清理掉的旧对象又合回来了。
正确的做法是让所有开发者删除旧 clone，重新 clone 一份新仓库。如果只用一套仓库，还需要重建 PR、重新配置 review 规则。force push 还会让 CI 里基于旧哈希的缓存全部失效，所以一定要提前做好团队通知，约定一个统一切换的时间点。
5.3 submodule、远程 token 与多机同步的连带问题
如果仓库里用了 submodule，历史重写的连带影响会更大。Filter-Repo 重写的是主仓库的提交历史，submodule 在提交里是以 gitlink 形式记录一个固定哈希。主仓库重写后，如果 submodule 仓库本身没有做对应处理，git submodule update可能会报错，因为提交里指向的 submodule 哈希在旧仓库里还能找到，但因为历史被重写，gitlink 的匹配关系可能已经对不上。
处理办法一般是：先把 submodule 仓库也做一次历史重写或至少确认其内容稳定，再重新执行git submodule update --init --recursive。另外一个很容易被忽略的问题是新机器 clone 时的认证配置。很多团队用 HTTPS 地址加 token 拉代码，重写后重新 clone 时如果 token 权限不够，就会遇到各种认证失败。换到 SSH 通道的话，记得先确认ssh -T git@github.com这类命令能通过。
多台电脑同步这个场景我多说一句：如果你有两台电脑同时开发，历史重写后，另一台电脑上的旧 clone 已经作废了。别试图用 pull 或者 rebase 去修复，直接删掉重新 clone，这是代价最低的路径。
5.4 哪些场景不该用 Filter-Repo
历史重写毕竟是破坏性操作，不是所有情况都适合做。我一般遇到下面几种情况会直接劝退：
- 仓库已经在公开平台被大量 fork，改历史会让下游所有 fork 和依赖项目陷入混乱。
- 项目处于活跃审计阶段，提交历史的完整性本身就是合规要求。
- 团队规模很大且没有统一的管理手段，无法保证所有人都在同一时间点切换新历史。
另外一个不是特别明显但很现实的限制：Filter-Repo 只能重写 Git 层面的内容，它无法清除已经进入 CI 缓存、CDN、或者别人下载过的历史产物。如果敏感信息已经泄露到外部，修仓库只是一部分工作，该改的密码、该换的 key 一个都不能省。
6. 验证与收尾：确认历史真的被清干净
6.1 提交哈希、文件路径、对象计数三重检查
收尾阶段我习惯按"哈希-路径-对象"三个维度做一遍完整检查。先用git log --all --oneline -20看一眼新历史的结构，确认提交记录是完整连续的，然后对比一下当前 HEAD 的哈希和原仓库备份里的哈希，确保历史确实被重写过。
接着用这一条验证目标路径已经从所有提交中消失：
git rev-list --objects --all | grep "secret.conf"正常情况应该是空输出。最后再用git count-objects -vH对比重写前后的对象库体积。以我那个项目为例，重写前 size-pack 是 1.7G，清完之后只剩 240M，效果非常直观。如果发现体积没有明显下降，多半是前面的旧引用清理步骤没有做全。
6.2 远端验证：从仓库页面倒推重写结果
本地验证通过之后，还要去远端平台确认一下。Force push 完成后，在 GitHub、Gitee 这类平台的仓库页面里，直接搜一下之前清理掉的文件路径，应该没有任何结果。也可以打开历史提交列表，随机挑几个旧提交的哈希，用浏览器地址栏访问https://<平台>/<owner>/<repo>/commit/<旧哈希>，正常情况会返回 404 或提示提交不存在，这就说明远端的历史也确实被换掉了。
这一步千万别省。本地重写成功不代表远端更新成功，有时候因为分支保护规则或者 force push 权限限制，推送会被部分拒绝。如果你 push 之后不验证远端，后面有人 clone 下来还是旧历史，整个重写等于白做。
6.3 用保护分支和 push 权限把好最后一关
历史重写完成之后，最好顺手把仓库的分支保护策略配置好。主分支开启 force push 保护是最基本的，确保以后没有人能随意覆盖远端历史。团队里如果需要保留重写能力，可以让少数管理员单独掌握权限，普通开发者走 PR 流程就够了。
如果有多个长期分支，可以约定 push 频率和合并策略，降低未来再出现"历史里混入大文件"这类问题的概率。从根上解决问题比事后清理重要得多。
我个人在实际操作中的体会是：Filter-Repo 并不是一个需要天天用的工具，但它是每个 Git 重度使用者都应该掌握的安全网。碰上仓库膨胀、敏感信息误提交、子目录拆分的场景，它比 filter-branch 可靠太多。唯一要记住的是，动手之前先 clone 一份新鲜的副本，先跑--analyze看清底细，重写之后再花十分钟做验证，这套流程走完，基本不会再出问题。
