Git 历史中彻底删除文件

本技能指导用户使用 git filter-repo 工具从 Git 仓库的完整历史记录中彻底删除指定文件。

适用场景

意外提交了敏感信息（密码、API 密钥、私钥、token）
意外提交了大文件，导致仓库体积膨胀
需要清理历史记录中的特定文件
需要移除所有分支和标签中的某个文件

核心流程

1. 注意！第一步，先询问用户，确定用户的仓库路径，是否是当前工作目录。

询问用户是否需要备份仓库（强烈建议）

必须用户确认后，继续执行后续步骤。

2. 备份仓库（强烈建议）

在执行任何操作前，先备份仓库：

# 方式1：复制整个仓库目录
cp -r your-repo your-repo-backup

# 方式2：创建裸仓库备份
git clone --bare your-repo your-repo-backup.git

3. 安装 git filter-repo

根据操作系统选择安装方式：

macOS:

brew install git-filter-repo

Ubuntu / Debian:

pip install git-filter-repo

Windows:

pip install git-filter-repo

4. 确认当前仓库状态

进入仓库目录后检查：

git status
git remote -v

如果没有远程仓库，先添加：

git remote add origin git@github.com:用户名/仓库名.git

5. 使用 git filter-repo 删除文件

假设要删除的文件是 secrets.txt：

git filter-repo --path secrets.txt --invert-paths

这一步的作用：

从所有 commit 中移除该文件
从所有分支中移除该文件
从所有 tag 中移除该文件

删除多个文件：

git filter-repo --path file1.txt --path file2.txt --path secrets/ --invert-paths

删除整个目录：

git filter-repo --path 目录名/ --invert-paths

6. 验证文件是否已删除

查看历史中是否还有这个文件：

git log --all -- 文件名

如果没有输出，说明已经删干净了。

6. 强制推送到远程仓库

因为历史被重写了，必须强制推送：

# 推送所有分支
git push origin --force --all

# 推送所有标签
git push origin --force --tags

敏感信息删除后的额外操作

如果删除的是敏感信息（密钥、token、密码、私钥），除了删除历史，还要：

立即吊销旧密钥

在对应的服务平台（GitHub、AWS、Azure 等）立即吊销/删除旧密钥
重新生成新的密钥

检查其他位置

检查是否有其他人 fork 了仓库
检查 CI/CD 缓存
检查本地 clone 是否还保留旧内容

重要提醒： 历史删掉了，不代表别人之前没复制走。一旦敏感信息被提交到公开仓库，就应当视为已泄露。

通知协作者

因为 commit 历史变了，其他人本地仓库会和远程不一致。需要通知他们：

重新 clone 仓库（推荐）

或者执行以下命令同步：

git fetch origin
git reset --hard origin/main  # 会丢失本地未推送的更改，谨慎使用

警告： 不要继续基于旧历史开发，否则再次推送时会重新引入已删除的文件

常见问题

Q: 提示 "fatal: not a git repository"？

确保你在 Git 仓库根目录下执行命令。

Q: 提示 "git filter-repo: command not found"？

先安装 git-filter-repo，参考上面的安装步骤。

Q: 删除后仓库体积没有变小？

需要执行垃圾回收：

git gc --aggressive --prune=now

Q: 只想修改最近一次 commit？

如果文件只在最近一次 commit 中，不需要用 filter-repo，用：

git rm --cached 文件名
git commit --amend

一句话版本

最核心的命令：

# 删除文件
 git filter-repo --path 文件名 --invert-paths

# 如果没有远程，先添加
git remote add origin <repo-url>

# 强制推送
git push origin --force --all
git push origin --force --tags