git-bundle 教程

一句话理解

git bundle 能把仓库引用与对象打成一个可传输文件，接收方可以像远端一样读取它。

什么时候适合用

• 内网隔离、无公网访问
• 一次性传递特定分支历史
• 做可归档的历史快照交付

典型命令

git bundle create repo.bundle main feature/hotfix
git bundle verify repo.bundle
git clone repo.bundle repo-from-bundle

常见工作流

1. 发送方创建 bundle 并校验
2. 通过文件渠道传递 bundle
3. 接收方 clone 或 fetch 这个 bundle

关键边界

• bundle 里有什么，完全取决于你打包了哪些 ref
• 接收方若缺前置对象，可能无法完整应用增量 bundle

!先 verify 再分发

bundle 文件一旦在外部渠道传播，返工成本高。生成后立即 git bundle verify 能提前暴露缺失依赖问题。

常见误区

误区 1：以为 --all 总是最佳选项

很多场景只需要最小引用集，盲目全量会造成大文件和泄露风险。

误区 2：不校验就给接收方

git bundle 把仓库历史打包成单个文件，支持离线克隆和 fetch 操作。理解它时，要把它放在"如何在没有网络连接的环境中传输完整 Git 历史"这个场景中来看。

接收方失败后再排查，沟通与传输成本会放大。

误区 3：把 bundle 当长期实时同步方案

• 在没有网络连接的环境中，用 bundle 文件把完整仓库历史从一台机器传输到另一台。
• 用 git clone repo.bundle 从 bundle 文件创建一个完整仓库，替代网络克隆。
• 创建增量 bundle，只打包上次传输后新增的提交，减少传输量。

bundle 更适合“批量快照式”交换，不适合高频双向协作。

接下来建议继续看什么

输入

仓库历史引用范围

→git bundle

结果

单个 bundle 文件可离线传输的完整历史

bundle 文件可以被另一个仓库当作远端使用，支持 clone 和 fetch。

1. git-fetch
2. git-request-pull
3. cross repository integration workflow

• bundle 适合离线传输历史，但创建时需要确保包含所有必要的祖先提交，否则接收端可能缺少必需的提交。
• 接收端可以用 git clone repo.bundle 从零创建仓库，也可以用 git fetch repo.bundle 增量更新已有仓库。
• 创建 bundle 前可以用 git bundle verify 检查文件是否完整、是否包含所需的引用。
• 如果 bundle 只包含部分引用范围，接收端 clone 后可能只有指定的分支，需要额外 fetch 其他分支。

延伸阅读

继续搭配 git status、git log、git show 一起看，通常更容易判断这条命令对历史、索引和工作区分别造成了什么影响。