English ▾ 主题 ▾ 最新版本 ▾ 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 文件进行操作。可以从bundle git-clone[1] 一个新的存储库，可以使用 git-fetch[1] 从一个 bundle 文件中获取，并使用 git-ls-remote[1] 列出其中包含的引用。没有相应的“写入”支持，即不支持 git push 到 bundle 中。

BUNDLE 格式

Bundle 是 .pack 文件（请参阅 git-pack-objects[1]），带有一个标头，指示 bundle 中包含哪些引用。

与打包归档格式本身一样，bundle 可以是独立的，也可以使用排除项创建。请参阅下面的“对象前提条件”部分。

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

使用修订排除项时，没有创建“thick pack”的选项，用户无需担心两者之间的差异。通过使用“thin packs”，使用排除项创建的 bundle 尺寸更小。此处仅出于好奇心以及作为其他文档的参考而说明它们在底层是“thin”。

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

选项

create [选项] <文件> <git-rev-list-args>

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

verify <文件>

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

list-heads <文件>

列出 bundle 中定义的引用。 如果后跟引用列表，则仅打印与给定引用匹配的引用。 如果 file 是 -，则从标准输入读取 bundle。

unbundle <文件>

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

<git-rev-list-args>

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

[<refname>…​]

用于限制报告为可用的引用的引用列表。 这主要供 git fetch 使用，后者期望仅接收请求的那些引用，而不一定接收包中的所有内容（在这种情况下，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

但请再次注意，这仅适用于引用，即您将仅包括引用和可从这些引用访问的提交。 您将不包括其他本地状态，例如索引、工作树、储藏库、每个存储库配置、hooks 等的内容。

稍后您可以使用例如 git-clone[1] 恢复该存储库

$ git clone backup.bundle <new directory>

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

为了引导这个过程，您可以首先创建一个没有任何先决条件的包。您可以使用一个标签来记住您上次处理到的提交，以便以后轻松地使用增量包更新另一个存储库。

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

然后，您将 file.bundle 文件传输到目标机器 B。因为此包不需要提取任何现有对象，所以您可以通过克隆它在机器 B 上创建一个新的存储库。

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

这将会在生成的存储库中定义一个名为“origin”的远程仓库，允许您从包中获取 (fetch) 和拉取 (pull)。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 的包替换为增量更新后，进行获取 (fetch) 或拉取 (pull) 操作。

在原始存储库中进行更多工作后，您可以创建一个增量包来更新另一个存储库。

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

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

machineB$ cd R2
machineB$ git pull

如果您知道目标接收方存储库应该包含哪些提交对象，则可以使用该知识来指定先决条件，提供一个截止点来限制包含在生成的包中的修订和对象。前面的示例使用了 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 来查看是否可以从使用先决条件创建的包中提取内容。

$ git bundle verify mybundle

这将列出您必须拥有的提交，以便从包中提取内容，如果您没有这些提交，将会报错。

从接收方存储库的角度来看，包就像一个常规存储库，可以从中获取 (fetch) 或拉取 (pull)。例如，您可以在获取时映射引用。

$ git fetch mybundle master:localRef

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

$ git ls-remote mybundle

讨论

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

因此，建议使用 Git 工具来创建存储库备份，可以使用此命令或 git-clone[1] 等命令。但请记住，这些工具不会帮助您备份引用和提交之外的状态。换句话说，它们不会帮助您备份索引、工作树、暂存区、每个存储库的配置、钩子等内容。

另请参见 gitfaq[7] 的 "TRANSFERS" 部分，了解跨系统文件同步相关的问题。

文件格式

请参阅 gitformat-bundle[5]。

GIT

属于 git[1] 套件的一部分。

scroll-to-top