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 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 link:technical/bundle-format.html[the `bundle-format`
  60 documentation] for more details and the discussion of "thin pack" in
  61 link:technical/pack-format.html[the pack format documentation] for
  62 further details.
  63
  64 OPTIONS
  65 -------
  66
  67 create [options] <file> <git-rev-list-args>::
  68         Used to create a bundle named 'file'.  This requires the
  69         '<git-rev-list-args>' arguments to define the bundle contents.
  70         'options' contains the options specific to the 'git bundle create'
  71         subcommand.
  72
  73 verify <file>::
  74         Used to check that a bundle file is valid and will apply
  75         cleanly to the current repository.  This includes checks on the
  76         bundle format itself as well as checking that the prerequisite
  77         commits exist and are fully linked in the current repository.
  78         Then, 'git bundle' prints a list of missing commits, if any.
  79         Finally, information about additional capabilities, such as "object
  80         filter", is printed. See "Capabilities" in link:technical/bundle-format.html
  81         for more information. The exit code is zero for success, but will
  82         be nonzero if the bundle file is invalid.
  83
  84 list-heads <file>::
  85         Lists the references defined in the bundle.  If followed by a
  86         list of references, only references matching those given are
  87         printed out.
  88
  89 unbundle <file>::
  90         Passes the objects in the bundle to 'git index-pack'
  91         for storage in the repository, then prints the names of all
  92         defined references. If a list of references is given, only
  93         references matching those in the list are printed. This command is
  94         really plumbing, intended to be called only by 'git fetch'.
  95
  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.
 105
 106
 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').
 113
 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.
 119
 120 --all-progress::
 121         When --stdout is specified then progress report is
 122         displayed during the object count and compression phases
 123         but inhibited during the write-out phase. The reason is
 124         that in some cases the output stream is directly linked
 125         to another command which may wish to display progress
 126         status of its own as it processes incoming pack data.
 127         This flag is like --progress except that it forces progress
 128         report for the write-out phase as well even if --stdout is
 129         used.
 130
 131 --all-progress-implied::
 132         This is used to imply --all-progress whenever progress display
 133         is activated.  Unlike --all-progress this flag doesn't actually
 134         force any progress display by itself.
 135
 136 --version=<version>::
 137         Specify the bundle version.  Version 2 is the older format and can only be
 138         used with SHA-1 repositories; the newer version 3 contains capabilities that
 139         permit extensions. The default is the oldest supported format, based on the
 140         hash algorithm in use.
 141
 142 -q::
 143 --quiet::
 144         This flag makes the command not to report its progress
 145         on the standard error stream.
 146
 147 SPECIFYING REFERENCES
 148 ---------------------
 149
 150 Revisions must be accompanied by reference names to be packaged in a
 151 bundle.
 152
 153 More than one reference may be packaged, and more than one set of prerequisite objects can
 154 be specified.  The objects packaged are those not contained in the
 155 union of the prerequisites.
 156
 157 The 'git bundle create' command resolves the reference names for you
 158 using the same rules as `git rev-parse --abbrev-ref=loose`. Each
 159 prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
 160 (e.g. `master~10..master`, `--since=10.days.ago master`).
 161
 162 All of these simple cases are OK (assuming we have a "master" and
 163 "next" branch):
 164
 165 ----------------
 166 $ git bundle create master.bundle master
 167 $ echo master | git bundle create master.bundle --stdin
 168 $ git bundle create master-and-next.bundle master next
 169 $ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
 170 ----------------
 171
 172 And so are these (and the same but omitted `--stdin` examples):
 173
 174 ----------------
 175 $ git bundle create recent-master.bundle master~10..master
 176 $ git bundle create recent-updates.bundle master~10..master next~5..next
 177 ----------------
 178
 179 A revision name or a range whose right-hand-side cannot be resolved to
 180 a reference is not accepted:
 181
 182 ----------------
 183 $ git bundle create HEAD.bundle $(git rev-parse HEAD)
 184 fatal: Refusing to create empty bundle.
 185 $ git bundle create master-yesterday.bundle master~10..master~5
 186 fatal: Refusing to create empty bundle.
 187 ----------------
 188
 189 OBJECT PREREQUISITES
 190 --------------------
 191
 192 When creating bundles it is possible to create a self-contained bundle
 193 that can be unbundled in a repository with no common history, as well
 194 as providing negative revisions to exclude objects needed in the
 195 earlier parts of the history.
 196
 197 Feeding a revision such as `new` to `git bundle create` will create a
 198 bundle file that contains all the objects reachable from the revision
 199 `new`. That bundle can be unbundled in any repository to obtain a full
 200 history that leads to the revision `new`:
 201
 202 ----------------
 203 $ git bundle create full.bundle new
 204 ----------------
 205
 206 A revision range such as `old..new` will produce a bundle file that
 207 will require the revision `old` (and any objects reachable from it)
 208 to exist for the bundle to be "unbundle"-able:
 209
 210 ----------------
 211 $ git bundle create full.bundle old..new
 212 ----------------
 213
 214 A self-contained bundle without any prerequisites can be extracted
 215 into anywhere, even into an empty repository, or be cloned from
 216 (i.e., `new`, but not `old..new`).
 217
 218 It is okay to err on the side of caution, causing the bundle file
 219 to contain objects already in the destination, as these are ignored
 220 when unpacking at the destination.
 221
 222 If you want to match `git clone --mirror`, which would include your
 223 refs such as `refs/remotes/*`, use `--all`.
 224 If you want to provide the same set of refs that a clone directly
 225 from the source repository would get, use `--branches --tags` for
 226 the `<git-rev-list-args>`.
 227
 228 The 'git bundle verify' command can be used to check whether your
 229 recipient repository has the required prerequisite commits for a
 230 bundle.
 231
 232 EXAMPLES
 233 --------
 234
 235 Assume you want to transfer the history from a repository R1 on machine A
 236 to another repository R2 on machine B.
 237 For whatever reason, direct connection between A and B is not allowed,
 238 but we can move data from A to B via some mechanism (CD, email, etc.).
 239 We want to update R2 with development made on the branch master in R1.
 240
 241 To bootstrap the process, you can first create a bundle that does not have
 242 any prerequisites. You can use a tag to remember up to what commit you last
 243 processed, in order to make it easy to later update the other repository
 244 with an incremental bundle:
 245
 246 ----------------
 247 machineA$ cd R1
 248 machineA$ git bundle create file.bundle master
 249 machineA$ git tag -f lastR2bundle master
 250 ----------------
 251
 252 Then you transfer file.bundle to the target machine B. Because this
 253 bundle does not require any existing object to be extracted, you can
 254 create a new repository on machine B by cloning from it:
 255
 256 ----------------
 257 machineB$ git clone -b master /home/me/tmp/file.bundle R2
 258 ----------------
 259
 260 This will define a remote called "origin" in the resulting repository that
 261 lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will
 262 have an entry like this:
 263
 264 ------------------------
 265 [remote "origin"]
 266     url = /home/me/tmp/file.bundle
 267     fetch = refs/heads/*:refs/remotes/origin/*
 268 ------------------------
 269
 270 To update the resulting mine.git repository, you can fetch or pull after
 271 replacing the bundle stored at /home/me/tmp/file.bundle with incremental
 272 updates.
 273
 274 After working some more in the original repository, you can create an
 275 incremental bundle to update the other repository:
 276
 277 ----------------
 278 machineA$ cd R1
 279 machineA$ git bundle create file.bundle lastR2bundle..master
 280 machineA$ git tag -f lastR2bundle master
 281 ----------------
 282
 283 You then transfer the bundle to the other machine to replace
 284 /home/me/tmp/file.bundle, and pull from it.
 285
 286 ----------------
 287 machineB$ cd R2
 288 machineB$ git pull
 289 ----------------
 290
 291 If you know up to what commit the intended recipient repository should
 292 have the necessary objects, you can use that knowledge to specify the
 293 prerequisites, giving a cut-off point to limit the revisions and objects that go
 294 in the resulting bundle. The previous example used the lastR2bundle tag
 295 for this purpose, but you can use any other options that you would give to
 296 the linkgit:git-log[1] command. Here are more examples:
 297
 298 You can use a tag that is present in both:
 299
 300 ----------------
 301 $ git bundle create mybundle v1.0.0..master
 302 ----------------
 303
 304 You can use a prerequisite based on time:
 305
 306 ----------------
 307 $ git bundle create mybundle --since=10.days master
 308 ----------------
 309
 310 You can use the number of commits:
 311
 312 ----------------
 313 $ git bundle create mybundle -10 master
 314 ----------------
 315
 316 You can run `git-bundle verify` to see if you can extract from a bundle
 317 that was created with a prerequisite:
 318
 319 ----------------
 320 $ git bundle verify mybundle
 321 ----------------
 322
 323 This will list what commits you must have in order to extract from the
 324 bundle and will error out if you do not have them.
 325
 326 A bundle from a recipient repository's point of view is just like a
 327 regular repository which it fetches or pulls from. You can, for example, map
 328 references when fetching:
 329
 330 ----------------
 331 $ git fetch mybundle master:localRef
 332 ----------------
 333
 334 You can also see what references it offers:
 335
 336 ----------------
 337 $ git ls-remote mybundle
 338 ----------------
 339
 340 GIT
 341 ---
 342 Part of the linkgit:git[1] suite