]>
Commit | Line | Data |
---|---|---|
2e0afafe JS |
1 | git-bundle(1) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-bundle - Move objects and refs by archive | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
e448ff87 | 11 | [verse] |
c5aecfc8 | 12 | 'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] |
13 | [--version=<version>] <file> <git-rev-list-args> | |
e0eba649 | 14 | 'git bundle' verify [-q | --quiet] <file> |
62b4698e | 15 | 'git bundle' list-heads <file> [<refname>...] |
d941cc4c | 16 | 'git bundle' unbundle [--progress] <file> [<refname>...] |
2e0afafe JS |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
20 | ||
5c8273d5 ÆAB |
21 | Create, unpack, and manipulate "bundle" files. Bundles are used for |
22 | the "offline" transfer of Git objects without an active "server" | |
23 | sitting on the other side of the network connection. | |
24 | ||
25 | They can be used to create both incremental and full backups of a | |
26 | repository, and to relay the state of the references in one repository | |
27 | to another. | |
28 | ||
29 | Git commands that fetch or otherwise "read" via protocols such as | |
30 | `ssh://` and `https://` can also operate on bundle files. It is | |
31 | possible linkgit:git-clone[1] a new repository from a bundle, to use | |
32 | linkgit:git-fetch[1] to fetch from one, and to list the references | |
33 | contained within it with linkgit:git-ls-remote[1]. There's no | |
34 | corresponding "write" support, i.e.a 'git push' into a bundle is not | |
35 | supported. | |
36 | ||
37 | See the "EXAMPLES" section below for examples of how to use bundles. | |
38 | ||
39 | BUNDLE FORMAT | |
40 | ------------- | |
41 | ||
42 | Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a | |
43 | header indicating what references are contained within the bundle. | |
44 | ||
c9dba103 | 45 | Like the packed archive format itself bundles can either be |
5c8273d5 | 46 | self-contained, or be created using exclusions. |
9ab80dd6 | 47 | See the "OBJECT PREREQUISITES" section below. |
5c8273d5 ÆAB |
48 | |
49 | Bundles created using revision exclusions are "thin packs" created | |
50 | using the `--thin` option to linkgit:git-pack-objects[1], and | |
51 | unbundled using the `--fix-thin` option to linkgit:git-index-pack[1]. | |
52 | ||
53 | There is no option to create a "thick pack" when using revision | |
a4dfb449 MÅ |
54 | exclusions, and users should not be concerned about the difference. By |
55 | using "thin packs", bundles created using exclusions are smaller in | |
5c8273d5 | 56 | size. That they're "thin" under the hood is merely noted here as a |
a4dfb449 | 57 | curiosity, and as a reference to other documentation. |
5c8273d5 | 58 | |
844739ba | 59 | See linkgit:gitformat-bundle[5] for more details and the discussion of |
977c47b4 | 60 | "thin pack" in linkgit:gitformat-pack[5] for further details. |
2e0afafe JS |
61 | |
62 | OPTIONS | |
63 | ------- | |
64 | ||
79862b6b | 65 | create [options] <file> <git-rev-list-args>:: |
a6190565 | 66 | Used to create a bundle named 'file'. This requires the |
0e40a73a | 67 | '<git-rev-list-args>' arguments to define the bundle contents. |
79862b6b RJ |
68 | 'options' contains the options specific to the 'git bundle create' |
69 | subcommand. | |
2e0afafe JS |
70 | |
71 | verify <file>:: | |
a6190565 MG |
72 | Used to check that a bundle file is valid and will apply |
73 | cleanly to the current repository. This includes checks on the | |
74 | bundle format itself as well as checking that the prerequisite | |
75 | commits exist and are fully linked in the current repository. | |
017303eb DS |
76 | Then, 'git bundle' prints a list of missing commits, if any. |
77 | Finally, information about additional capabilities, such as "object | |
844739ba | 78 | filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5] |
017303eb DS |
79 | for more information. The exit code is zero for success, but will |
80 | be nonzero if the bundle file is invalid. | |
2e0afafe JS |
81 | |
82 | list-heads <file>:: | |
a6190565 MG |
83 | Lists the references defined in the bundle. If followed by a |
84 | list of references, only references matching those given are | |
85 | printed out. | |
2e0afafe JS |
86 | |
87 | unbundle <file>:: | |
a6190565 MG |
88 | Passes the objects in the bundle to 'git index-pack' |
89 | for storage in the repository, then prints the names of all | |
90 | defined references. If a list of references is given, only | |
91 | references matching those in the list are printed. This command is | |
92 | really plumbing, intended to be called only by 'git fetch'. | |
2e0afafe | 93 | |
5e1f9605 | 94 | <git-rev-list-args>:: |
a6190565 | 95 | A list of arguments, acceptable to 'git rev-parse' and |
469bfc96 | 96 | 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES |
1884df1a | 97 | below), that specifies the specific objects and references |
6cf378f0 | 98 | to transport. For example, `master~10..master` causes the |
a6190565 MG |
99 | current master reference to be packaged along with all objects |
100 | added since its 10th ancestor commit. There is no explicit | |
101 | limit to the number of references and objects that may be | |
102 | packaged. | |
2e0afafe JS |
103 | |
104 | ||
62b4698e | 105 | [<refname>...]:: |
a6190565 MG |
106 | A list of references used to limit the references reported as |
107 | available. This is principally of use to 'git fetch', which | |
108 | expects to receive only those references asked for and not | |
109 | necessarily everything in the pack (in this case, 'git bundle' acts | |
110 | like 'git fetch-pack'). | |
2e0afafe | 111 | |
79862b6b RJ |
112 | --progress:: |
113 | Progress status is reported on the standard error stream | |
114 | by default when it is attached to a terminal, unless -q | |
115 | is specified. This flag forces progress status even if | |
116 | the standard error stream is not directed to a terminal. | |
117 | ||
118 | --all-progress:: | |
119 | When --stdout is specified then progress report is | |
120 | displayed during the object count and compression phases | |
121 | but inhibited during the write-out phase. The reason is | |
122 | that in some cases the output stream is directly linked | |
123 | to another command which may wish to display progress | |
124 | status of its own as it processes incoming pack data. | |
125 | This flag is like --progress except that it forces progress | |
126 | report for the write-out phase as well even if --stdout is | |
127 | used. | |
128 | ||
129 | --all-progress-implied:: | |
130 | This is used to imply --all-progress whenever progress display | |
131 | is activated. Unlike --all-progress this flag doesn't actually | |
132 | force any progress display by itself. | |
133 | ||
c5aecfc8 | 134 | --version=<version>:: |
135 | Specify the bundle version. Version 2 is the older format and can only be | |
136 | used with SHA-1 repositories; the newer version 3 contains capabilities that | |
137 | permit extensions. The default is the oldest supported format, based on the | |
138 | hash algorithm in use. | |
139 | ||
79862b6b RJ |
140 | -q:: |
141 | --quiet:: | |
142 | This flag makes the command not to report its progress | |
143 | on the standard error stream. | |
144 | ||
2e0afafe JS |
145 | SPECIFYING REFERENCES |
146 | --------------------- | |
147 | ||
a4dfb449 | 148 | Revisions must be accompanied by reference names to be packaged in a |
0bb92f3a ÆAB |
149 | bundle. |
150 | ||
1d9c8dae | 151 | More than one reference may be packaged, and more than one set of prerequisite objects can |
0bb92f3a | 152 | be specified. The objects packaged are those not contained in the |
1d9c8dae | 153 | union of the prerequisites. |
0bb92f3a ÆAB |
154 | |
155 | The 'git bundle create' command resolves the reference names for you | |
156 | using the same rules as `git rev-parse --abbrev-ref=loose`. Each | |
1d9c8dae | 157 | prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly |
0bb92f3a ÆAB |
158 | (e.g. `master~10..master`, `--since=10.days.ago master`). |
159 | ||
160 | All of these simple cases are OK (assuming we have a "master" and | |
161 | "next" branch): | |
162 | ||
163 | ---------------- | |
164 | $ git bundle create master.bundle master | |
165 | $ echo master | git bundle create master.bundle --stdin | |
166 | $ git bundle create master-and-next.bundle master next | |
167 | $ (echo master; echo next) | git bundle create master-and-next.bundle --stdin | |
168 | ---------------- | |
169 | ||
170 | And so are these (and the same but omitted `--stdin` examples): | |
171 | ||
172 | ---------------- | |
173 | $ git bundle create recent-master.bundle master~10..master | |
174 | $ git bundle create recent-updates.bundle master~10..master next~5..next | |
175 | ---------------- | |
176 | ||
177 | A revision name or a range whose right-hand-side cannot be resolved to | |
178 | a reference is not accepted: | |
179 | ||
180 | ---------------- | |
181 | $ git bundle create HEAD.bundle $(git rev-parse HEAD) | |
182 | fatal: Refusing to create empty bundle. | |
183 | $ git bundle create master-yesterday.bundle master~10..master~5 | |
184 | fatal: Refusing to create empty bundle. | |
185 | ---------------- | |
2e0afafe | 186 | |
9ab80dd6 ÆAB |
187 | OBJECT PREREQUISITES |
188 | -------------------- | |
189 | ||
190 | When creating bundles it is possible to create a self-contained bundle | |
191 | that can be unbundled in a repository with no common history, as well | |
192 | as providing negative revisions to exclude objects needed in the | |
193 | earlier parts of the history. | |
194 | ||
195 | Feeding a revision such as `new` to `git bundle create` will create a | |
196 | bundle file that contains all the objects reachable from the revision | |
197 | `new`. That bundle can be unbundled in any repository to obtain a full | |
198 | history that leads to the revision `new`: | |
199 | ||
200 | ---------------- | |
201 | $ git bundle create full.bundle new | |
202 | ---------------- | |
203 | ||
204 | A revision range such as `old..new` will produce a bundle file that | |
205 | will require the revision `old` (and any objects reachable from it) | |
206 | to exist for the bundle to be "unbundle"-able: | |
207 | ||
208 | ---------------- | |
209 | $ git bundle create full.bundle old..new | |
210 | ---------------- | |
211 | ||
212 | A self-contained bundle without any prerequisites can be extracted | |
213 | into anywhere, even into an empty repository, or be cloned from | |
214 | (i.e., `new`, but not `old..new`). | |
215 | ||
1d52b026 DM |
216 | It is okay to err on the side of caution, causing the bundle file |
217 | to contain objects already in the destination, as these are ignored | |
2e0afafe JS |
218 | when unpacking at the destination. |
219 | ||
0e40a73a PO |
220 | If you want to match `git clone --mirror`, which would include your |
221 | refs such as `refs/remotes/*`, use `--all`. | |
222 | If you want to provide the same set of refs that a clone directly | |
223 | from the source repository would get, use `--branches --tags` for | |
224 | the `<git-rev-list-args>`. | |
225 | ||
9ab80dd6 ÆAB |
226 | The 'git bundle verify' command can be used to check whether your |
227 | recipient repository has the required prerequisite commits for a | |
228 | bundle. | |
229 | ||
76a8788c NTND |
230 | EXAMPLES |
231 | -------- | |
2e0afafe | 232 | |
8aa7eebf NS |
233 | Assume you want to transfer the history from a repository R1 on machine A |
234 | to another repository R2 on machine B. | |
2e0afafe | 235 | For whatever reason, direct connection between A and B is not allowed, |
1d52b026 DM |
236 | but we can move data from A to B via some mechanism (CD, email, etc.). |
237 | We want to update R2 with development made on the branch master in R1. | |
99d8ea2c | 238 | |
1d52b026 | 239 | To bootstrap the process, you can first create a bundle that does not have |
1d9c8dae | 240 | any prerequisites. You can use a tag to remember up to what commit you last |
1d52b026 DM |
241 | processed, in order to make it easy to later update the other repository |
242 | with an incremental bundle: | |
99d8ea2c | 243 | |
8aa7eebf NS |
244 | ---------------- |
245 | machineA$ cd R1 | |
ffe4da15 | 246 | machineA$ git bundle create file.bundle master |
8aa7eebf NS |
247 | machineA$ git tag -f lastR2bundle master |
248 | ---------------- | |
99d8ea2c | 249 | |
b5fb4770 JH |
250 | Then you transfer file.bundle to the target machine B. Because this |
251 | bundle does not require any existing object to be extracted, you can | |
252 | create a new repository on machine B by cloning from it: | |
99d8ea2c | 253 | |
8aa7eebf | 254 | ---------------- |
ded6aa6b | 255 | machineB$ git clone -b master /home/me/tmp/file.bundle R2 |
8aa7eebf | 256 | ---------------- |
2e0afafe | 257 | |
8aa7eebf | 258 | This will define a remote called "origin" in the resulting repository that |
1d52b026 | 259 | lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will |
8aa7eebf | 260 | have an entry like this: |
2e0afafe | 261 | |
8aa7eebf NS |
262 | ------------------------ |
263 | [remote "origin"] | |
ffe4da15 | 264 | url = /home/me/tmp/file.bundle |
8aa7eebf NS |
265 | fetch = refs/heads/*:refs/remotes/origin/* |
266 | ------------------------ | |
267 | ||
1d52b026 DM |
268 | To update the resulting mine.git repository, you can fetch or pull after |
269 | replacing the bundle stored at /home/me/tmp/file.bundle with incremental | |
270 | updates. | |
8aa7eebf | 271 | |
1d52b026 DM |
272 | After working some more in the original repository, you can create an |
273 | incremental bundle to update the other repository: | |
8aa7eebf NS |
274 | |
275 | ---------------- | |
276 | machineA$ cd R1 | |
ffe4da15 | 277 | machineA$ git bundle create file.bundle lastR2bundle..master |
8aa7eebf NS |
278 | machineA$ git tag -f lastR2bundle master |
279 | ---------------- | |
280 | ||
1d52b026 DM |
281 | You then transfer the bundle to the other machine to replace |
282 | /home/me/tmp/file.bundle, and pull from it. | |
8aa7eebf NS |
283 | |
284 | ---------------- | |
285 | machineB$ cd R2 | |
286 | machineB$ git pull | |
287 | ---------------- | |
99d8ea2c | 288 | |
8aa7eebf | 289 | If you know up to what commit the intended recipient repository should |
1d52b026 | 290 | have the necessary objects, you can use that knowledge to specify the |
1d9c8dae | 291 | prerequisites, giving a cut-off point to limit the revisions and objects that go |
5e1f9605 | 292 | in the resulting bundle. The previous example used the lastR2bundle tag |
1d52b026 | 293 | for this purpose, but you can use any other options that you would give to |
8aa7eebf | 294 | the linkgit:git-log[1] command. Here are more examples: |
99d8ea2c | 295 | |
1d52b026 | 296 | You can use a tag that is present in both: |
99d8ea2c | 297 | |
8aa7eebf NS |
298 | ---------------- |
299 | $ git bundle create mybundle v1.0.0..master | |
300 | ---------------- | |
2e0afafe | 301 | |
1d9c8dae | 302 | You can use a prerequisite based on time: |
ee8245b5 | 303 | |
8aa7eebf NS |
304 | ---------------- |
305 | $ git bundle create mybundle --since=10.days master | |
306 | ---------------- | |
2e0afafe | 307 | |
1d52b026 | 308 | You can use the number of commits: |
2e0afafe | 309 | |
8aa7eebf NS |
310 | ---------------- |
311 | $ git bundle create mybundle -10 master | |
312 | ---------------- | |
313 | ||
314 | You can run `git-bundle verify` to see if you can extract from a bundle | |
1d9c8dae | 315 | that was created with a prerequisite: |
8aa7eebf NS |
316 | |
317 | ---------------- | |
b1889c36 | 318 | $ git bundle verify mybundle |
8aa7eebf | 319 | ---------------- |
2e0afafe | 320 | |
8aa7eebf | 321 | This will list what commits you must have in order to extract from the |
1d52b026 | 322 | bundle and will error out if you do not have them. |
2e0afafe | 323 | |
8aa7eebf | 324 | A bundle from a recipient repository's point of view is just like a |
1d52b026 DM |
325 | regular repository which it fetches or pulls from. You can, for example, map |
326 | references when fetching: | |
2e0afafe | 327 | |
8aa7eebf NS |
328 | ---------------- |
329 | $ git fetch mybundle master:localRef | |
330 | ---------------- | |
2e0afafe | 331 | |
5e1f9605 | 332 | You can also see what references it offers: |
2e0afafe | 333 | |
8aa7eebf NS |
334 | ---------------- |
335 | $ git ls-remote mybundle | |
336 | ---------------- | |
2e0afafe | 337 | |
844739ba ÆAB |
338 | FILE FORMAT |
339 | ----------- | |
340 | ||
341 | See linkgit:gitformat-bundle[5]. | |
342 | ||
2e0afafe JS |
343 | GIT |
344 | --- | |
9e1f0a85 | 345 | Part of the linkgit:git[1] suite |