迁移Bitbucket仓库至GitHub时推送因大文件限制失败求助

问题背景 #

我正尝试把Bitbucket上的仓库迁移到GitHub，操作步骤是：

git clone https://bitbucket.company_name.net/scm/project/repository.git
cd repository folder
git remote add github https://github.com/project-name/repo-name.git
git push github

但推送时收到了大文件超限的错误：

remote: error: File target/file1.war is 146.41 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: File target/file2.war is 146.41 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: File target/file.war is 146.41 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage
![remote rejected] main -> main (pre-receive hook declined) error: failed to push some refs to 'https://github.com/project-name/repo-name.git'

奇怪的是，本地克隆的仓库里并没有这些.war文件，但在.git/objects/pack目录下有大体积的.pack、.idx和.rev文件——这说明这些大文件其实藏在Git的提交历史里，只是现在被删除了，但历史记录还保留着，推送时GitHub会检查整个历史里的文件大小。之前试过Git LFS的方案，但没解决问题。

解决方法：清理Git历史中的大文件 #

既然Git LFS没起作用，我们需要彻底从仓库的所有提交历史里移除这些超大的.war文件，推荐用git filter-repo（官方推荐的替代旧工具git filter-branch的方案），步骤如下：

1. 安装git filter-repo
   Windows用户可以通过Chocolatey安装：choco install git-filter-repo；macOS用Homebrew：brew install git-filter-repo；Linux可以直接从官方仓库下载脚本，或者用系统包管理器安装。

2. 在本地仓库中执行清理命令
   进入你的本地仓库目录，运行以下命令移除所有历史中的指定.war文件：

   git filter-repo --path target/file1.war --invert-paths
   git filter-repo --path target/file2.war --invert-paths
   git filter-repo --path target/file.war --invert-paths
   

   如果你想一次性移除所有.war文件，可以用：

   git filter-repo --path-glob '*.war' --invert-paths
   

3. 强制推送到GitHub远程
   清理完成后，用强制推送覆盖GitHub上的仓库（注意：如果仓库已经有其他协作者，要提前沟通，因为这会重写历史）：

   git push github main --force
   

4. 清理本地缓存（可选）
   为了彻底清理本地的大文件缓存，运行：

   git reflog expire --expire=now --all
   git gc --prune=now --aggressive
   

另一种方案：使用BFG Repo-Cleaner #

如果你觉得git filter-repo操作复杂，也可以用BFG工具：

1. 下载BFG的jar包
2. 运行命令移除历史中的大文件：

   java -jar bfg.jar --delete-files '*.war' 你的仓库目录
   

3. 之后同样执行git gc和强制推送的步骤。

备注：内容来源于stack exchange，提问作者SamAllium