AI Notes Public

Appearance

Git 仓库迁移时如何完整保全所有远程分支与 refs ​

  • 状态：已验证
  • 来源：对话整理
  • 更新时间：2026-03-14

关键结论 ​

  • 迁移单个远程仓库时，最稳妥的方法是使用 git clone --mirror 和 git push --mirror。
  • git push --all 只会推送本地分支 refs/heads/*，不能保证迁移所有远程跟踪分支。
  • 如果存在多个旧远程，不能默认它们内容一致；只镜像一个旧远程，可能遗漏另一个远程的独有分支或标签。
  • 对多远程场景，应分别做 mirror 备份，比较 refs/heads 和 refs/tags 后，再执行最终迁移。
  • 在旧远程可能失联的场景下，除了 mirror 仓库，建议额外生成 bundle 作为单文件离线备份。
  • 本文聚焦 refs 级保全与远程迁移，不负责路径级历史清理；相关内容在私有知识库中继续维护，公开版未收录。
  • 如果只需要单文件离线传递或归档快照，应优先查看 Git bundle 离线仓库迁移与备份。

详细分析 ​

  • git clone --mirror 会镜像源仓库的所有 refs，而不仅仅是普通本地分支，适合做完整仓库迁移和归档。
  • git push --mirror 会将本地 mirror 仓库中的 refs 镜像推送到新远程，适合整体搬迁。
  • 当前工作仓库里看到的 remotes/origin/*、remotes/gitlab/* 只是远程跟踪引用，不等价于本地已创建对应分支。
  • 如果仅在当前开发仓库执行 git push --all，新远程只能拿到本地 branch，未建立本地 branch 的远程内容可能遗漏。
  • 当 origin 和 gitlab 同时存在时，可能出现三类情况：
    • 内容完全一致。
    • 一方有独有分支或标签。
    • 同名分支但历史不同。
  • 第三种情况必须人工判定归属或改名保全，不能直接覆盖。
  • 因此多远程迁移的正确思路不是“随便选一个 remote 镜像出去”，而是先分别抓取完整 refs，再比对 heads 和 tags，最后决定如何合并到新远程。
  • 在旧远程未来可能失联的前提下，mirror 仓库适合保留完整 Git 结构，bundle 则适合作为额外离线备份，两者职责不同且可以并存。
  • 当目标是“保全所有 refs 并迁移到新远端”时，mirror 是主方案；当目标是“生成可携带的单文件备份”时，bundle 是辅助手段。

可执行步骤 ​

  1. 分别对每个旧远程执行镜像克隆。
  2. 分别导出各自的分支和标签列表。
  3. 比较两个远程的 heads 和 tags 差异，确认是否存在独有内容。
  4. 若某一远程可确认是完整主仓库，则直接将该 mirror 迁移到新远程。
  5. 若两个远程各有独有分支或标签，则先选择一个 mirror 推到新远程，再将另一远程独有 refs 逐项补推。
  6. 额外生成 bundle 作为单文件离线备份。
  7. 最后用 git ls-remote 校验新远程中的 heads 和 tags。

命令 / 配置 / 代码 ​

分别镜像旧远程：

bash
git clone --mirror <origin_url> origin.mirror.git
git clone --mirror <gitlab_url> gitlab.mirror.git

单远程完整迁移：

bash
git clone --mirror <old_remote_url> repo.mirror.git
cd repo.mirror.git
git remote set-url origin <new_remote_url>
git push --mirror

导出 heads：

bash
git for-each-ref refs/heads --format='%(refname:short)' | sort

导出 tags：

bash
git for-each-ref refs/tags --format='%(refname:short)' | sort

比较两个远程分支：

bash
comm -3 /tmp/origin_heads.txt /tmp/gitlab_heads.txt

生成 bundle：

bash
git bundle create ../repo-full.bundle --all

校验新远程：

bash
git ls-remote --heads <new_remote_url>
git ls-remote --tags <new_remote_url>

风险与注意事项 ​

  • 只镜像一个旧远程，不能保证覆盖另一个旧远程的独有内容。
  • 多远程中若存在同名分支但提交历史不同，不能直接都推成同名，需要先确认归属。
  • git push --mirror 具有强覆盖语义，目标新仓库应尽量为空仓库或确认可被镜像覆盖。
  • mirror 仓库建议单独创建，不要直接在当前开发工作仓库里混用。
  • 在旧远程仍可访问时，应优先完成 mirror 抓取和本地备份，再做整理和比对。

关联条目 ​

  • 路径级历史删除与重写流程在私有知识库中继续维护，公开版未收录。