fuzz: link fuzz programs with `make all` on Linux
[alt-git.git] / Documentation / git-bundle.txt
blob3ab42a19cae4aca0e6a3a83db92d25a4d88bf927
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 [-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>...]
18 DESCRIPTION
19 -----------
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.
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.
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.
37 See the "EXAMPLES" section below for examples of how to use bundles.
39 BUNDLE FORMAT
40 -------------
42 Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
43 header indicating what references are contained within the bundle.
45 Like the packed archive format itself bundles can either be
46 self-contained, or be created using exclusions.
47 See the "OBJECT PREREQUISITES" section below.
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].
53 There is no option to create a "thick pack" when using revision
54 exclusions, and users should not be concerned about the difference. By
55 using "thin packs", bundles created using exclusions are smaller in
56 size. That they're "thin" under the hood is merely noted here as a
57 curiosity, and as a reference to other documentation.
59 See linkgit:gitformat-bundle[5] for more details and the discussion of
60 "thin pack" in linkgit:gitformat-pack[5] for further details.
62 OPTIONS
63 -------
65 create [options] <file> <git-rev-list-args>::
66         Used to create a bundle named 'file'.  This requires the
67         '<git-rev-list-args>' arguments to define the bundle contents.
68         'options' contains the options specific to the 'git bundle create'
69         subcommand. If 'file' is `-`, the bundle is written to stdout.
71 verify <file>::
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.
76         Then, 'git bundle' prints a list of missing commits, if any.
77         Finally, information about additional capabilities, such as "object
78         filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
79         for more information. The exit code is zero for success, but will
80         be nonzero if the bundle file is invalid. If 'file' is `-`, the
81         bundle is read from stdin.
83 list-heads <file>::
84         Lists the references defined in the bundle.  If followed by a
85         list of references, only references matching those given are
86         printed out. If 'file' is `-`, the bundle is read from stdin.
88 unbundle <file>::
89         Passes the objects in the bundle to 'git index-pack'
90         for storage in the repository, then prints the names of all
91         defined references. If a list of references is given, only
92         references matching those in the list are printed. This command is
93         really plumbing, intended to be called only by 'git fetch'.
94         If 'file' is `-`, the bundle is read from stdin.
96 <git-rev-list-args>::
97         A list of arguments, acceptable to 'git rev-parse' and
98         'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES
99         below), that specifies the specific objects and references
100         to transport.  For example, `master~10..master` causes the
101         current master reference to be packaged along with all objects
102         added since its 10th ancestor commit.  There is no explicit
103         limit to the number of references and objects that may be
104         packaged.
107 [<refname>...]::
108         A list of references used to limit the references reported as
109         available. This is principally of use to 'git fetch', which
110         expects to receive only those references asked for and not
111         necessarily everything in the pack (in this case, 'git bundle' acts
112         like 'git fetch-pack').
114 --progress::
115         Progress status is reported on the standard error stream
116         by default when it is attached to a terminal, unless -q
117         is specified. This flag forces progress status even if
118         the standard error stream is not directed to a terminal.
120 --version=<version>::
121         Specify the bundle version.  Version 2 is the older format and can only be
122         used with SHA-1 repositories; the newer version 3 contains capabilities that
123         permit extensions. The default is the oldest supported format, based on the
124         hash algorithm in use.
126 -q::
127 --quiet::
128         This flag makes the command not to report its progress
129         on the standard error stream.
131 SPECIFYING REFERENCES
132 ---------------------
134 Revisions must be accompanied by reference names to be packaged in a
135 bundle.
137 More than one reference may be packaged, and more than one set of prerequisite objects can
138 be specified.  The objects packaged are those not contained in the
139 union of the prerequisites.
141 The 'git bundle create' command resolves the reference names for you
142 using the same rules as `git rev-parse --abbrev-ref=loose`. Each
143 prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
144 (e.g. `master~10..master`, `--since=10.days.ago master`).
146 All of these simple cases are OK (assuming we have a "master" and
147 "next" branch):
149 ----------------
150 $ git bundle create master.bundle master
151 $ echo master | git bundle create master.bundle --stdin
152 $ git bundle create master-and-next.bundle master next
153 $ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
154 ----------------
156 And so are these (and the same but omitted `--stdin` examples):
158 ----------------
159 $ git bundle create recent-master.bundle master~10..master
160 $ git bundle create recent-updates.bundle master~10..master next~5..next
161 ----------------
163 A revision name or a range whose right-hand-side cannot be resolved to
164 a reference is not accepted:
166 ----------------
167 $ git bundle create HEAD.bundle $(git rev-parse HEAD)
168 fatal: Refusing to create empty bundle.
169 $ git bundle create master-yesterday.bundle master~10..master~5
170 fatal: Refusing to create empty bundle.
171 ----------------
173 OBJECT PREREQUISITES
174 --------------------
176 When creating bundles it is possible to create a self-contained bundle
177 that can be unbundled in a repository with no common history, as well
178 as providing negative revisions to exclude objects needed in the
179 earlier parts of the history.
181 Feeding a revision such as `new` to `git bundle create` will create a
182 bundle file that contains all the objects reachable from the revision
183 `new`. That bundle can be unbundled in any repository to obtain a full
184 history that leads to the revision `new`:
186 ----------------
187 $ git bundle create full.bundle new
188 ----------------
190 A revision range such as `old..new` will produce a bundle file that
191 will require the revision `old` (and any objects reachable from it)
192 to exist for the bundle to be "unbundle"-able:
194 ----------------
195 $ git bundle create full.bundle old..new
196 ----------------
198 A self-contained bundle without any prerequisites can be extracted
199 into anywhere, even into an empty repository, or be cloned from
200 (i.e., `new`, but not `old..new`).
202 It is okay to err on the side of caution, causing the bundle file
203 to contain objects already in the destination, as these are ignored
204 when unpacking at the destination.
206 If you want to match `git clone --mirror`, which would include your
207 refs such as `refs/remotes/*`, use `--all`.
208 If you want to provide the same set of refs that a clone directly
209 from the source repository would get, use `--branches --tags` for
210 the `<git-rev-list-args>`.
212 The 'git bundle verify' command can be used to check whether your
213 recipient repository has the required prerequisite commits for a
214 bundle.
216 EXAMPLES
217 --------
219 Assume you want to transfer the history from a repository R1 on machine A
220 to another repository R2 on machine B.
221 For whatever reason, direct connection between A and B is not allowed,
222 but we can move data from A to B via some mechanism (CD, email, etc.).
223 We want to update R2 with development made on the branch master in R1.
225 To bootstrap the process, you can first create a bundle that does not have
226 any prerequisites. You can use a tag to remember up to what commit you last
227 processed, in order to make it easy to later update the other repository
228 with an incremental bundle:
230 ----------------
231 machineA$ cd R1
232 machineA$ git bundle create file.bundle master
233 machineA$ git tag -f lastR2bundle master
234 ----------------
236 Then you transfer file.bundle to the target machine B. Because this
237 bundle does not require any existing object to be extracted, you can
238 create a new repository on machine B by cloning from it:
240 ----------------
241 machineB$ git clone -b master /home/me/tmp/file.bundle R2
242 ----------------
244 This will define a remote called "origin" in the resulting repository that
245 lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will
246 have an entry like this:
248 ------------------------
249 [remote "origin"]
250     url = /home/me/tmp/file.bundle
251     fetch = refs/heads/*:refs/remotes/origin/*
252 ------------------------
254 To update the resulting mine.git repository, you can fetch or pull after
255 replacing the bundle stored at /home/me/tmp/file.bundle with incremental
256 updates.
258 After working some more in the original repository, you can create an
259 incremental bundle to update the other repository:
261 ----------------
262 machineA$ cd R1
263 machineA$ git bundle create file.bundle lastR2bundle..master
264 machineA$ git tag -f lastR2bundle master
265 ----------------
267 You then transfer the bundle to the other machine to replace
268 /home/me/tmp/file.bundle, and pull from it.
270 ----------------
271 machineB$ cd R2
272 machineB$ git pull
273 ----------------
275 If you know up to what commit the intended recipient repository should
276 have the necessary objects, you can use that knowledge to specify the
277 prerequisites, giving a cut-off point to limit the revisions and objects that go
278 in the resulting bundle. The previous example used the lastR2bundle tag
279 for this purpose, but you can use any other options that you would give to
280 the linkgit:git-log[1] command. Here are more examples:
282 You can use a tag that is present in both:
284 ----------------
285 $ git bundle create mybundle v1.0.0..master
286 ----------------
288 You can use a prerequisite based on time:
290 ----------------
291 $ git bundle create mybundle --since=10.days master
292 ----------------
294 You can use the number of commits:
296 ----------------
297 $ git bundle create mybundle -10 master
298 ----------------
300 You can run `git-bundle verify` to see if you can extract from a bundle
301 that was created with a prerequisite:
303 ----------------
304 $ git bundle verify mybundle
305 ----------------
307 This will list what commits you must have in order to extract from the
308 bundle and will error out if you do not have them.
310 A bundle from a recipient repository's point of view is just like a
311 regular repository which it fetches or pulls from. You can, for example, map
312 references when fetching:
314 ----------------
315 $ git fetch mybundle master:localRef
316 ----------------
318 You can also see what references it offers:
320 ----------------
321 $ git ls-remote mybundle
322 ----------------
324 FILE FORMAT
325 -----------
327 See linkgit:gitformat-bundle[5].
331 Part of the linkgit:git[1] suite