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