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]
  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. If 'file' is `-`, the bundle is written to stdout.
  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. If 'file' is `-`, the
  81         bundle is read from stdin.
  82
  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.
  87
  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.
  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 --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.
 125
 126 -q::
 127 --quiet::
 128         This flag makes the command not to report its progress
 129         on the standard error stream.
 130
 131 SPECIFYING REFERENCES
 132 ---------------------
 133
 134 Revisions must be accompanied by reference names to be packaged in a
 135 bundle.
 136
 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.
 140
 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`).
 145
 146 All of these simple cases are OK (assuming we have a "master" and
 147 "next" branch):
 148
 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 ----------------
 155
 156 And so are these (and the same but omitted `--stdin` examples):
 157
 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 ----------------
 162
 163 A revision name or a range whose right-hand-side cannot be resolved to
 164 a reference is not accepted:
 165
 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 ----------------
 172
 173 OBJECT PREREQUISITES
 174 --------------------
 175
 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.
 180
 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`:
 185
 186 ----------------
 187 $ git bundle create full.bundle new
 188 ----------------
 189
 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:
 193
 194 ----------------
 195 $ git bundle create full.bundle old..new
 196 ----------------
 197
 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`).
 201
 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.
 205
 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>`.
 211
 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.
 215
 216 EXAMPLES
 217 --------
 218
 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.
 224
 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:
 229
 230 ----------------
 231 machineA$ cd R1
 232 machineA$ git bundle create file.bundle master
 233 machineA$ git tag -f lastR2bundle master
 234 ----------------
 235
 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:
 239
 240 ----------------
 241 machineB$ git clone -b master /home/me/tmp/file.bundle R2
 242 ----------------
 243
 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:
 247
 248 ------------------------
 249 [remote "origin"]
 250     url = /home/me/tmp/file.bundle
 251     fetch = refs/heads/*:refs/remotes/origin/*
 252 ------------------------
 253
 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.
 257
 258 After working some more in the original repository, you can create an
 259 incremental bundle to update the other repository:
 260
 261 ----------------
 262 machineA$ cd R1
 263 machineA$ git bundle create file.bundle lastR2bundle..master
 264 machineA$ git tag -f lastR2bundle master
 265 ----------------
 266
 267 You then transfer the bundle to the other machine to replace
 268 /home/me/tmp/file.bundle, and pull from it.
 269
 270 ----------------
 271 machineB$ cd R2
 272 machineB$ git pull
 273 ----------------
 274
 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:
 281
 282 You can use a tag that is present in both:
 283
 284 ----------------
 285 $ git bundle create mybundle v1.0.0..master
 286 ----------------
 287
 288 You can use a prerequisite based on time:
 289
 290 ----------------
 291 $ git bundle create mybundle --since=10.days master
 292 ----------------
 293
 294 You can use the number of commits:
 295
 296 ----------------
 297 $ git bundle create mybundle -10 master
 298 ----------------
 299
 300 You can run `git-bundle verify` to see if you can extract from a bundle
 301 that was created with a prerequisite:
 302
 303 ----------------
 304 $ git bundle verify mybundle
 305 ----------------
 306
 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.
 309
 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:
 313
 314 ----------------
 315 $ git fetch mybundle master:localRef
 316 ----------------
 317
 318 You can also see what references it offers:
 319
 320 ----------------
 321 $ git ls-remote mybundle
 322 ----------------
 323
 324 FILE FORMAT
 325 -----------
 326
 327 See linkgit:gitformat-bundle[5].
 328
 329 GIT
 330 ---
 331 Part of the linkgit:git[1] suite