Git bundle 离线仓库迁移与备份

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

关键结论

• git bundle 可以把 Git 仓库打包为单个 .bundle 文件，适合无网络或隔离网络环境下传输代码。
• bundle 可以被 git clone、git fetch、git pull 当作远程数据源使用。
• bundle 支持增量导出，只打包指定范围内新增的提交。
• 适合离线迁移仓库、归档备份、跨网络边界传递代码。
• 本条目只讲单文件离线打包与导入，不负责完整 refs 镜像或多远程迁移流程；这些场景应优先查看 mirror-migration.md。

详细分析

• bundle 本质上是 packfile + refs 的封装，保存了导入目标所需的对象和引用信息。
• 与普通压缩源码目录不同，bundle 保留 Git 历史结构，因此可以继续用于克隆、拉取和增量更新。
• 可以只导出某个分支、某组 tag，或者使用 --all 导出全部可达对象。
• 增量 bundle 只包含指定提交范围内的新对象，因此前提是目标仓库已经具备基础提交历史。
• 如果需求是“把一个仓库的所有 refs 完整搬到新远端”，bundle 不是首选，应优先使用 git clone --mirror / git push --mirror。

可执行步骤

1. 在源仓库执行 git bundle create repo.bundle --all，生成完整 bundle 文件。
2. 使用 git bundle verify repo.bundle 检查 bundle 是否完整、是否满足依赖关系。
3. 在目标环境通过 git clone repo.bundle repo 创建离线仓库副本。
4. 如果只需要传输后续变更，在源仓库执行 git bundle create update.bundle <commit>..HEAD 生成增量 bundle。
5. 在目标仓库按需使用 git fetch ../update.bundle <branch>:<branch> 或 git pull ../update.bundle <branch> 导入新增提交。

命令 / 配置 / 代码

git bundle create repo.bundle --all
git bundle verify repo.bundle
git clone repo.bundle repo
git bundle create update.bundle A..B
git fetch ../update.bundle main:main
git pull ../update.bundle main

风险与注意事项

• 增量 bundle 依赖已有基础提交；如果目标仓库缺少前置 commit，增量导入会失败。
• bundle 不是实时同步机制，每次传输新提交都需要重新生成 bundle 文件。
• 使用分支范围或提交范围创建 bundle 时，应确认目标所需的 tag、分支和历史都已包含。

关联条目

• 完整 refs 镜像与远程迁移见 Git 仓库迁移时如何完整保全所有远程分支与 refs。
• 路径级历史删除和重写流程可继续在私有知识库中维护；公开版未收录该条目。