diff options
Diffstat (limited to 'Documentation/git-bundle.txt')
| -rw-r--r-- | Documentation/git-bundle.txt | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt new file mode 100644 index 0000000000..aee7e4a8c9 --- /dev/null +++ b/Documentation/git-bundle.txt @@ -0,0 +1,209 @@ +git-bundle(1) +============= + +NAME +---- +git-bundle - Move objects and refs by archive + + +SYNOPSIS +-------- +[verse] +'git bundle' create <file> <git-rev-list args> +'git bundle' verify <file> +'git bundle' list-heads <file> [refname...] +'git bundle' unbundle <file> [refname...] + +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, rsync, http) cannot be used. This command provides support for +'git-fetch' and 'git-pull' to operate by packaging objects and references +in an archive at the originating machine, then importing those into +another repository using 'git-fetch' and 'git-pull' +after moving the archive by some means (i.e., by sneakernet). 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. + +OPTIONS +------- + +create <file>:: + Used to create a bundle named 'file'. This requires the + 'git-rev-list' arguments to define the bundle contents. + +verify <file>:: + 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. + 'git-bundle' prints a list of missing commits, if any, and exits + with a non-zero status. + +list-heads <file>:: + Lists the references defined in the bundle. If followed by a + list of references, only references matching those given are + printed out. + +unbundle <file>:: + 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'. + +[git-rev-list-args...]:: + A list of arguments, acceptable to 'git-rev-parse' and + 'git-rev-list', 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. + + +[refname...]:: + A list of references used to limit the references reported as + available. This is principally of use to 'git-fetch', which + expects to receive only those references asked for and not + necessarily everything in the pack (in this case, 'git-bundle' acts + like 'git-fetch-pack'). + +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`). + +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. + +EXAMPLE +------- + +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. + +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 +processed, in order to make it easy to later update the other repository +with an incremental bundle: + +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle master +machineA$ git tag -f lastR2bundle master +---------------- + +Then you transfer file.bundle to the target machine B. If you are creating +the repository on machine B, then you can clone from the bundle as if it +were a remote repository instead of creating an empty repository and then +pulling or fetching objects from the bundle: + +---------------- +machineB$ git clone /home/me/tmp/file.bundle R2 +---------------- + +This will define a remote called "origin" in the resulting repository that +lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will +have an entry like this: + +------------------------ +[remote "origin"] + url = /home/me/tmp/file.bundle + fetch = refs/heads/*:refs/remotes/origin/* +------------------------ + +To update the resulting mine.git repository, you can fetch or pull after +replacing the bundle stored at /home/me/tmp/file.bundle with incremental +updates. + +After working some more in the original repository, you can create an +incremental bundle to update the other repository: + +---------------- +machineA$ cd R1 +machineA$ git bundle create file.bundle lastR2bundle..master +machineA$ git tag -f lastR2bundle master +---------------- + +You then transfer the bundle to the other machine to replace +/home/me/tmp/file.bundle, and pull from it. + +---------------- +machineB$ cd R2 +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 +in the resulting bundle. The previous example used 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: + +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: + +---------------- +$ git bundle create mybundle --since=10.days master +---------------- + +You can use the number of commits: + +---------------- +$ 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: + +---------------- +$ git bundle verify mybundle +---------------- + +This will list what commits you must have in order to extract from the +bundle and will error out if you do not have them. + +A bundle from a recipient repository's point of view is just like a +regular repository which it fetches or pulls from. You can, for example, map +references when fetching: + +---------------- +$ git fetch mybundle master:localRef +---------------- + +You can also see what references it offers. + +---------------- +$ git ls-remote mybundle +---------------- + +Author +------ +Written by Mark Levedahl <mdl123@verizon.net> + +GIT +--- +Part of the linkgit:git[1] suite |