Git bundle：一份完整的离线备份指南
说到Git仓库备份，大家第一时间想到的可能是git clone。但有没有一种方法，能把整个仓库打包成一个文件，像存档一样随身携带呢？答案就是git bundle。不过，这个看似简单的命令，用起来却有不少门道，稍不注意就可能备份了个“寂寞”。
git bundle create 能否替代 clone 做完整备份？
答案是肯定的，但它的适用场景非常明确：离线环境或单向同步。这个命令的精髓在于，它将整个仓库的Git对象和引用全部打包进一个单一文件，不依赖任何远程服务，也不需要创建裸仓库。从便携性角度看，它比git clone --bare更胜一筹。
然而，一个常见的“坑”就藏在细节里。如果直接对工作目录运行git bundle create，却没有加上--all参数或明确指定引用范围，那么打包出来的很可能只有当前分支的内容。那些至关重要的标签、其他分支、甚至reflog和notes，都会被无情地遗漏。
- 想要一网打尽？必须使用
--all参数，这样才能囊括所有分支和标签。仅仅指定HEAD或main，得到的只是单个分支的快照。 - 如果仓库使用了
git-notes功能，在refs/notes/下存有注释，那么需要显式地将refs/notes/**加入打包范围。 - 打包前，不妨先运行一次
git gc，清理冗余对象，可以有效避免生成的bundle文件体积不必要的膨胀。
bundle 文件如何验证是否完整？
千万别以为文件大小正常或者文件存在就万事大吉。Git本身不会自动校验bundle文件的完整性。一个损坏或被截断的bundle文件，可能在解包到后期才报错，甚至更糟——静默地丢失部分数据。
正确的验证姿势分几步走：
- 首先，使用
git bundle verify repo.bundle。这个命令会检查包的内部结构以及对象的可达性。 - 接着，用
git ls-remote repo.bundle确认一下，所有你期望的引用（比如refs/tags/v1.0和refs/heads/dev）是否都出现在输出列表里。 - 如果追求万无一失，可以创建一个全新的空目录，执行
git init后，再尝试git pull ../repo.bundle --all。看看是否能顺利拉取出所有的分支和标签，这是最彻底的验收测试。
用 bundle 恢复仓库时为什么 missing commit？
恢复时发现提交缺失，这通常是两个环节出了问题：要么是打包时“漏装”了某些引用，要么是恢复时“漏取”了全部内容。必须理解，bundle本质上是一个静态快照，而非智能镜像，它不会自动推导和包含所有依赖关系。
举个例子：某个提交虽然被打包进了bundle文件，但它仅被一个特定的标签所引用。如果打包时遗漏了这个标签，那么恢复时，即便这个提交对象物理存在于包内，git pull也无法将它提取出来——因为没有引用指向它。
- 恢复命令务必使用
git pull repo.bundle --all。记住，git clone repo.bundle默认只抓取HEAD指向的内容。 - 如果原仓库包含一些特殊引用，例如
refs/pull/（PR引用）或refs/replace/（提交替换），必须在create命令中手动列出，bundle不会自动识别这些非标准命名空间。 - 在Windows环境下，如果文件路径包含空格或Unicode字符，某些旧版本的Git在解析
git bundle命令时可能会失败。遇到这类问题，升级到Git 2.35及以上版本通常是有效的解决方案。
bundle 和 bare clone 哪个更适合长期归档？
对于长期归档这个严肃的任务，裸克隆（bare clone）是更稳妥的选择。bundle文件虽然便于传输和携带，但它存在几个固有局限：不支持增量更新、无法用git fsck进行完整性校验、也不能通过git repack来优化存储。长期存放，数据腐化的风险相对更高。
那么，bundle的真正用武之地在哪里？其实在于“临时离线分发”场景：比如向客户交付某个时刻的代码快照、在没有网络连接的环境间迁移仓库、或者在持续集成流水线中传递构建状态。
- 若是出于归档目的，优先选择
git clone --bare克隆一个裸仓库，然后定期运行git fsck检查，最后可以压缩成tar.xz格式保存。 - 如果使用bundle，建议在文件名中加入日期和提交哈希后缀，例如
repo-20240520-，这样既能清晰记录版本，也能避免文件覆盖误操作。a1b2c3d.bundle - 特别注意，不要试图用bundle来备份包含子模块的仓库。子模块的信息不会被自动包含在内，需要额外单独处理。
说到底，bundle的边界非常清晰：它是Git的一个“只读快照封装”工具，而非一个完整的备份系统。当你开始考虑增量备份、定期校验、生命周期管理这些需求时，就该切换回裸仓库配合外部工具链的方案了。
