GitLab项目远程历史文件迁移至Git LFS的问题及解决方案求助

我近期为GitLab项目启用Git LFS并成功提交了一个200MB文件，已验证远程仓库中该文件标记为LFS。此前提交的几个未使用LFS的10MB.pkl文件也存于远程仓库，想知道将它们迁移至LFS的最佳方法。

我尝试执行以下命令：

git lfs migrate import --everything --include="*.pkl" --verbose

但执行git push时出现错误：

! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'yourgit.internal.yourdomain.com:<user>/project.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

执行git pull也无法解决问题。请问：

1. 迁移现有文件至LFS的正确方法是什么？
2. 在迁移命令中添加--include-ref=refs/heads/master是否有用？
3. 针对其他分支是否需要额外操作？

失败原因分析 #

使用--everything参数会重写仓库所有分支的提交历史，导致本地分支与远程分支的提交记录完全不一致，因此推送会被拒绝。git pull无法解决这个问题，因为拉取后会产生合并提交，而我们的目标是替换历史而非合并。

正确迁移步骤 #

1. 备份仓库（必做） #

先克隆一份全新的远程仓库到本地作为备份，防止操作失误丢失数据：

git clone yourgit.internal.yourdomain.com:<user>/project.git project-backup

2. 针对目标分支迁移（以master为例） #

如果仅需迁移master分支的历史文件，用--include-ref指定分支，避免修改其他分支的历史：

git lfs migrate import --include-ref=refs/heads/master --include="*.pkl" --verbose

该命令仅重写master分支中所有.pkl文件的提交历史，将它们转换为LFS对象。

3. 强制推送重写后的分支 #

由于修改了提交历史，必须通过强制推送覆盖远程分支：

git push origin master --force

注意：强制推送会覆盖远程分支的历史，务必提前告知团队成员，且所有人后续需要重新拉取仓库，避免本地历史冲突。

4. 处理其他分支 #

若其他分支也存在未使用LFS的.pkl文件，需对每个分支重复以下操作：

• 切换到目标分支：git checkout feature-branch
• 执行迁移命令：git lfs migrate import --include-ref=refs/heads/feature-branch --include="*.pkl" --verbose
• 强制推送分支：git push origin feature-branch --force

5. 清理本地冗余对象（可选） #

迁移完成后，可清理本地仓库中不再需要的非LFS文件对象，释放存储空间：

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

关于--include-ref的作用 #

这个参数非常实用，它能精准指定需要迁移的分支，避免--everything带来的全分支历史重写，减少不必要的冲突和操作风险。如果仅需处理master分支，添加该参数是最优选择。

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