简体中文 ▾ 主题 ▾ 最新版本 ▾ git-bundle 最后更新于 2.48.0

名称

git-bundle - 通过存档移动对象和引用

概要

git bundle create [-q | --quiet | --progress]
		    [--version=<version>] <file> <git-rev-list-args>
git bundle verify [-q | --quiet] <file>
git bundle list-heads <file> [<refname>…​]
git bundle unbundle [--progress] <file> [<refname>…​]

描述

创建、解包和操作“bundle”文件。Bundle 用于 Git 对象的“离线”传输，而无需在网络连接的另一端有一个活动的“服务器”。

它们可用于创建仓库的增量和完整备份（请参阅“示例”中的“完整备份”示例），以及将一个仓库中的引用状态传递到另一个仓库（请参阅第二个示例）。

通过 ssh:// 和 https:// 等协议进行获取或其他“读取”操作的 Git 命令也可以操作 bundle 文件。可以 git-clone[1] 一个新的仓库，可以通过 git-fetch[1] 从 bundle 获取，并使用 git-ls-remote[1] 列出其中包含的引用。没有相应的“写入”支持，即不支持向 bundle 进行 git push。

BUNDLE 格式

Bundle 是 .pack 文件（参见 git-pack-objects[1]），带有指示 bundle 中包含哪些引用的头信息。

与打包的存档格式本身一样，bundle 可以是自包含的，也可以使用排除项创建。请参阅下面的“对象先决条件”部分。

使用修订排除项创建的 Bundle 是使用 git-pack-objects[1] 的 --thin 选项创建的“瘦 pack”，并使用 git-index-pack[1] 的 --fix-thin 选项解包。

在使用修订排除项时，没有创建“厚 pack”的选项，用户不必担心其中的区别。通过使用“瘦 pack”，使用排除项创建的 Bundle 大小更小。它们底层是“瘦”的，这一点在此仅作为一种奇闻和对其他文档的引用。

有关更多详细信息，请参阅 gitformat-bundle[5]，有关“瘦 pack”的讨论，请参阅 gitformat-pack[5]。

选项

create [options] <file> <git-rev-list-args>

用于创建名为 file 的 bundle。这需要 <git-rev-list-args> 参数来定义 bundle 的内容。options 包含 git bundle create 子命令的特定选项。如果 file 是 -，则 bundle 将写入 stdout。

verify <file>

用于检查 bundle 文件是否有效，并且是否能干净地应用于当前仓库。这包括对 bundle 格式本身的检查，以及检查先决条件提交是否存在并已完全链接到当前仓库。然后，git bundle 会打印出缺失的提交列表（如果有）。最后，还会打印有关其他功能（如“对象过滤器”）的信息。有关更多信息，请参阅 gitformat-bundle[5] 中的“功能”部分。退出代码为零表示成功，否则表示 bundle 文件无效。如果 file 是 -，则从 stdin 读取 bundle。

list-heads <file>

列出 bundle 中定义的引用。如果后面跟着一个引用列表，则只打印匹配给定引用的引用。如果 file 是 -，则从 stdin 读取 bundle。

unbundle <file>

将 bundle 中的对象传递给 git index-pack 以便存储在仓库中，然后打印所有已定义引用的名称。如果给出了引用列表，则只打印列表中匹配的引用。此命令实际上是底层的调用命令，仅供 git fetch 调用。如果 file 是 -，则从 stdin 读取 bundle。

<git-rev-list-args>

一个参数列表，可被 git rev-parse 和 git rev-list 接受（并包含一个命名引用，请参阅下面的“指定引用”），用于指定要传输的特定对象和引用。例如，master~10..master 将当前 master 引用及其第 10 个祖先提交以来的所有添加的对象一起打包。引用的数量和打包的对象数量没有明确限制。

[<refname>…​]

一个引用列表，用于限制作为可用的引用。这主要用于 git fetch，后者期望只接收请求的引用，而不是 pack 中的所有内容（在这种情况下，git bundle 的行为类似于 git fetch-pack）。

--progress

默认情况下，当标准错误流连接到终端时，会报告进度状态，除非指定了 -q。此标志强制报告进度状态，即使标准错误流未定向到终端。

--version=<version>

指定 bundle 版本。版本 2 是旧格式，只能与 SHA-1 仓库一起使用；较新的版本 3 包含允许扩展的功能。默认是支持的最旧格式，基于所使用的哈希算法。

-q
--quiet

此标志使命令不会在标准错误流上报告其进度。

指定引用

修订必须附带引用名称才能打包到 bundle 中。或者，可以使用 --all 来打包所有引用。

可以打包多个引用，也可以指定多个先决对象集。打包的对象是那些不包含在先决条件并集中的对象。

git bundle create 命令使用与 git rev-parse --abbrev-ref=loose 相同的规则为您解析引用名称。每个先决条件都可以显式指定（例如，^master~10），或隐式指定（例如，master~10..master，--since=10.days.ago master）。

以下所有简单情况都可以（假设我们有一个“master”和“next”分支）

$ git bundle create master.bundle master
$ echo master | git bundle create master.bundle --stdin
$ git bundle create master-and-next.bundle master next
$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin

以下情况也是如此（省略了相同的 --stdin 示例）

$ git bundle create recent-master.bundle master~10..master
$ git bundle create recent-updates.bundle master~10..master next~5..next

无法解析到引用的修订名称或范围的右侧将不被接受

$ git bundle create HEAD.bundle $(git rev-parse HEAD)
fatal: Refusing to create empty bundle.
$ git bundle create master-yesterday.bundle master~10..master~5
fatal: Refusing to create empty bundle.

对象先决条件

创建 bundle 时，可以创建一个自包含的 bundle，该 bundle 可以在没有共同历史记录的仓库中解包，还可以提供负面修订以排除早期历史记录中需要的对象。

将 new 这样的修订提供给 git bundle create 会创建一个 bundle 文件，其中包含从修订 new 可达的所有对象。该 bundle 可以在任何仓库中解包，以获得导致修订 new 的完整历史记录。

$ git bundle create full.bundle new

像 old..new 这样的修订范围将生成一个 bundle 文件，该文件要求修订 old（以及从它可达的所有对象）存在才能使 bundle“可解包”。

$ git bundle create full.bundle old..new

没有先决条件的自包含 bundle 可以提取到任何地方，即使是空仓库，或者可以从中克隆（即 new，但不能 old..new）。

谨慎行事是可以的，这会导致 bundle 文件包含目的地已有的对象，因为在目的地解包时这些对象会被忽略。

如果您想提供与直接从源仓库克隆所获取的引用集相同的引用集，请为 <git-rev-list-args> 使用 --branches --tags。

git bundle verify 命令可用于检查您的接收方仓库是否具有 bundle 所需的先决条件提交。

示例

我们将讨论两种情况

  1. 备份仓库的完整副本

  2. 在两个机器没有直接连接的情况下，将仓库的历史记录传输到另一台机器

首先，让我们考虑仓库的完整备份。以下命令将对仓库进行完整备份，这意味着所有引用都包含在 bundle 中

$ git bundle create backup.bundle --all

但请再次注意，这仅适用于引用，即您只包含引用以及从这些引用可达的提交。您不会包含其他本地状态，例如索引内容、工作树、暂存区、每个仓库的配置、钩子等。

之后，您可以使用例如 git-clone[1] 来恢复该仓库

$ git clone backup.bundle <new directory>

对于下一个示例，假设您想将仓库 R1（位于机器 A 上）的历史记录传输到仓库 R2（位于机器 B 上）。出于某种原因，不允许 A 和 B 之间直接连接，但我们可以通过某种机制（CD、电子邮件等）将数据从 A 移动到 B。我们想用 R1 中 master 分支的开发更新 R2。

为了启动该过程，您可以先创建一个没有先决条件的 bundle。您可以使用标签来记住您上次处理到哪个提交，以便以后轻松地用增量 bundle 更新其他仓库

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

然后，您将 file.bundle 传输到目标机器 B。由于此 bundle 不需要任何现有对象即可提取，因此您可以在机器 B 上通过克隆它来创建一个新仓库

machineB$ git clone -b master /home/me/tmp/file.bundle R2

这将在生成的仓库中定义一个名为“origin”的远程，让您可以从 bundle 中获取和拉取。R2 中的 $GIT_DIR/config 文件将具有类似以下的条目

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

要更新生成的 mine.git 仓库，您可以在替换 /home/me/tmp/file.bundle 中存储的 bundle 以进行增量更新后，执行 fetch 或 pull 操作。

在原始仓库中进行更多工作后，您可以创建一个增量 bundle 来更新其他仓库

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

然后，您将 bundle 传输到另一台机器以替换 /home/me/tmp/file.bundle，然后从中拉取。

machineB$ cd R2
machineB$ git pull

如果您知道目标仓库应该拥有必要对象的提交截至何处，您可以使用这些知识来指定先决条件，从而给出截止点来限制进入 bundle 的修订和对象。上一个示例为此使用了 lastR2bundle 标签，但您可以使用提供给 git-log[1] 命令的任何其他选项。以下是更多示例

您可以使用两个仓库中都存在的标签

$ git bundle create mybundle v1.0.0..master

您可以使用基于时间的先决条件

$ git bundle create mybundle --since=10.days master

您可以使用提交次数

$ git bundle create mybundle -10 master

您可以运行 git-bundle verify 来查看是否可以从使用先决条件创建的 bundle 中提取

$ git bundle verify mybundle

这将列出您必须拥有的才能从 bundle 中提取的提交，如果缺少它们，则会报错。

从接收方仓库的角度来看，bundle 就像一个常规仓库，它可以从中获取或拉取。例如，您可以在获取时映射引用

$ git fetch mybundle master:localRef

您还可以查看它提供的引用

$ git ls-remote mybundle

讨论

创建仓库完整备份的一种简单方法是使用类似 cp -r <repo> <destination> 的命令。不推荐这样做，因为在复制操作期间仓库可能会被写入。反过来，<destination> 中的某些文件可能会损坏。

这就是为什么建议使用 Git 工具来制作仓库备份，无论是使用此命令还是例如 git-clone[1]。但请记住，这些工具不会帮助您备份除引用和提交以外的状态。换句话说，它们不会帮助您备份索引内容、工作树、暂存区、每个仓库的配置、钩子等。

另请参阅 gitfaq[7]，“传输”部分，了解跨系统进行文件同步问题的讨论。

文件格式

请参阅 gitformat-bundle[5]。

GIT

Git[1] 套件的一部分