Git 历史重写指南：filter-repo 清理敏感信息与减小仓库体积

在团队协作和开源项目中，Git 仓库的历史记录往往会随着时间推移变得臃肿不堪。更糟糕的是，有时我们会不小心将敏感信息——API 密钥、数据库密码、私密令牌——提交到了版本历史中。即使后来删除了这些文件，它们仍然存在于 Git 的历史提交里，任何克隆仓库的人都能轻易找回。这时，我们就需要重写 Git 历史。

为什么需要重写 Git 历史

Git 的设计哲学是“不可变历史”，每一次提交都通过 SHA-1 哈希相互链接，形成一条完整的链条。这意味着简单地删除文件并提交，并不会真正从历史中抹去它。常见的需要重写历史的场景包括：

• 敏感信息泄露：密码、密钥、令牌被意外提交
• 误提交大文件：视频、数据集、编译产物导致仓库体积暴增
• 仓库迁移重构：需要清理历史提交者信息或目录结构
• 移除不再需要的子模块或依赖

过去，开发者常用 git filter-branch 来完成这些任务，但它速度慢、容易出错，且官方已不推荐使用。如今，git filter-repo 是官方推荐的历史重写工具。

filter-repo 简介与安装

git filter-repo 是一个用 Python 编写的第三方工具，由 Git 社区维护，旨在取代 filter-branch。它的优势包括：

• 速度极快，基于流式处理
• 安全性更高，默认会检查并防止误操作
• 支持路径过滤、内容替换、引用重命名等丰富功能

安装方式因平台而异：

# macOS (Homebrew)
brew install git-filter-repo

# pip 安装（跨平台）
pip install git-filter-repo

# 验证安装
git filter-repo --version

安装完成后，git filter-repo 即可作为 Git 子命令使用。

准备工作：安全第一

重写历史是一项破坏性操作，会改变所有提交的哈希值。在执行之前，务必做好以下准备：

1. 备份仓库：直接复制整个仓库目录，或使用 git clone --mirror 创建镜像备份
2. 通知协作者：所有团队成员需要在重写后重新克隆仓库
3. 确保工作区干净：提交或暂存所有更改
4. 在克隆副本上操作：filter-repo 默认要求仓库是“新鲜克隆”，否则会拒绝执行

# 创建镜像备份
git clone --mirror https://github.com/user/repo.git repo-backup.git

# 克隆一份用于重写的工作副本
git clone https://github.com/user/repo.git repo-clean
cd repo-clean

场景一：彻底移除敏感文件

假设你曾不小心提交了 config/secrets.yml 文件，其中包含数据库密码。要将其从所有历史中彻底删除：

git filter-repo --path config/secrets.yml --invert-paths

--path 指定目标路径，--invert-paths 表示“反选”——即删除该路径，而非保留。执行后，该文件将从每一个提交中被移除，仿佛从未存在过。

如果需要删除多个文件或目录，可以重复使用 --path：

git filter-repo \
  --path config/secrets.yml \
  --path .env \
  --path credentials/ \
  --invert-paths

场景二：替换文件中的敏感字符串

有时敏感信息并非独立文件，而是散落在多个文件的内容中，比如硬编码的 API 密钥。这时可以使用 --replace-text 选项。

首先创建一个替换规则文件 replacements.txt：

literal:AKIAIOSFODNN7EXAMPLE==>REMOVED
regex:password\s*=\s*['\"].*?['\"]==>password = "REDACTED"

每行一条规则，支持 literal:（字面量）和 regex:（正则表达式）两种前缀。然后执行：

git filter-repo --replace-text replacements.txt

这样，所有历史提交中匹配到的敏感字符串都会被替换为占位符。

场景三：减小仓库体积

仓库体积膨胀通常源于历史中的大文件。要找出这些“罪魁祸首”，可以使用 git filter-repo --analyze：

git filter-repo --analyze

该命令会生成 .git/filter-repo/analysis/ 目录，其中包含多个报告文件。查看 blob-shas-and-paths.txt 可以找到最大的文件及其路径。

确定目标后，移除大文件的方式与场景一相同：

git filter-repo --path path/to/large-file.zip --invert-paths

如果大文件分布在某个目录中，直接指定目录即可。执行完毕后，Git 会自动运行垃圾回收，仓库体积通常会显著缩小。

场景四：重命名目录或调整结构

有时我们需要将某个子目录提升为仓库根目录，或将目录重命名。filter-repo 提供了 --subdirectory-filter 和 --path-rename 选项：

# 只保留 subdir 目录，并将其作为新的根目录
git filter-repo --subdirectory-filter subdir/

# 将 old-name 重命名为 new-name
git filter-repo --path-rename old-name/:new-name/

这在项目拆分或模块独立时非常有用。

推送重写后的历史

重写完成后，本地仓库的远程配置会被清空（这是 filter-repo 的安全机制）。你需要重新添加远程并强制推送：

git remote add origin https://github.com/user/repo.git
git push --force --all
git push --force --tags

注意：强制推送会覆盖远程历史，所有协作者都必须重新克隆仓库。如果使用 GitHub 等平台，可能还需要联系支持团队清理缓存，否则旧提交仍可能通过特定 URL 访问。

最佳实践与注意事项

• 优先使用官方工具：git filter-repo 比 filter-branch 更安全、更快速
• 敏感信息泄露后立即轮换密钥：重写历史不能保证信息未被他人获取，务必更换所有泄露的凭证
• 使用 .gitignore 防患于未然：在项目初期就配置好忽略规则
• 考虑使用 BFG Repo-Cleaner：对于纯删除大文件的任务，BFG 是另一个轻量选择
• 测试后再推送：在本地验证历史重写结果，确认无误后再强制推送

总结

git filter-repo 是当前重写 Git 历史的最佳工具，无论是清理敏感信息、移除大文件，还是重构目录结构，它都能高效完成任务。掌握它的核心用法——--path、--invert-paths、--replace-text、--subdirectory-filter——足以应对绝大多数场景。但请记住：重写历史是一把双刃剑，操作前务必备份，操作后务必通知团队。只有谨慎使用，才能让仓库历史真正变得干净、轻量、安全。

未经允许不得转载：任鹏个人博客 » Git 历史重写指南：filter-repo 清理敏感信息与减小仓库体积