git bundle手册

 SYNOPSIS

gitbundle create <file><git-rev-list-args> git bundle verify<file> gitbundle list-heads <file>[<refname>…] git bundle unbundle<file>[<refname>…]

DESCRIPTION

Some workflowsrequire that one or more branches of development on one machine bereplicated on another machine, but the two machines cannot bedirectly connected, and therefore the interactive git protocols(git, ssh, rsync, http) cannot be used. This command providessupport for gitfetch and git pull to operate bypackaging objects and references in an archive at the originatingmachine, then importing those into another repositoryusing gitfetch and git pull after moving thearchive by some means (e.g., by sneakernet). As no directconnection between the repositories exists, the user must specify abasis for the bundle that is held by the destination repository:the bundle assumes that all objects in the basis are already in thedestination repository.

OPTIONS

create <file>

Used to createa bundle named file.This requires the git-rev-list-args arguments todefine the bundle contents.

verify <file>

Used to checkthat a bundle file is valid and will apply cleanly to the currentrepository. This includes checks on the bundle format itself aswell as checking that the prerequisite commits exist and are fullylinked in the current repository. git bundle prints a list ofmissing commits, if any, and exits with a non-zero status.

list-heads <file>

Lists thereferences defined in the bundle. If followed by a list ofreferences, only references matching those given are printedout.

unbundle <file>

Passes theobjects in the bundle to git index-pack for storage inthe repository, then prints the names of all defined references. Ifa list of references is given, only references matching those inthe list are printed. This command is really plumbing, intended tobe called only by gitfetch.

<git-rev-list-args>

A list ofarguments, acceptable to gitrev-parse and git rev-list (and containing anamed ref, see SPECIFYING REFERENCES below), that specifies thespecific objects and references to transport. Forexample, master~10..master causes thecurrent master reference to be packaged along with all objectsadded since its 10th ancestor commit. There is no explicit limit tothe number of references and objects that may be packaged.

[<refname>…]

A list ofreferences used to limit the references reported as available. Thisis principally of use togit fetch,which expects to receive only those references asked for and notnecessarily everything in the pack (in thiscase, gitbundle acts like git fetch-pack).

SPECIFYING REFERENCES

git bundle will only packagereferences that are shown by git show-ref: this includes heads, tags, andremote heads. References such as master~1 cannot be packaged,but are perfectly suitable for defining the basis. More than onereference may be packaged, and more than one basis can bespecified. The objects packaged are those not contained in theunion 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).

It is veryimportant that the basis used be held by the destination. It isokay to err on the side of caution, causing the bundle file tocontain objects already in the destination, as these are ignoredwhen unpacking at the destination.

EXAMPLE

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

To bootstrapthe process, you can first create a bundle that does not have anybasis. You can use a tag to remember up to what commit you lastprocessed, in order to make it easy to later update the otherrepository with an incremental bundle:

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

Then youtransfer file.bundle to the target machine B. If you are creatingthe repository on machine B, then you can clone from the bundle asif it were a remote repository instead of creating an emptyrepository and then pulling or fetching objects from thebundle:

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

This willdefine a remote called "origin" in the resulting repository thatlets you fetch and pull from the bundle. The $GIT_DIR/config filein R2 will have an entry like this:

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

To update theresulting mine.git repository, you can fetch or pull afterreplacing the bundle stored at /home/me/tmp/file.bundle withincremental updates.

After workingsome more in the original repository, you can create an incrementalbundle to update the other repository:

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

You thentransfer the bundle to the other machine to replace/home/me/tmp/file.bundle, and pull from it.

machineB$ cd R2machineB$ git pull

If you know upto what commit the intended recipient repository should have thenecessary objects, you can use that knowledge to specify the basis,giving a cut-off point to limit the revisions and objects that goin the resulting bundle. The previous example used the lastR2bundletag for this purpose, but you can use any other options that youwould give to the git-log(1) command.Here are more examples:

You can use atag that is present in both:

$ git bundle create mybundle v1.0.0..master

You can use abasis based on time:

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

You can use thenumber of commits:

$ git bundle create mybundle -10 master

You canrun git-bundleverify to see if you can extract from abundle that was created with a basis:

$ git bundle verify mybundle

This will listwhat commits you must have in order to extract from the bundle andwill error out if you do not have them.

A bundle from arecipient repository’s point of view is just like a regularrepository which it fetches or pulls from. You can, for example,map references when fetching:

$ git fetch mybundle master:localRef

You can alsosee what references it offers:

$ git ls-remote mybundle