1GIT-BUNDLE(1) Git Manual GIT-BUNDLE(1)
2
6 git-bundle - Move objects and refs by archive
7
9 git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]
10 [--version=<version>] <file> <git-rev-list-args>
11 git bundle verify [-q | --quiet] <file>
12 git bundle list-heads <file> [<refname>...]
13 git bundle unbundle <file> [<refname>...]
14
16 Some workflows require that one or more branches of development on one
17 machine be replicated on another machine, but the two machines cannot
18 be directly connected, and therefore the interactive Git protocols
19 (git, ssh, http) cannot be used.
20 The git bundle command packages objects and references in an archive at
22 the originating machine, which can then be imported into another
23 repository using git fetch, git pull, or git clone, after moving the
24 archive by some means (e.g., by sneakernet).
25 As no direct connection between the repositories exists, the user must
27 specify a basis for the bundle that is held by the destination
28 repository: the bundle assumes that all objects in the basis are
29 already in the destination repository.
30
32 create [options] <file> <git-rev-list-args>
33 Used to create a bundle named file. This requires the
34 <git-rev-list-args> arguments to define the bundle contents.
35 options contains the options specific to the git bundle create
36 subcommand.
37 verify <file>
39 Used to check that a bundle file is valid and will apply cleanly to
40 the current repository. This includes checks on the bundle format
41 itself as well as checking that the prerequisite commits exist and
42 are fully linked in the current repository. git bundle prints a
43 list of missing commits, if any, and exits with a non-zero status.
44 list-heads <file>
46 Lists the references defined in the bundle. If followed by a list
47 of references, only references matching those given are printed
48 out.
49 unbundle <file>
51 Passes the objects in the bundle to git index-pack for storage in
52 the repository, then prints the names of all defined references. If
53 a list of references is given, only references matching those in
54 the list are printed. This command is really plumbing, intended to
55 be called only by git fetch.
56 <git-rev-list-args>
58 A list of arguments, acceptable to git rev-parse and git rev-list
59 (and containing a named ref, see SPECIFYING REFERENCES below), that
60 specifies the specific objects and references to transport. For
61 example, master~10..master causes the current master reference to
62 be packaged along with all objects added since its 10th ancestor
63 commit. There is no explicit limit to the number of references and
64 objects that may be packaged.
65 [<refname>...]
67 A list of references used to limit the references reported as
68 available. This is principally of use to git fetch, which expects
69 to receive only those references asked for and not necessarily
70 everything in the pack (in this case, git bundle acts like git
71 fetch-pack).
72 --progress
74 Progress status is reported on the standard error stream by default
75 when it is attached to a terminal, unless -q is specified. This
76 flag forces progress status even if the standard error stream is
77 not directed to a terminal.
78 --all-progress
80 When --stdout is specified then progress report is displayed during
81 the object count and compression phases but inhibited during the
82 write-out phase. The reason is that in some cases the output stream
83 is directly linked to another command which may wish to display
84 progress status of its own as it processes incoming pack data. This
85 flag is like --progress except that it forces progress report for
86 the write-out phase as well even if --stdout is used.
87 --all-progress-implied
89 This is used to imply --all-progress whenever progress display is
90 activated. Unlike --all-progress this flag doesn’t actually force
91 any progress display by itself.
92 --version=<version>
94 Specify the bundle version. Version 2 is the older format and can
95 only be used with SHA-1 repositories; the newer version 3 contains
96 capabilities that permit extensions. The default is the oldest
97 supported format, based on the hash algorithm in use.
98 -q, --quiet
100 This flag makes the command not to report its progress on the
101 standard error stream.
102
104 git bundle will only package references that are shown by git show-ref:
105 this includes heads, tags, and remote heads. References such as
106 master~1 cannot be packaged, but are perfectly suitable for defining
107 the basis. More than one reference may be packaged, and more than one
108 basis can be specified. The objects packaged are those not contained in
109 the union of the given bases. Each basis can be specified explicitly
110 (e.g. ^master~10), or implicitly (e.g. master~10..master,
111 --since=10.days.ago master).
112 It is very important that the basis used be held by the destination. It
114 is okay to err on the side of caution, causing the bundle file to
115 contain objects already in the destination, as these are ignored when
116 unpacking at the destination.
117 git clone can use any bundle created without negative refspecs (e.g.,
119 new, but not old..new). If you want to match git clone --mirror, which
120 would include your refs such as refs/remotes/*, use --all. If you want
121 to provide the same set of refs that a clone directly from the source
122 repository would get, use --branches --tags for the
123 <git-rev-list-args>.
124
126 Assume you want to transfer the history from a repository R1 on machine
127 A to another repository R2 on machine B. For whatever reason, direct
128 connection between A and B is not allowed, but we can move data from A
129 to B via some mechanism (CD, email, etc.). We want to update R2 with
130 development made on the branch master in R1.
131 To bootstrap the process, you can first create a bundle that does not
133 have any basis. You can use a tag to remember up to what commit you
134 last processed, in order to make it easy to later update the other
135 repository with an incremental bundle:
136 machineA$ cd R1
138 machineA$ git bundle create file.bundle master
139 machineA$ git tag -f lastR2bundle master
140 Then you transfer file.bundle to the target machine B. Because this
142 bundle does not require any existing object to be extracted, you can
143 create a new repository on machine B by cloning from it:
144 machineB$ git clone -b master /home/me/tmp/file.bundle R2
146 This will define a remote called "origin" in the resulting repository
148 that lets you fetch and pull from the bundle. The $GIT_DIR/config file
149 in R2 will have an entry like this:
150 [remote "origin"]
152 url = /home/me/tmp/file.bundle
153 fetch = refs/heads/*:refs/remotes/origin/*
154 To update the resulting mine.git repository, you can fetch or pull
156 after replacing the bundle stored at /home/me/tmp/file.bundle with
157 incremental updates.
158 After working some more in the original repository, you can create an
160 incremental bundle to update the other repository:
161 machineA$ cd R1
163 machineA$ git bundle create file.bundle lastR2bundle..master
164 machineA$ git tag -f lastR2bundle master
165 You then transfer the bundle to the other machine to replace
167 /home/me/tmp/file.bundle, and pull from it.
168 machineB$ cd R2
170 machineB$ git pull
171 If you know up to what commit the intended recipient repository should
173 have the necessary objects, you can use that knowledge to specify the
174 basis, giving a cut-off point to limit the revisions and objects that
175 go in the resulting bundle. The previous example used the lastR2bundle
176 tag for this purpose, but you can use any other options that you would
177 give to the git-log(1) command. Here are more examples:
178 You can use a tag that is present in both:
180 $ git bundle create mybundle v1.0.0..master
182 You can use a basis based on time:
184 $ git bundle create mybundle --since=10.days master
186 You can use the number of commits:
188 $ git bundle create mybundle -10 master
190 You can run git-bundle verify to see if you can extract from a bundle
192 that was created with a basis:
193 $ git bundle verify mybundle
195 This will list what commits you must have in order to extract from the
197 bundle and will error out if you do not have them.
198 A bundle from a recipient repository’s point of view is just like a
200 regular repository which it fetches or pulls from. You can, for
201 example, map references when fetching:
202 $ git fetch mybundle master:localRef
204 You can also see what references it offers:
206 $ git ls-remote mybundle
208
210 Part of the git(1) suite
211Git 2.31.1 2021-03-26 GIT-BUNDLE(1)