完整记录了 Git 大文件清理的实战过程

# 使用 BFG 清理 Git 历史中的大文件并推送到 GitHub（无需重新 clone）

在 Git 仓库中意外提交了超过 100MB 的大文件后，GitHub 会拒绝 push，提示：

error: File XXX is 328.46 MB; this exceeds GitHub’s file size limit of 100.00 MB

本文记录了如何使用 [`BFG Repo-Cleaner`](https://rtyley.github.io/bfg-repo-cleaner/) 清理 Git 历史中的大文件，并将更新强制推送回远程 GitHub 仓库。**整个过程无需重新 clone 本地项目！**

---

## 🎯 场景说明

- 本地已有项目目录：`~/AAA_BBB`
- 误提交了大文件：如 `.safetensors`、`.pt` 等
- 想清理 Git 历史中的大文件并保留现有代码目录
- 不使用 Git LFS

---

## ✅ 步骤一：准备工作

### 1. 创建镜像仓库副本

```bash
cd ~
git clone --mirror ~/AAA_BBB

这会创建一个裸仓库副本：~/AAA_BBB.git

2. 安装 Java（BFG 依赖 Java）

如果你使用 Conda：

conda install -c conda-forge openjdk=11

或者使用 apt：

sudo apt install openjdk-11-jre-headless

3. 下载 BFG 工具

mkdir -p ~/package_install
cd ~/package_install
wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar -O bfg.jar

创建一个 alias（可选）：

alias bfg='java -jar ~/package_install/bfg.jar'

✅ 步骤二：清理大文件

1. 打包 Git 对象（BFG 只处理 pack 文件）

cd ~/AAA_BBB.git
git reflog expire --expire=now --all
git gc --aggressive --prune=now

2. 使用 BFG 清理 >100MB 的历史文件

bfg --strip-blobs-bigger-than 100M ~/AAA_BBB.git

输出会提示哪些大文件已被删除。

3. 再次清理引用并回收空间

cd ~/AAA_BBB.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive

✅ 步骤三：强制推送到 GitHub

1. 设置远程为 GitHub 仓库地址（隐藏私密信息）

git remote set-url origin git@github.com:YourUsername/YourRepo.git

2. 使用 --mirror 强制推送完整仓库历史

git push --mirror

✅ 步骤四：同步本地代码目录

此步骤可避免重新 clone 本地项目。

cd ~/AAA_BBB
git fetch
git reset --hard origin/main

此时你的工作区将与 GitHub 保持一致，并且大文件历史已清除。

✅ 附加建议：忽略未来的大文件

编辑 .gitignore 防止再次提交模型等大文件

# .gitignore
*.pt
*.safetensors
*.zip
outputs/

git rm -r --cached outputs/
git commit -m "Ignore large files"
git push

✅ 总结

🔒 注意事项

• git reset --hard 会清除未提交改动，请确保提前备份
• 使用 --mirror 会重写所有分支与标签，务必清楚再执行
• 推荐在多人协作仓库操作前，通知所有开发者

✅ 参考链接

• BFG Repo-Cleaner 官方文档
• GitHub：大文件限制
• Git LFS 官网

如果你频繁需要处理大模型等文件，建议配置 Git LFS 或单独管理模型文件。