---

一文搞懂 git filter-repo：Git 历史清理与重构的终极利器

在软件开发的漫长旅程中，Git 仓库的提交历史就像是项目的“航海日志”。它记录了每一次代码的变更、每一次功能的迭代和每一次 bug 的修复。一个清晰、干净、有意义的 Git 历史，对于团队协作、代码审查、问题追溯以及项目维护都至关重要。然而，在实际工作中，我们的“航海日志”常常会因为各种原因而变得混乱不堪：

• 误提交敏感信息：不小心将密码、API 密钥、私钥等敏感数据提交到了仓库中。
• 提交大型二进制文件：将视频、设计稿、编译产物等大文件加入了版本控制，导致仓库体积急剧膨胀。
• 项目结构调整：需要将一个庞大的单体仓库（Monorepo）中的某个子目录拆分成一个独立的、拥有完整历史的新仓库。
• 作者信息修正：由于配置错误，大量提交使用了错误的用户名或邮箱地址。
• 历史重构：希望对整个项目的历史进行系统性的调整，比如统一提交信息格式、移除所有 .DS_Store 文件等。

面对这些问题，我们需要一个强大而可靠的工具来“改写历史”。在过去，git filter-branch 是 Git 官方提供的解决方案，但它以其复杂难用的接口、极其缓慢的执行速度和潜在的危险性而“臭名昭著”。随后，BFG Repo-Cleaner 等工具应运而生，它们在特定场景（如删除大文件）下表现出色，但通用性和灵活性有所欠缺。

今天，我们迎来了 Git 历史重写领域的王者——git filter-repo。它是由 git filter-branch 的主要维护者之一开发，并被 Git 官方正式推荐为替代 filter-branch 的首选工具。git filter-repo 集速度、安全、易用性和强大功能于一身，是当之无愧的 Git 历史清理与重构的终极利器。

本文将作为一份详尽的指南，带你从零开始，全面掌握 git filter-repo 的使用方法，让你能够自信地应对各种复杂的 Git 历史操作场景。

一、为什么选择 git filter-repo？

在深入学习具体用法之前，我们有必要了解 git filter-repo 相比于它的前辈们，究竟好在哪里。

1. 无与伦比的速度：git filter-repo 的性能远超 git filter-branch。filter-branch 在处理每个提交时，都需要检出（checkout）文件到工作目录，这涉及到大量的磁盘 I/O 操作，因此速度极慢。而 git filter-repo 直接在 Git 的对象数据库（.git 目录下的 objects）层面进行操作，避免了不必要的检出，速度通常是 filter-branch 的几十倍甚至上百倍。

2. 默认的安全性：git filter-repo 在设计上就将安全放在了首位。它会强制要求你在一个全新的、干净的克隆仓库上进行操作，从而避免了对你原始工作仓库的任何意外破坏。如果你尝试在已有历史的仓库上运行它，它会报错并拒绝执行，这道“防火墙”为你的数据安全提供了坚实的保障。

3. 简洁直观的接口：filter-branch 的命令行语法晦涩难懂，常常需要编写复杂的 shell 脚本。而 git filter-repo 提供了大量简单明了的命令行选项，覆盖了 80% 以上的常见场景。例如，--strip-blobs-bigger-than 10M（删除大于 10M 的文件）、--path-rename old:new（重命名文件/目录）等，一看便知其意。

4. 强大的可扩展性：对于复杂的、定制化的需求，git filter-repo 提供了基于 Python 的回调（callback）功能，如 --message-callback、--blob-callback 等。你可以通过一小段 Python 代码，实现对提交信息、文件内容等进行任意复杂的转换，兼具了易用性与灵活性。

5. 官方的认可与推荐：Git 官方文档现在明确指出 git filter-branch 存在诸多问题，并强烈推荐用户迁移到 git filter-repo。这意味着 filter-repo 是社区公认的未来方向，拥有更好的维护和更活跃的社区支持。

二、安装与准备工作：安全第一

“工欲善其事，必先利其器”。在使用 git filter-repo 之前，我们需要完成安装并做好万无一失的准备。

2.1 安装

git filter-repo 是一个 Python 脚本，最简单的安装方式是通过 pip：

bash
pip install git-filter-repo

如果你使用的是 macOS 并安装了 Homebrew，也可以通过以下命令安装：

bash
brew install git-filter-repo

对于 Debian/Ubuntu 等 Linux 发行版，可以使用系统的包管理器：

bash
sudo apt-get install git-filter-repo

安装完成后，在终端运行 git filter-repo --version，如果能看到版本号输出，则表示安装成功。

2.2 准备工作：备份与克隆

重写历史是一项具有破坏性的操作。它会改变 Git 仓库中几乎所有对象的 SHA-1 哈希值。一旦你将改写后的历史强制推送到远程仓库，所有协作者都需要进行特殊处理才能同步。因此，在动手之前，务必遵循以下黄金法则：

第一步：完整备份原始仓库

在进行任何操作之前，请为你的原始仓库创建一个完美的、包含所有分支和标签的镜像备份。这是你的“后悔药”。

“`bash

假设你的原始仓库在 my-project.git

git clone –mirror [email protected]:your-org/my-project.git my-project.backup.git
“`

--mirror 参数会创建一个裸仓库（bare repository），它包含了原始仓库的所有信息（所有分支、所有标签、所有 Git 内部对象），但没有工作目录。你可以将这个 my-project.backup.git 目录压缩存档，放到一个安全的地方。

第二步：在一个全新的克隆上操作

git filter-repo 的安全机制要求你在一个新克隆的仓库上工作。这样做可以确保你的原始工作区不受影响。

“`bash

从你的原始仓库克隆一个新的副本用于操作

git clone [email protected]:your-org/my-project.git my-project-filtered

cd my-project-filtered
“`

现在，我们所有的 git filter-repo 命令都将在这个 my-project-filtered 目录中执行。

三、核心用例与实战演练

下面，我们将通过一系列真实、高频的场景，来演示 git filter-repo 的强大功能。

场景一：从所有历史中彻底删除文件或目录

这是最常见的需求，比如删掉误提交的密码文件 config/database.yml 或庞大的 node_modules 目录。

命令：

“`bash

删除单个文件

git filter-repo –path config/database.yml –invert-paths

删除整个目录

git filter-repo –path node_modules/ –invert-paths

删除多种模式的文件（例如，所有 .log 文件）

git filter-repo –path-glob ‘*.log’ –invert-paths
“`

解析：

• --path <path>：选中指定路径的文件或目录。
• --path-glob <glob>：使用通配符模式选中文件。
• --invert-paths：这是关键！它会将你的选择反转，即“除了我选中的路径，保留其他所有东西”，从而达到了删除的目的。

执行命令后，git filter-repo 会遍历所有提交，将目标文件或目录从中抹去，并重新计算后续所有提交的哈希值。

场景二：清除所有大于指定体积的文件

当仓库因为大文件而变得臃肿不堪时，这个功能就是救星。

命令：

“`bash

删除所有大于 10MB 的文件

git filter-repo –strip-blobs-bigger-than 10M

删除所有大于 500KB 的文件

git filter-repo –strip-blobs-bigger-than 500K
“`

解析：

• --strip-blobs-bigger-than <size>：blob 是 Git 中存储文件内容的对象。这个命令会移除所有体积超过 <size> 的 blob。支持的单位有 K、M、G。

这个命令非常高效，它会扫描 Git 的对象数据库，直接剔除不符合要求的 blob，然后重写引用了这些 blob 的提交。

场景三：将子目录提取为独立的新仓库

当一个单体仓库发展到一定阶段，需要将其中的某个模块（如 services/user-service/）拆分成微服务时，我们希望这个新仓库能保留原有的完整提交历史。

命令：

“`bash

将 services/user-service/ 目录提取出来，并使其成为新仓库的根目录

git filter-repo –subdirectory-filter services/user-service/
“`

解析：

• --subdirectory-filter <directory>：这个命令会执行以下操作：
  1. 只保留与指定子目录相关的提交。
  2. 将该子目录提升为新仓库的根目录。
  3. 丢弃所有与该子目录无关的文件和提交。

执行完毕后，my-project-filtered 仓库就变成了一个全新的、只包含 user-service 代码及其完整演进历史的仓库。

场景四：统一修改作者的姓名和邮箱

团队成员可能因为本地 Git 配置不当，使用了个人邮箱或错误的用户名提交了代码。我们需要将其修正为公司的标准信息。

准备工作：

首先，创建一个“邮件映射”文件，我们称之为 mailmap.txt。格式为：

正确用户名 <正确邮箱> 错误用户名 <错误邮箱>

例如：

“`

mailmap.txt

John Doe john.doe@company.com John Doe john.doe@gmail.com
John Doe john.doe@company.com JD jd@local-machine
“`

命令：

bash
git filter-repo --mailmap mailmap.txt

解析：

• --mailmap <file>：git filter-repo 会读取这个映射文件，并遍历每一个提交。如果提交的作者或提交者信息匹配到了文件中的“错误”部分，就会自动替换为对应的“正确”信息。这是一种非常优雅且强大的批量修正方式。

场景五：在整个历史中重命名文件或目录

假设项目早期有一个名为 legacy-api/ 的目录，现在想在整个提交历史中都将其重命名为 core-api/。

命令：

bash
git filter-repo --path-rename legacy-api:core-api

解析：

• --path-rename <old_name>:<new_name>：使用冒号分隔的格式，指定旧路径和新路径。git filter-repo 会在所有历史提交中应用这个重命名规则。

场景六：高级定制 – 使用回调函数修改提交信息

假设我们需要给所有提交信息加上一个项目前缀，比如 [PROJECT-X]。

命令：

bash
git filter-repo --message-callback 'return b"[PROJECT-X] " + message'

解析：

• --message-callback <python_code>：这里我们传入了一小段 Python 代码。
  • 在回调的上下文中，message 变量代表原始的提交信息，它是一个字节字符串（bytes）。
  • return b"[PROJECT-X] " + message 返回一个新的字节字符串，作为修改后的提交信息。b"" 表示这是一个字节字符串。

这种回调机制极大地扩展了 git filter-repo 的能力，你可以用类似的方式使用 --blob-callback 修改文件内容，或用 --filename-callback 实现更复杂的重命名逻辑。

四、收尾工作：清理与推送

当你对 my-project-filtered 仓库中的历史感到满意后，还剩下最后几个关键步骤。

第一步：检查新历史

在执行任何不可逆操作前，仔细检查一下新的提交历史。

“`bash
git log –oneline | head -n 20

或者使用图形化工具

gitk –all
“`

确认文件被正确删除、重命名，作者信息被修改，提交信息符合预期。

第二步：清理旧对象

git filter-repo 会在 .git/filter-repo/ 目录下保留一些重写前的引用信息，以便恢复。当你确认不再需要它们时，可以清理仓库，减小 .git 目录的体积。

“`bash

首先，移除与旧远程仓库的关联

git remote rm origin

强制执行垃圾回收，彻底删除旧的、无法访问的对象

git gc –prune=now –aggressive
“`

第三步：推送到新的远程仓库

现在，你需要将这个“焕然一新”的仓库推送到远程。通常有两种选择：

1. 推送到一个全新的远程仓库：这是最安全、最推荐的做法。

   “`bash

   在 GitHub/GitLab 等平台创建一个全新的空仓库

   添加新仓库地址为 origin

   git remote add origin [email protected]:your-org/my-project-new.git

   强制推送所有分支和标签

   git push origin –force –all
   git push origin –force –tags
   “`

2. 覆盖旧的远程仓库：这是极其危险的操作，必须提前与所有团队成员沟通！

   通知所有协作者：仓库历史已被重写，他们本地的旧仓库将无法正常 pull。他们需要删除本地旧仓库，然后重新克隆，或者执行复杂的分支重置操作。

   在获得团队一致同意后，执行以下操作：

   “`bash

   假设旧仓库地址是 [email protected]:your-org/my-project.git

   git remote add origin [email protected]:your-org/my-project.git

   ！！！警告：这将永久覆盖远程仓库的历史 ！！！

   git push origin –force –all
   git push origin –force –tags
   “`

解析：

• --force：必须使用强制推送，因为新历史与旧历史完全不兼容。
• --all：推送所有本地分支。
• --tags：推送所有本地标签。filter-repo 会相应地更新标签，使其指向新的提交。

五、最佳实践与注意事项

• 永远备份：在任何时候，备份都是你的救生圈。
• 沟通，沟通，再沟通：如果要重写一个共享仓库的历史，沟通是成功的关键。确保每个团队成员都了解变更计划和后续需要执行的操作。
• 小步快跑：尽量一次只执行一种类型的历史修改。比如，先删除大文件，再修改作者信息。这样更容易验证每一步操作的正确性。
• 理解其破坏性：深刻理解 git filter-repo 会创建全新的提交历史。对于开源项目或有大量外部贡献者的项目，重写历史需要极其谨慎。
• 善用 dry-run：对于一些复杂的命令，可以加上 --dry-run 参数进行演习，它会显示将要执行的操作但不会真正修改仓库。

结语

git filter-repo 无疑是现代 Git 工作流中处理历史问题的最佳工具。它将曾经令人望而生畏的 git filter-branch 变成了简单、快速且安全的操作。通过掌握本文介绍的核心用法和工作流程，你将能够从容地管理和维护任何规模的 Git 仓库，无论是清理敏感数据、为仓库“瘦身”，还是进行大规模的结构重构。

记住，强大的工具需要配以谨慎的态度。在按下回车键之前，请确保你已经做好了充分的准备。现在，去尽情地“净化”你的 Git 历史吧！