Git
简体中文 ▾ Topics ▾ Latest version ▾ git-bundle last updated in 2.44.0

名称

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

概述

git bundle create [-q | --quiet | --progress]
		    [--version=<版本>] <文件> <git-rev-list-args>
git bundle verify [-q | --quiet] <文件>
git bundle list-heads <文件> [<引用名>…​]
git bundle unbundle [--progress] <文件> [<引用名>…​]

描述

创建、解包和操作 “打包” 文件。捆绑文件用于 Git 对象的 “离线” 传输,而不需要在网络连接的另一端有一个活跃的 “服务器”。

它们可以用来创建仓库的增量和完全备份,并将一个仓库中的引用状态传递给另一个版本库。

通过 ssh://https:// 等协议获取或以其他方式 “读取” 的 Git 命令也可以对打包文件进行操作。它可以通过 git-clone[1] 从打包中建立新的仓库,用 git-fetch[1] 从其中获取,并通过 git-ls-remote[1] 列出其中的引用。没有相应的 "写" 支持,也就是说,不支持 git push 捆绑包。

关于如何使用捆绑包的例子,见下面的 “实例” 部分。

捆绑包格式

捆绑包是 .pack 文件(见 git-pack-objects[1]),有一个标头说明捆绑包中包含哪些引用。

Like the packed archive format itself bundles can either be self-contained, or be created using exclusions. See the "OBJECT PREREQUISITES" section below.

使用修订版排除法创建的捆绑包是使用 git-pack-objects[1]--thin 选项创建的 “轻量包”,并使用 git-index-pack[1]--fix-thin 选项解除捆绑。

在使用修订排除法时,没有创建 “复杂包” 的选项,用户不应该担心这种差异。通过使用 “轻量包”,使用排除法创建的捆绑文件尺寸较小。它们在引擎盖下是 “薄” 的,在此只是作为一种好奇,并作为其他文档的参考。

更多细节见 gitformat-bundle[5] ,以及 gitformat-pack[5] 中关于 “轻量包” 的讨论。

选项

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

Used to create a bundle named file. This requires the <git-rev-list-args> arguments to define the bundle contents. options contains the options specific to the git bundle create subcommand. If file is -, the bundle is written to stdout.

verify <文件>

Used to check that a bundle file is valid and will apply cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. Then, git bundle prints a list of missing commits, if any. Finally, information about additional capabilities, such as "object filter", is printed. See "Capabilities" in gitformat-bundle[5] for more information. The exit code is zero for success, but will be nonzero if the bundle file is invalid. If file is -, the bundle is read from stdin.

list-heads <文件>

Lists the references defined in the bundle. If followed by a list of references, only references matching those given are printed out. If file is -, the bundle is read from stdin.

unbundle <文件>

Passes the objects in the bundle to git index-pack for storage in the repository, then prints the names of all defined references. If a list of references is given, only references matching those in the list are printed. This command is really plumbing, intended to be called only by git fetch. If file is -, the bundle is read from stdin.

<git-rev-list-args>

A list of arguments, acceptable to git rev-parse and git rev-list (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references to transport. For example, master~10..master causes the current master reference to be packaged along with all objects added since its 10th ancestor commit. There is no explicit limit to the number of references and objects that may be packaged.

[<引用名>…​]

用于限制报告的可用引用的列表。这主要是对 git fetch 有用,它希望只收到那些要求的引用,而不一定是包中的所有内容(在这种情况下, git bundle 就像 git fetch-pack)。

--progress

当标准错误流连接到终端时,除非指定了 -q,否则默认情况下会在标准错误流上报告进展状态。即使标准错误流没有指向终端,这个标志也会强制显示进度状态。

--version=<版本>

Specify the bundle version. Version 2 is the older format and can only be used with SHA-1 repositories; the newer version 3 contains capabilities that permit extensions. The default is the oldest supported format, based on the hash algorithm in use.

-q
--quiet

这个标志使命令不在标准错误流中报告其进度。

指定引用

修订必须附有引用名称,才能打包成捆绑包。

More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the union of the prerequisites.

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: 拒绝产生空捆绑包。
$ git bundle create master-yesterday.bundle master~10..master~5
fatal: 拒绝产生空捆绑包。

对象的先决条件

在创建捆绑包时,可以创建一个独立的捆绑包,可以在没有共同历史的版本库中解绑,也可以提供负修订,以排除历史早期部分所需的对象。

git bundle create 输入诸如`new’这样的修订版将创建一个捆绑包文件,其中包含所有从 new 修订版可以到达的对象。捆绑文件可以在任何版本库中解绑,以获得通往 new 版本的完整历史:

$ git bundle create mybundle -10 master

A revision range such as old..new will produce a bundle file that will require the revision old (and any objects reachable from it) to exist for the bundle to be "unbundle"-able:

$ git bundle create mybundle v1.0.0..master

一个没有任何先决条件的独立软件包可以被提取到任何地方,甚至可以提取到一个空的仓库中,或者被克隆出来(即 new,但不是 old..new)。

谨慎行事是可以的,使捆绑文件包含已经在目的地的对象,因为在目的地解包时这些对象会被忽略。

If you want to match git clone --mirror, which would include your refs such as refs/remotes/*, use --all. If you want to provide the same set of refs that a clone directly from the source repository would get, use --branches --tags for the <git-rev-list-args>.

git bundle verify 命令可以用来检查你的接收库是否有一个捆绑包所需的先决条件提交。

实例

Assume you want to transfer the history from a repository R1 on machine A to another repository R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.

为了启动这个过程,你可以先创建一个没有任何先决条件的捆绑包。你可以使用一个标签来记住你最后处理的提交,以方便以后用增量的捆绑包来更新其他仓库:

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

然后你把 file.bundle 传输到目标机器 B。因为这个捆绑包不需要提取任何现有的对象,你可以通过克隆它在机器 B 上创建一个新的仓库:

机器 B $ git clone -b master /home/me/tmp/file.bundle R2

这将在生成的版本库中定义一个名为 "origin" 的远程,让你从捆绑包中获取和拉取。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 的捆绑包后取用或拉取。

在原始仓库中再工作一段时间后,你可以创建一个增量包来更新另一个版本库:

机器 A $ cd R1
机器 A $ git bundle create file.bundle lastR2bundle..master
机器 A $ git tag -f lastR2bundle master

然后你把捆绑包转移到另一台机器上,以取代 /home/me/tmp/file.bundle,并从其中提取。

机器 B $ cd R2
机器 B $ 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

这将列出你必须有哪些提交才能从捆绑包中提取,如果你没有这些提交就会出错。

从接收者仓库的角度来看,一个捆绑包就像一个普通的仓库,它从那里获取或拉取。例如,你可以在获取的时候映射引用:

$ git fetch mybundle master:localRef

你也可以看看它提供哪些引用:

$ git ls-remote mybundle

文件格式

GIT

属于 git[1] 文档

scroll-to-top