如何使用BFG Repo-Cleaner清理本地大文件仓库以推送至GitHub

核心结论 #

不需要对原本地仓库单独执行BFG命令，通过处理镜像仓库后同步原仓库即可完成历史清理，全程安全且不破坏原仓库备份。

详细操作步骤 #

• 1. 创建本地仓库的镜像副本
  镜像仓库是包含所有分支、标签完整历史的裸仓库，用来安全处理历史数据，不影响原仓库：

  git clone --mirror /Users/me/myrepo /Users/me/myrepomirror.git
  

• 2. 用BFG清理镜像仓库中的大文件
  执行命令移除所有提交历史中超过50MB的文件（当前分支最新版本的大文件会被保留，若要彻底移除可加--no-blob-protection参数）：

  java -jar bfg.jar --strip-blobs-bigger-than 50M /Users/me/myrepomirror.git
  

• 3. 清理镜像仓库的冗余数据
  进入镜像仓库目录，执行垃圾回收彻底删除被标记的大文件：

  cd /Users/me/myrepomirror.git
  git reflog expire --expire=now --all
  git gc --prune=now --aggressive
  

• 4. 同步原本地仓库到清理后的镜像仓库
  回到原仓库目录，拉取镜像仓库的清理结果，覆盖本地历史：

  cd /Users/me/myrepo
  # 备份原远程仓库（防止出错）
  git remote rename origin origin-backup
  # 添加清理后的镜像仓库为临时远程
  git remote add cleaned-mirror /Users/me/myrepomirror.git
  # 强制拉取所有分支的清理后历史
  git pull cleaned-mirror --all --force
  # 可选：删除临时远程
  git remote remove cleaned-mirror
  

• 5. 强制推送到GitHub
  由于历史已被改写，必须强制推送覆盖GitHub上的旧历史：

  git push origin --all --force
  # 若有标签需要同步，执行：
  git push origin --tags --force
  

常见疑问解答 #

• 为什么用镜像仓库？
  镜像仓库是原仓库的完整副本，处理过程中不会影响原仓库，即使操作失误，原仓库仍可正常使用，风险更低。
• 后续的git reflog expire和git gc命令作用是什么？
  这些命令是彻底清理镜像仓库中被BFG标记为删除的冗余数据，确保大文件被完全移除，不会残留。
• 原仓库还需要单独跑BFG吗？
  不需要，通过拉取镜像仓库的清理结果，原仓库的所有分支历史都会同步更新，无需重复执行BFG。

内容的提问来源于stack exchange，提问作者Socorro