Documentation/git-bundle.txt

   1 git-bundle(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-bundle - Move objects and refs by archive
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]
  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
  18 DESCRIPTION
  19 -----------
  20
  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
  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.
  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
  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.
  58
  59 See linkgit:gitformat-bundle[5] for more details and the discussion of
  60 "thin pack" in linkgit:gitformat-pack[5] for further details.
  61
  62 OPTIONS
  63 -------
  64
  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.
  70
  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.
  81
  82 list-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.
  86
  87 unbundle <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
  94 <git-rev-list-args>::
  95         A list of arguments, acceptable to 'git rev-parse' and
  96         'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES
  97         below), that specifies the specific objects and references
  98         to transport.  For example, `master~10..master` causes the
  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.
 103
 104
 105 [<refname>...]::
 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').
 111
 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
 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
 140 -q::
 141 --quiet::
 142         This flag makes the command not to report its progress
 143         on the standard error stream.
 144
 145 SPECIFYING REFERENCES
 146 ---------------------
 147
 148 Revisions must be accompanied by reference names to be packaged in a
 149 bundle.
 150
 151 More than one reference may be packaged, and more than one set of prerequisite objects can
 152 be specified.  The objects packaged are those not contained in the
 153 union of the prerequisites.
 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
 157 prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
 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 ----------------
 186
 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
 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
 218 when unpacking at the destination.
 219
 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
 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
 230 EXAMPLES
 231 --------
 232
 233 Assume you want to transfer the history from a repository R1 on machine A
 234 to another repository R2 on machine B.
 235 For whatever reason, direct connection between A and B is not allowed,
 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.
 238
 239 To bootstrap the process, you can first create a bundle that does not have
 240 any prerequisites. You can use a tag to remember up to what commit you last
 241 processed, in order to make it easy to later update the other repository
 242 with an incremental bundle:
 243
 244 ----------------
 245 machineA$ cd R1
 246 machineA$ git bundle create file.bundle master
 247 machineA$ git tag -f lastR2bundle master
 248 ----------------
 249
 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:
 253
 254 ----------------
 255 machineB$ git clone -b master /home/me/tmp/file.bundle R2
 256 ----------------
 257
 258 This will define a remote called "origin" in the resulting repository that
 259 lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will
 260 have an entry like this:
 261
 262 ------------------------
 263 [remote "origin"]
 264     url = /home/me/tmp/file.bundle
 265     fetch = refs/heads/*:refs/remotes/origin/*
 266 ------------------------
 267
 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.
 271
 272 After working some more in the original repository, you can create an
 273 incremental bundle to update the other repository:
 274
 275 ----------------
 276 machineA$ cd R1
 277 machineA$ git bundle create file.bundle lastR2bundle..master
 278 machineA$ git tag -f lastR2bundle master
 279 ----------------
 280
 281 You then transfer the bundle to the other machine to replace
 282 /home/me/tmp/file.bundle, and pull from it.
 283
 284 ----------------
 285 machineB$ cd R2
 286 machineB$ git pull
 287 ----------------
 288
 289 If you know up to what commit the intended recipient repository should
 290 have the necessary objects, you can use that knowledge to specify the
 291 prerequisites, giving a cut-off point to limit the revisions and objects that go
 292 in the resulting bundle. The previous example used the lastR2bundle tag
 293 for this purpose, but you can use any other options that you would give to
 294 the linkgit:git-log[1] command. Here are more examples:
 295
 296 You can use a tag that is present in both:
 297
 298 ----------------
 299 $ git bundle create mybundle v1.0.0..master
 300 ----------------
 301
 302 You can use a prerequisite based on time:
 303
 304 ----------------
 305 $ git bundle create mybundle --since=10.days master
 306 ----------------
 307
 308 You can use the number of commits:
 309
 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
 315 that was created with a prerequisite:
 316
 317 ----------------
 318 $ git bundle verify mybundle
 319 ----------------
 320
 321 This will list what commits you must have in order to extract from the
 322 bundle and will error out if you do not have them.
 323
 324 A bundle from a recipient repository's point of view is just like a
 325 regular repository which it fetches or pulls from. You can, for example, map
 326 references when fetching:
 327
 328 ----------------
 329 $ git fetch mybundle master:localRef
 330 ----------------
 331
 332 You can also see what references it offers:
 333
 334 ----------------
 335 $ git ls-remote mybundle
 336 ----------------
 337
 338 FILE FORMAT
 339 -----------
 340
 341 See linkgit:gitformat-bundle[5].
 342
 343 GIT
 344 ---
 345 Part of the linkgit:git[1] suite