| 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 (see the "full backup" example in "EXAMPLES"), and to relay |
| 27 | the state of the references in one repository to another (see the second |
| 28 | example). |
| 29 | |
| 30 | Git commands that fetch or otherwise "read" via protocols such as |
| 31 | `ssh://` and `https://` can also operate on bundle files. It is |
| 32 | possible linkgit:git-clone[1] a new repository from a bundle, to use |
| 33 | linkgit:git-fetch[1] to fetch from one, and to list the references |
| 34 | contained within it with linkgit:git-ls-remote[1]. There's no |
| 35 | corresponding "write" support, i.e. a 'git push' into a bundle is not |
| 36 | supported. |
| 37 | |
| 38 | BUNDLE FORMAT |
| 39 | ------------- |
| 40 | |
| 41 | Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a |
| 42 | header indicating what references are contained within the bundle. |
| 43 | |
| 44 | Like the packed archive format itself bundles can either be |
| 45 | self-contained, or be created using exclusions. |
| 46 | See the "OBJECT PREREQUISITES" section below. |
| 47 | |
| 48 | Bundles created using revision exclusions are "thin packs" created |
| 49 | using the `--thin` option to linkgit:git-pack-objects[1], and |
| 50 | unbundled using the `--fix-thin` option to linkgit:git-index-pack[1]. |
| 51 | |
| 52 | There is no option to create a "thick pack" when using revision |
| 53 | exclusions, and users should not be concerned about the difference. By |
| 54 | using "thin packs", bundles created using exclusions are smaller in |
| 55 | size. That they're "thin" under the hood is merely noted here as a |
| 56 | curiosity, and as a reference to other documentation. |
| 57 | |
| 58 | See linkgit:gitformat-bundle[5] for more details and the discussion of |
| 59 | "thin pack" in linkgit:gitformat-pack[5] for further details. |
| 60 | |
| 61 | OPTIONS |
| 62 | ------- |
| 63 | |
| 64 | create [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 | |
| 70 | verify <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 | |
| 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. If 'file' is `-`, the bundle is read from stdin. |
| 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 | 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 | |
| 130 | SPECIFYING REFERENCES |
| 131 | --------------------- |
| 132 | |
| 133 | Revisions must be accompanied by reference names to be packaged in a |
| 134 | bundle. Alternatively `--all` can be used to package all refs. |
| 135 | |
| 136 | More than one reference may be packaged, and more than one set of prerequisite objects can |
| 137 | be specified. The objects packaged are those not contained in the |
| 138 | union of the prerequisites. |
| 139 | |
| 140 | The 'git bundle create' command resolves the reference names for you |
| 141 | using the same rules as `git rev-parse --abbrev-ref=loose`. Each |
| 142 | prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly |
| 143 | (e.g. `master~10..master`, `--since=10.days.ago master`). |
| 144 | |
| 145 | All 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 | |
| 155 | And 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 | |
| 162 | A revision name or a range whose right-hand-side cannot be resolved to |
| 163 | a reference is not accepted: |
| 164 | |
| 165 | ---------------- |
| 166 | $ git bundle create HEAD.bundle $(git rev-parse HEAD) |
| 167 | fatal: Refusing to create empty bundle. |
| 168 | $ git bundle create master-yesterday.bundle master~10..master~5 |
| 169 | fatal: Refusing to create empty bundle. |
| 170 | ---------------- |
| 171 | |
| 172 | OBJECT PREREQUISITES |
| 173 | -------------------- |
| 174 | |
| 175 | When creating bundles it is possible to create a self-contained bundle |
| 176 | that can be unbundled in a repository with no common history, as well |
| 177 | as providing negative revisions to exclude objects needed in the |
| 178 | earlier parts of the history. |
| 179 | |
| 180 | Feeding a revision such as `new` to `git bundle create` will create a |
| 181 | bundle file that contains all the objects reachable from the revision |
| 182 | `new`. That bundle can be unbundled in any repository to obtain a full |
| 183 | history that leads to the revision `new`: |
| 184 | |
| 185 | ---------------- |
| 186 | $ git bundle create full.bundle new |
| 187 | ---------------- |
| 188 | |
| 189 | A revision range such as `old..new` will produce a bundle file that |
| 190 | will require the revision `old` (and any objects reachable from it) |
| 191 | to exist for the bundle to be "unbundle"-able: |
| 192 | |
| 193 | ---------------- |
| 194 | $ git bundle create full.bundle old..new |
| 195 | ---------------- |
| 196 | |
| 197 | A self-contained bundle without any prerequisites can be extracted |
| 198 | into anywhere, even into an empty repository, or be cloned from |
| 199 | (i.e., `new`, but not `old..new`). |
| 200 | |
| 201 | It is okay to err on the side of caution, causing the bundle file |
| 202 | to contain objects already in the destination, as these are ignored |
| 203 | when unpacking at the destination. |
| 204 | |
| 205 | If you want to provide the same set of refs that a clone directly |
| 206 | from the source repository would get, use `--branches --tags` for |
| 207 | the `<git-rev-list-args>`. |
| 208 | |
| 209 | The 'git bundle verify' command can be used to check whether your |
| 210 | recipient repository has the required prerequisite commits for a |
| 211 | bundle. |
| 212 | |
| 213 | EXAMPLES |
| 214 | -------- |
| 215 | |
| 216 | We'll discuss two cases: |
| 217 | |
| 218 | 1. Taking a full backup of a repository |
| 219 | 2. Transferring the history of a repository to another machine when the |
| 220 | two machines have no direct connection |
| 221 | |
| 222 | First let's consider a full backup of the repository. The following |
| 223 | command will take a full backup of the repository in the sense that all |
| 224 | refs are included in the bundle: |
| 225 | |
| 226 | ---------------- |
| 227 | $ git bundle create backup.bundle --all |
| 228 | ---------------- |
| 229 | |
| 230 | But note again that this is only for the refs, i.e. you will only |
| 231 | include refs and commits reachable from those refs. You will not |
| 232 | include other local state, such as the contents of the index, working |
| 233 | tree, the stash, per-repository configuration, hooks, etc. |
| 234 | |
| 235 | You can later recover that repository by using for example |
| 236 | linkgit:git-clone[1]: |
| 237 | |
| 238 | ---------------- |
| 239 | $ git clone backup.bundle <new directory> |
| 240 | ---------------- |
| 241 | |
| 242 | For the next example, assume you want to transfer the history from a |
| 243 | repository R1 on machine A to another repository R2 on machine B. |
| 244 | For whatever reason, direct connection between A and B is not allowed, |
| 245 | but we can move data from A to B via some mechanism (CD, email, etc.). |
| 246 | We want to update R2 with development made on the branch master in R1. |
| 247 | |
| 248 | To bootstrap the process, you can first create a bundle that does not have |
| 249 | any prerequisites. You can use a tag to remember up to what commit you last |
| 250 | processed, in order to make it easy to later update the other repository |
| 251 | with an incremental bundle: |
| 252 | |
| 253 | ---------------- |
| 254 | machineA$ cd R1 |
| 255 | machineA$ git bundle create file.bundle master |
| 256 | machineA$ git tag -f lastR2bundle master |
| 257 | ---------------- |
| 258 | |
| 259 | Then you transfer file.bundle to the target machine B. Because this |
| 260 | bundle does not require any existing object to be extracted, you can |
| 261 | create a new repository on machine B by cloning from it: |
| 262 | |
| 263 | ---------------- |
| 264 | machineB$ git clone -b master /home/me/tmp/file.bundle R2 |
| 265 | ---------------- |
| 266 | |
| 267 | This will define a remote called "origin" in the resulting repository that |
| 268 | lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will |
| 269 | have 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 | |
| 277 | To update the resulting mine.git repository, you can fetch or pull after |
| 278 | replacing the bundle stored at /home/me/tmp/file.bundle with incremental |
| 279 | updates. |
| 280 | |
| 281 | After working some more in the original repository, you can create an |
| 282 | incremental bundle to update the other repository: |
| 283 | |
| 284 | ---------------- |
| 285 | machineA$ cd R1 |
| 286 | machineA$ git bundle create file.bundle lastR2bundle..master |
| 287 | machineA$ git tag -f lastR2bundle master |
| 288 | ---------------- |
| 289 | |
| 290 | You then transfer the bundle to the other machine to replace |
| 291 | /home/me/tmp/file.bundle, and pull from it. |
| 292 | |
| 293 | ---------------- |
| 294 | machineB$ cd R2 |
| 295 | machineB$ git pull |
| 296 | ---------------- |
| 297 | |
| 298 | If you know up to what commit the intended recipient repository should |
| 299 | have the necessary objects, you can use that knowledge to specify the |
| 300 | prerequisites, giving a cut-off point to limit the revisions and objects that go |
| 301 | in the resulting bundle. The previous example used the lastR2bundle tag |
| 302 | for this purpose, but you can use any other options that you would give to |
| 303 | the linkgit:git-log[1] command. Here are more examples: |
| 304 | |
| 305 | You can use a tag that is present in both: |
| 306 | |
| 307 | ---------------- |
| 308 | $ git bundle create mybundle v1.0.0..master |
| 309 | ---------------- |
| 310 | |
| 311 | You can use a prerequisite based on time: |
| 312 | |
| 313 | ---------------- |
| 314 | $ git bundle create mybundle --since=10.days master |
| 315 | ---------------- |
| 316 | |
| 317 | You can use the number of commits: |
| 318 | |
| 319 | ---------------- |
| 320 | $ git bundle create mybundle -10 master |
| 321 | ---------------- |
| 322 | |
| 323 | You can run `git-bundle verify` to see if you can extract from a bundle |
| 324 | that was created with a prerequisite: |
| 325 | |
| 326 | ---------------- |
| 327 | $ git bundle verify mybundle |
| 328 | ---------------- |
| 329 | |
| 330 | This will list what commits you must have in order to extract from the |
| 331 | bundle and will error out if you do not have them. |
| 332 | |
| 333 | A bundle from a recipient repository's point of view is just like a |
| 334 | regular repository which it fetches or pulls from. You can, for example, map |
| 335 | references when fetching: |
| 336 | |
| 337 | ---------------- |
| 338 | $ git fetch mybundle master:localRef |
| 339 | ---------------- |
| 340 | |
| 341 | You can also see what references it offers: |
| 342 | |
| 343 | ---------------- |
| 344 | $ git ls-remote mybundle |
| 345 | ---------------- |
| 346 | |
| 347 | DISCUSSION |
| 348 | ---------- |
| 349 | |
| 350 | A naive way to make a full backup of a repository is to use something to |
| 351 | the effect of `cp -r <repo> <destination>`. This is discouraged since |
| 352 | the repository could be written to during the copy operation. In turn |
| 353 | some files at `<destination>` could be corrupted. |
| 354 | |
| 355 | This is why it is recommended to use Git tooling for making repository |
| 356 | backups, either with this command or with e.g. linkgit:git-clone[1]. |
| 357 | But keep in mind that these tools will not help you backup state other |
| 358 | than refs and commits. In other words they will not help you backup |
| 359 | contents of the index, working tree, the stash, per-repository |
| 360 | configuration, hooks, etc. |
| 361 | |
| 362 | See also linkgit:gitfaq[7], section "TRANSFERS" for a discussion of the |
| 363 | problems associated with file syncing across systems. |
| 364 | |
| 365 | FILE FORMAT |
| 366 | ----------- |
| 367 | |
| 368 | See linkgit:gitformat-bundle[5]. |
| 369 | |
| 370 | GIT |
| 371 | --- |
| 372 | Part of the linkgit:git[1] suite |