Git从历史提交中删除文件

发表于

一、 概述与风险提示

使用场景：

  • 不慎提交了敏感信息（如密码、密钥）。
  • 误提交了大文件导致仓库体积膨胀。
  • 需要清理版本控制历史中的临时文件。

⚠️ 重要风险提示：

  1. 不可逆操作：修改 Git 历史会改变提交的哈希值 (SHA)，影响所有协作者。
  2. 必须备份：执行任何历史修改操作前，务必备份整个仓库。
  3. 团队协调：操作前应通知所有协作者，操作后需重新 clone 仓库。
  4. 替代方案：如果只是想删除最新提交中的文件，使用 git rm 即可，无需修改历史。

二、 方法一：git filter-branch

适用于批量处理整个仓库的历史记录。

1
2
3
4
5
6
7
# 切换到仓库根目录
cd /path/to/repo

# 执行删除操作
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch example.txt' \
  --prune-empty --tag-name-filter cat -- --all

参数说明：

  • --force：强制覆盖旧的备份分支。
  • --index-filter：对每个提交的索引执行命令。
  • git rm --cached --ignore-unmatch：从索引中移除文件，但忽略文件不存在的情况。
  • --prune-empty：删除因操作变为空的提交。
  • --tag-name-filter cat：保留原有标签名称。
  • --all：处理所有分支。

清理残留：

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

三、 方法二：git rebase

适用于处理少量连续提交中的文件删除。

1
2
3
4
5
6
# 1. 查看提交历史，确定目标提交范围
git log --oneline

# 2. 开始交互式 rebase
# 例如从 HEAD~5 开始，包含最近5个提交
git rebase -i HEAD~5

在打开的编辑器中，找到包含目标文件的提交，将其 pick 改为 edit：

1
2
3
pick abc1234 添加配置文件
edit def5678 添加敏感文件  <-- 改为 edit
pick 89a0123 修复bug

保存退出后，执行以下操作：

1
2
3
4
5
6
7
8
# 删除文件
git rm example.txt

# 修改当前提交（不改变消息）
git commit --amend --no-edit

# 继续 rebase 过程
git rebase --continue

如果有多个提交需要处理，重复上述 edit -> git rm -> amend -> continue 的流程。

四、 方法三：git filter-repo（推荐）

git filter-repo 是目前最推荐的工具，速度快、灵活性高、功能强大。

安装：

1
2
# 使用 pip 安装
python3 -m pip install --user git-filter-repo

删除单个文件：

1
git filter-repo --path example.txt --invert-paths

删除多个文件或目录：

1
git filter-repo --path-rename example.txt: --path-rename sensitive/: --invert-paths

删除大于指定大小的文件：

1
git filter-repo --strip-blobs-bigger-than 10M --invert-paths

⚠️ 重要：filter-repo 要求仓库是干净的 clone，建议使用以下方式：

1
2
3
4
5
6
7
8
9
10
11
# 1. 克隆仓库（使用 --mirror 完整克隆）
git clone --mirror https://github.com/user/repo.git

# 2. 进入仓库目录
cd repo.git

# 3. 执行过滤
git filter-repo --path example.txt --invert-paths

# 4. 推送更新
git push --force

五、 方法对比与总结

特性 filter-branch rebase filter-repo
速度 慢 取决于提交数 快
适用场景 大量历史处理 少量连续提交 所有场景
学习曲线 中等 较低 低
灵活性 高 低 高
推荐程度 ❌ 不推荐 ⚠️ 慎用 ✅ 强烈推荐

建议流程：

  1. 优先考虑使用 **git filter-repo**。
  2. 操作前务必备份仓库。
  3. 通知协作者即将进行的维护。
  4. 操作完成后，强制推送到远程：git push --force --all。
  5. 提醒所有协作者重新 clone 仓库。