永久从 Git 历史中移除文件

在 Git 中删除一个文件时，该文件仍会保留在 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:username/repository.git

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

假设待删除的文件为 secrets.txt：

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

该步骤的作用：

• 从所有提交中移除该文件
• 从所有分支中移除该文件
• 从所有标签中移除该文件

删除多个文件：

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

删除整个目录：

git filter-repo --path directory-name/ --invert-paths

6. 验证文件是否已被彻底删除

检查该文件是否仍在历史中存在：

git log --all -- filename

若无任何输出，则说明该文件已完全移除。

7. 强制推送到远程仓库

由于历史已被重写，必须强制推送：

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

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

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

如果您删除的是敏感信息（密钥、Token、密码、私钥），除清理历史外，还应执行以下操作：

立即撤销旧密钥

• 立即在对应服务平台（GitHub、AWS、Azure 等）上撤销或删除旧密钥
• 生成新密钥

检查其他位置

• 检查是否有人已 fork 该仓库
• 检查 CI/CD 缓存中是否残留敏感内容
• 检查本地克隆副本是否仍保留旧内容

重要提醒： 历史被删除，并不意味着他人未在此前复制过。一旦敏感信息被提交至公开仓库，即应视为已泄露。

通知协作者

由于提交历史已变更，其他人的本地仓库将与远程仓库不一致，您需通知他们：

1. 重新克隆仓库（推荐）

2. 或执行以下命令同步：

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

3. 警告： 切勿基于旧历史继续开发，否则再次推送时将重新引入已被删除的文件

常见问题

Q：出现 “fatal: not a git repository” 错误？

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

Q：出现 “git filter-repo: command not found” 错误？

请先安装 git-filter-repo，参考上方安装步骤。

Q：删除后仓库大小未减小？

运行垃圾回收命令：

git gc --aggressive --prune=now

Q：只想修改最新一次提交？

如果该文件仅存在于最新一次提交中，则无需使用 filter-repo，可改用：

git rm --cached filename
git commit --amend

一行式精简版

最核心的命令如下：

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

# 若无远程仓库，先添加
git remote add origin 

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