Merge branch 'ab/bundle-doc' into maint
Doc update. * ab/bundle-doc: bundle doc: replace "basis" with "prerequsite(s)" bundle doc: elaborate on rev<->ref restriction bundle doc: elaborate on object prerequisites bundle doc: rewrite the "DESCRIPTION" section
This commit is contained in:
Junio C Hamano
commit
dc79a67841
@ -18,21 +18,48 @@ SYNOPSIS
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Some workflows require that one or more branches of development on one
|
||||
machine be replicated on another machine, but the two machines cannot
|
||||
be directly connected, and therefore the interactive Git protocols (git,
|
||||
ssh, http) cannot be used.
|
||||
Create, unpack, and manipulate "bundle" files. Bundles are used for
|
||||
the "offline" transfer of Git objects without an active "server"
|
||||
sitting on the other side of the network connection.
|
||||
|
||||
The 'git bundle' command packages objects and references in an archive
|
||||
at the originating machine, which can then be imported into another
|
||||
repository using 'git fetch', 'git pull', or 'git clone',
|
||||
after moving the archive by some means (e.g., by sneakernet).
|
||||
They can be used to create both incremental and full backups of a
|
||||
repository, and to relay the state of the references in one repository
|
||||
to another.
|
||||
|
||||
As no
|
||||
direct connection between the repositories exists, the user must specify a
|
||||
basis for the bundle that is held by the destination repository: the
|
||||
bundle assumes that all objects in the basis are already in the
|
||||
destination repository.
|
||||
Git commands that fetch or otherwise "read" via protocols such as
|
||||
`ssh://` and `https://` can also operate on bundle files. It is
|
||||
possible linkgit:git-clone[1] a new repository from a bundle, to use
|
||||
linkgit:git-fetch[1] to fetch from one, and to list the references
|
||||
contained within it with linkgit:git-ls-remote[1]. There's no
|
||||
corresponding "write" support, i.e.a 'git push' into a bundle is not
|
||||
supported.
|
||||
|
||||
See the "EXAMPLES" section below for examples of how to use bundles.
|
||||
|
||||
BUNDLE FORMAT
|
||||
-------------
|
||||
|
||||
Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
|
||||
header indicating what references are contained within the bundle.
|
||||
|
||||
Like the the packed archive format itself bundles can either be
|
||||
self-contained, or be created using exclusions.
|
||||
See the "OBJECT PREREQUISITES" section below.
|
||||
|
||||
Bundles created using revision exclusions are "thin packs" created
|
||||
using the `--thin` option to linkgit:git-pack-objects[1], and
|
||||
unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
|
||||
|
||||
There is no option to create a "thick pack" when using revision
|
||||
exclusions, users should not be concerned about the difference. By
|
||||
using "thin packs" bundles created using exclusions are smaller in
|
||||
size. That they're "thin" under the hood is merely noted here as a
|
||||
curiosity, and as a reference to other documentation
|
||||
|
||||
See link:technical/bundle-format.html[the `bundle-format`
|
||||
documentation] for more details and the discussion of "thin pack" in
|
||||
link:technical/pack-format.html[the pack format documentation] for
|
||||
further details.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
@ -117,28 +144,88 @@ unbundle <file>::
|
||||
SPECIFYING REFERENCES
|
||||
---------------------
|
||||
|
||||
'git bundle' will only package references that are shown by
|
||||
'git show-ref': this includes heads, tags, and remote heads. References
|
||||
such as `master~1` cannot be packaged, but are perfectly suitable for
|
||||
defining the basis. More than one reference may be packaged, and more
|
||||
than one basis can be specified. The objects packaged are those not
|
||||
contained in the union of the given bases. Each basis can be
|
||||
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
|
||||
`master~10..master`, `--since=10.days.ago master`).
|
||||
Revisions must accompanied by reference names to be packaged in a
|
||||
bundle.
|
||||
|
||||
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.
|
||||
|
||||
The 'git bundle create' command resolves the reference names for you
|
||||
using the same rules as `git rev-parse --abbrev-ref=loose`. Each
|
||||
prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
|
||||
(e.g. `master~10..master`, `--since=10.days.ago master`).
|
||||
|
||||
All of these simple cases are OK (assuming we have a "master" and
|
||||
"next" branch):
|
||||
|
||||
----------------
|
||||
$ 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
|
||||
----------------
|
||||
|
||||
And so are these (and the same but omitted `--stdin` examples):
|
||||
|
||||
----------------
|
||||
$ git bundle create recent-master.bundle master~10..master
|
||||
$ git bundle create recent-updates.bundle master~10..master next~5..next
|
||||
----------------
|
||||
|
||||
A revision name or a range whose right-hand-side cannot be resolved to
|
||||
a reference is not accepted:
|
||||
|
||||
----------------
|
||||
$ 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.
|
||||
----------------
|
||||
|
||||
OBJECT PREREQUISITES
|
||||
--------------------
|
||||
|
||||
When creating bundles it is possible to create a self-contained bundle
|
||||
that can be unbundled in a repository with no common history, as well
|
||||
as providing negative revisions to exclude objects needed in the
|
||||
earlier parts of the history.
|
||||
|
||||
Feeding a revision such as `new` to `git bundle create` will create a
|
||||
bundle file that contains all the objects reachable from the revision
|
||||
`new`. That bundle can be unbundled in any repository to obtain a full
|
||||
history that leads to the revision `new`:
|
||||
|
||||
----------------
|
||||
$ git bundle create full.bundle new
|
||||
----------------
|
||||
|
||||
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 full.bundle old..new
|
||||
----------------
|
||||
|
||||
A self-contained bundle without any prerequisites can be extracted
|
||||
into anywhere, even into an empty repository, or be cloned from
|
||||
(i.e., `new`, but not `old..new`).
|
||||
|
||||
It is very important that the basis used be held by the destination.
|
||||
It is okay to err on the side of caution, causing the bundle file
|
||||
to contain objects already in the destination, as these are ignored
|
||||
when unpacking at the destination.
|
||||
|
||||
`git clone` can use any bundle created without negative refspecs
|
||||
(e.g., `new`, but not `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>`.
|
||||
|
||||
The 'git bundle verify' command can be used to check whether your
|
||||
recipient repository has the required prerequisite commits for a
|
||||
bundle.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
@ -149,7 +236,7 @@ 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.
|
||||
|
||||
To bootstrap the process, you can first create a bundle that does not have
|
||||
any basis. You can use a tag to remember up to what commit you last
|
||||
any prerequisites. You can use a tag to remember up to what commit you last
|
||||
processed, in order to make it easy to later update the other repository
|
||||
with an incremental bundle:
|
||||
|
||||
@ -200,7 +287,7 @@ machineB$ git pull
|
||||
|
||||
If you know up to what commit the intended recipient repository should
|
||||
have the necessary objects, you can use that knowledge to specify the
|
||||
basis, giving a cut-off point to limit the revisions and objects that go
|
||||
prerequisites, giving a cut-off point to limit the revisions and objects that go
|
||||
in the resulting bundle. The previous example used the lastR2bundle tag
|
||||
for this purpose, but you can use any other options that you would give to
|
||||
the linkgit:git-log[1] command. Here are more examples:
|
||||
@ -211,7 +298,7 @@ You can use a tag that is present in both:
|
||||
$ git bundle create mybundle v1.0.0..master
|
||||
----------------
|
||||
|
||||
You can use a basis based on time:
|
||||
You can use a prerequisite based on time:
|
||||
|
||||
----------------
|
||||
$ git bundle create mybundle --since=10.days master
|
||||
@ -224,7 +311,7 @@ $ git bundle create mybundle -10 master
|
||||
----------------
|
||||
|
||||
You can run `git-bundle verify` to see if you can extract from a bundle
|
||||
that was created with a basis:
|
||||
that was created with a prerequisite:
|
||||
|
||||
----------------
|
||||
$ git bundle verify mybundle
|
||||
|
||||
Loading…
Reference in New Issue
Block a user