| 1 | gitformat-bundle(5) |
| 2 | =================== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitformat-bundle - The bundle file format |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | *.bundle |
| 13 | *.bdl |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | |
| 18 | The Git bundle format is a format that represents both refs and Git |
| 19 | objects. A bundle is a header in a format similar to |
| 20 | linkgit:git-show-ref[1] followed by a pack in *.pack format. |
| 21 | |
| 22 | The format is created and read by the linkgit:git-bundle[1] command, |
| 23 | and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1]. |
| 24 | |
| 25 | |
| 26 | FORMAT |
| 27 | ------ |
| 28 | |
| 29 | We will use ABNF notation to define the Git bundle format. See |
| 30 | linkgit:gitprotocol-common[5] for the details. |
| 31 | |
| 32 | A v2 bundle looks like this: |
| 33 | |
| 34 | ---- |
| 35 | bundle = signature *prerequisite *reference LF pack |
| 36 | signature = "# v2 git bundle" LF |
| 37 | |
| 38 | prerequisite = "-" obj-id SP comment LF |
| 39 | comment = *CHAR |
| 40 | reference = obj-id SP refname LF |
| 41 | |
| 42 | pack = ... ; packfile |
| 43 | ---- |
| 44 | |
| 45 | A v3 bundle looks like this: |
| 46 | |
| 47 | ---- |
| 48 | bundle = signature *capability *prerequisite *reference LF pack |
| 49 | signature = "# v3 git bundle" LF |
| 50 | |
| 51 | capability = "@" key ["=" value] LF |
| 52 | prerequisite = "-" obj-id SP comment LF |
| 53 | comment = *CHAR |
| 54 | reference = obj-id SP refname LF |
| 55 | key = 1*(ALPHA / DIGIT / "-") |
| 56 | value = *(%01-09 / %0b-FF) |
| 57 | |
| 58 | pack = ... ; packfile |
| 59 | ---- |
| 60 | |
| 61 | |
| 62 | SEMANTICS |
| 63 | --------- |
| 64 | |
| 65 | A Git bundle consists of several parts. |
| 66 | |
| 67 | * "Capabilities", which are only in the v3 format, indicate functionality that |
| 68 | the bundle requires to be read properly. |
| 69 | |
| 70 | * "Prerequisites" list the objects that are NOT included in the bundle and the |
| 71 | reader of the bundle MUST already have, in order to use the data in the |
| 72 | bundle. The objects stored in the bundle may refer to prerequisite objects and |
| 73 | anything reachable from them (e.g. a tree object in the bundle can reference |
| 74 | a blob that is reachable from a prerequisite) and/or expressed as a delta |
| 75 | against prerequisite objects. |
| 76 | |
| 77 | * "References" record the tips of the history graph, iow, what the reader of the |
| 78 | bundle CAN "git fetch" from it. |
| 79 | |
| 80 | * "Pack" is the pack data stream "git fetch" would send, if you fetch from a |
| 81 | repository that has the references recorded in the "References" above into a |
| 82 | repository that has references pointing at the objects listed in |
| 83 | "Prerequisites" above. |
| 84 | |
| 85 | In the bundle format, there can be a comment following a prerequisite obj-id. |
| 86 | This is a comment and it has no specific meaning. The writer of the bundle MAY |
| 87 | put any string here. The reader of the bundle MUST ignore the comment. |
| 88 | |
| 89 | Note on shallow clones and Git bundles |
| 90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 91 | |
| 92 | Note that the prerequisites do not represent a shallow-clone boundary. The |
| 93 | semantics of the prerequisites and the shallow-clone boundaries are different, |
| 94 | and the Git bundle v2 format cannot represent a shallow clone repository. |
| 95 | |
| 96 | CAPABILITIES |
| 97 | ------------ |
| 98 | |
| 99 | Because there is no opportunity for negotiation, unknown capabilities cause 'git |
| 100 | bundle' to abort. |
| 101 | |
| 102 | * `object-format` specifies the hash algorithm in use, and can take the same |
| 103 | values as the `extensions.objectFormat` configuration value. |
| 104 | |
| 105 | * `filter` specifies an object filter as in the `--filter` option in |
| 106 | linkgit:git-rev-list[1]. The resulting pack-file must be marked as a |
| 107 | `.promisor` pack-file after it is unbundled. |
| 108 | |
| 109 | GIT |
| 110 | --- |
| 111 | Part of the linkgit:git[1] suite |