过滤分支(git filter-branch)

git filter-branch 是 Git 中一个强大的历史重写工具，允许对仓库的提交历史进行深度修改。它可以批量修改提交中的文件内容、作者信息、提交消息等，但需谨慎使用，因为会改变提交哈希，可能影响协作。

基本概念与用途

git filter-branch 的核心功能是遍历所有提交，按指定规则重写历史。常见场景包括：

• 从历史中彻底删除敏感文件（如密码、密钥）
• 批量修改作者/提交者信息
• 提取子目录作为新仓库的根目录
• 合并多个仓库时清理历史冲突

# 基本语法结构
git filter-branch [选项] <子命令> [参数]

典型使用场景

删除历史中的文件

要从所有提交中删除某个文件（如 credentials.txt）：

git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch credentials.txt' \
  --prune-empty --tag-name-filter cat -- --all

• --index-filter 比 --tree-filter 更快（不检出文件）
• --prune-empty 自动删除因此产生的空提交
• --tag-name-filter cat 保留标签名称

修改提交信息

批量修改作者邮箱地址：

git filter-branch --env-filter '
  if [ "$GIT_AUTHOR_EMAIL" = "old@example.com" ]; then
    GIT_AUTHOR_EMAIL="new@example.com";
  fi
' --tag-name-filter cat -- --all

子目录提取

将 subdir/ 提升为仓库根目录：

git filter-branch --subdirectory-filter subdir -- --all

高级用法示例

条件性修改文件内容

使用 --tree-filter 修改所有 .js 文件中的文本：

git filter-branch --tree-filter "
  find . -name '*.js' -exec sed -i 's/var/const/g' {} +
" HEAD~10..HEAD

多条件组合

同时修改作者信息和删除文件：

git filter-branch --env-filter '
  # 修改作者
  export GIT_AUTHOR_NAME="New Name"
  export GIT_AUTHOR_EMAIL="new@email.com"
' --index-filter '
  # 删除文件
  git rm --cached --ignore-unmatch secret.txt
' --prune-empty -- --all

性能优化技巧

1. 限制范围：添加提交范围（如 HEAD~20..HEAD）
2. 使用索引过滤：--index-filter 比 --tree-filter 快10-100倍
3. 关闭gc：临时禁用垃圾回收

   git -c gc.auto=0 filter-branch ...
   

风险与注意事项

1. 哈希变更：所有重写的提交会生成新哈希，破坏协作
2. 备份必要：操作前必须创建仓库备份

   git clone --mirror original.git backup.git
   

3. 清理缓存：操作后需清理引用缓存

   git for-each-ref --format="delete %(refname)" refs/original | git update-ref --stdin
   git reflog expire --expire=now --all
   git gc --prune=now
   

替代工具比较

对于大型仓库，考虑更高效的工具：

• git-filter-repo（Python实现，速度更快）
• BFG Repo-Cleaner（Java实现，专为删除大文件优化）

# 使用git-filter-repo删除文件示例
git filter-repo --path credentials.txt --invert-paths

实际案例：迁移项目

假设需要将 project-v1/ 目录提取为新仓库，并修改所有提交者信息：

# 步骤1：克隆原始仓库
git clone https://example.com/original.git
cd original

# 步骤2：提取子目录
git filter-branch --subdirectory-filter project-v1 -- --all

# 步骤3：修改提交信息
git filter-branch --env-filter '
  export GIT_COMMITTER_NAME="Team"
  export GIT_COMMITTER_EMAIL="team@company.com"
' -- --all

# 步骤4：推送到新仓库
git remote set-url origin https://example.com/new-repo.git
git push --force --all