| gitformat-bundle(5) |
| =================== |
| |
| NAME |
| ---- |
| gitformat-bundle - The bundle file format |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| *.bundle |
| *.bdl |
| |
| DESCRIPTION |
| ----------- |
| |
| The Git bundle format is a format that represents both refs and Git |
| objects. A bundle is a header in a format similar to |
| linkgit:git-show-ref[1] followed by a pack in *.pack format. |
| |
| The format is created and read by the linkgit:git-bundle[1] command, |
| and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1]. |
| |
| |
| FORMAT |
| ------ |
| |
| We will use ABNF notation to define the Git bundle format. See |
| linkgit:gitprotocol-common[5] for the details. |
| |
| A v2 bundle looks like this: |
| |
| ---- |
| bundle = signature *prerequisite *reference LF pack |
| signature = "# v2 git bundle" LF |
| |
| prerequisite = "-" obj-id SP comment LF |
| comment = *CHAR |
| reference = obj-id SP refname LF |
| |
| pack = ... ; packfile |
| ---- |
| |
| A v3 bundle looks like this: |
| |
| ---- |
| bundle = signature *capability *prerequisite *reference LF pack |
| signature = "# v3 git bundle" LF |
| |
| capability = "@" key ["=" value] LF |
| prerequisite = "-" obj-id SP comment LF |
| comment = *CHAR |
| reference = obj-id SP refname LF |
| key = 1*(ALPHA / DIGIT / "-") |
| value = *(%01-09 / %0b-FF) |
| |
| pack = ... ; packfile |
| ---- |
| |
| |
| SEMANTICS |
| --------- |
| |
| A Git bundle consists of several parts. |
| |
| * "Capabilities", which are only in the v3 format, indicate functionality that |
| the bundle requires to be read properly. |
| |
| * "Prerequisites" list the objects that are NOT included in the bundle and the |
| reader of the bundle MUST already have, in order to use the data in the |
| bundle. The objects stored in the bundle may refer to prerequisite objects and |
| anything reachable from them (e.g. a tree object in the bundle can reference |
| a blob that is reachable from a prerequisite) and/or expressed as a delta |
| against prerequisite objects. |
| |
| * "References" record the tips of the history graph, iow, what the reader of the |
| bundle CAN "git fetch" from it. |
| |
| * "Pack" is the pack data stream "git fetch" would send, if you fetch from a |
| repository that has the references recorded in the "References" above into a |
| repository that has references pointing at the objects listed in |
| "Prerequisites" above. |
| |
| In the bundle format, there can be a comment following a prerequisite obj-id. |
| This is a comment and it has no specific meaning. The writer of the bundle MAY |
| put any string here. The reader of the bundle MUST ignore the comment. |
| |
| Note on shallow clones and Git bundles |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Note that the prerequisites do not represent a shallow-clone boundary. The |
| semantics of the prerequisites and the shallow-clone boundaries are different, |
| and the Git bundle v2 format cannot represent a shallow clone repository. |
| |
| CAPABILITIES |
| ------------ |
| |
| Because there is no opportunity for negotiation, unknown capabilities cause 'git |
| bundle' to abort. |
| |
| * `object-format` specifies the hash algorithm in use, and can take the same |
| values as the `extensions.objectFormat` configuration value. |
| |
| * `filter` specifies an object filter as in the `--filter` option in |
| linkgit:git-rev-list[1]. The resulting pack-file must be marked as a |
| `.promisor` pack-file after it is unbundled. |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |
