Merge branch 'rs/archive'
[git/builtin-gsoc.git] / Documentation / git-bundle.txt
blob5051e2bada6d2409f40a04bbd25a5201df7d836e
1 git-bundle(1)
2 =============
4 NAME
5 ----
6 git-bundle - Move objects and refs by archive
9 SYNOPSIS
10 --------
11 [verse]
12 'git-bundle' create <file> [git-rev-list args]
13 'git-bundle' verify <file>
14 'git-bundle' list-heads <file> [refname...]
15 'git-bundle' unbundle <file> [refname...]
17 DESCRIPTION
18 -----------
20 Some workflows require that one or more branches of development on one
21 machine be replicated on another machine, but the two machines cannot
22 be directly connected so the interactive git protocols (git, ssh,
23 rsync, http) cannot be used.  This command provides support for
24 git-fetch and git-pull to operate by packaging objects and references
25 in an archive at the originating machine, then importing those into
26 another repository using gitlink:git-fetch[1] and gitlink:git-pull[1]
27 after moving the archive by some means (i.e., by sneakernet).  As no
28 direct connection between repositories exists, the user must specify a
29 basis for the bundle that is held by the destination repository: the
30 bundle assumes that all objects in the basis are already in the
31 destination repository.
33 OPTIONS
34 -------
36 create <file>::
37        Used to create a bundle named 'file'.  This requires the
38        git-rev-list arguments to define the bundle contents.
40 verify <file>::
41        Used to check that a bundle file is valid and will apply
42        cleanly to the current repository.  This includes checks on the
43        bundle format itself as well as checking that the prerequisite
44        commits exist and are fully linked in the current repository.
45        git-bundle prints a list of missing commits, if any, and exits
46        with non-zero status.
48 list-heads <file>::
49        Lists the references defined in the bundle.  If followed by a
50        list of references, only references matching those given are
51        printed out.
53 unbundle <file>::
54        Passes the objects in the bundle to gitlink:git-index-pack[1]
55        for storage in the repository, then prints the names of all
56        defined references. If a reflist is given, only references
57        matching those in the given list are printed. This command is
58        really plumbing, intended to be called only by
59        gitlink:git-fetch[1].
61 [git-rev-list-args...]::
62        A list of arguments, acceptable to git-rev-parse and
63        git-rev-list, that specify the specific objects and references
64        to transport.  For example, "master~10..master" causes the
65        current master reference to be packaged along with all objects
66        added since its 10th ancestor commit.  There is no explicit
67        limit to the number of references and objects that may be
68        packaged.
71 [refname...]::
72        A list of references used to limit the references reported as
73        available. This is principally of use to git-fetch, which
74        expects to receive only those references asked for and not
75        necessarily everything in the pack (in this case, git-bundle is
76        acting like gitlink:git-fetch-pack[1]).
78 SPECIFYING REFERENCES
79 ---------------------
81 git-bundle will only package references that are shown by
82 git-show-ref: this includes heads, tags, and remote heads.  References
83 such as master~1 cannot be packaged, but are perfectly suitable for
84 defining the basis.  More than one reference may be packaged, and more
85 than one basis can be specified.  The objects packaged are those not
86 contained in the union of the given bases.  Each basis can be
87 specified explicitly (e.g., ^master~10), or implicitly (e.g.,
88 master~10..master, master --since=10.days.ago).
90 It is very important that the basis used be held by the destination.
91 It is okay to err on the side of conservatism, causing the bundle file
92 to contain objects already in the destination as these are ignored
93 when unpacking at the destination.
95 EXAMPLE
96 -------
98 Assume two repositories exist as R1 on machine A, and R2 on machine B.
99 For whatever reason, direct connection between A and B is not allowed,
100 but we can move data from A to B via some mechanism (CD, email, etc).
101 We want to update R2 with developments made on branch master in R1.
102 We set a tag in R1 (lastR2bundle) after the previous such transport,
103 and move it afterwards to help build the bundle.
105 in R1 on A:
106 $ git-bundle create mybundle master ^lastR2bundle
107 $ git tag -f lastR2bundle master
109 (move mybundle from A to B by some mechanism)
111 in R2 on B:
112 $ git-bundle verify mybundle
113 $ git-fetch mybundle  refspec
115 where refspec is refInBundle:localRef
118 Also, with something like this in your config:
120 [remote "bundle"]
121     url = /home/me/tmp/file.bdl
122     fetch = refs/heads/*:refs/remotes/origin/*
124 You can first sneakernet the bundle file to ~/tmp/file.bdl and
125 then these commands:
127 $ git ls-remote bundle
128 $ git fetch bundle
129 $ git pull bundle
131 would treat it as if it is talking with a remote side over the
132 network.
134 Author
135 ------
136 Written by Mark Levedahl <mdl123@verizon.net>
140 Part of the gitlink:git[7] suite