projects / thirdparty / git.git / blame
| Commit | Line | Data |
|---|---|---|
| 7378ec90 MS |
1 | = Git bundle v2 format |
| 2 | ||
| 3 | The Git bundle format is a format that represents both refs and Git objects. | |
| 4 | ||
| 5 | == Format | |
| 6 | ||
| 7 | We will use ABNF notation to define the Git bundle format. See | |
| 8 | protocol-common.txt for the details. | |
| 9 | ||
| c5aecfc8 | 10 | A v2 bundle looks like this: |
| 11 | ||
| 7378ec90 MS |
12 | ---- |
| 13 | bundle = signature *prerequisite *reference LF pack | |
| 14 | signature = "# v2 git bundle" LF | |
| 15 | ||
| 16 | prerequisite = "-" obj-id SP comment LF | |
| 17 | comment = *CHAR | |
| 18 | reference = obj-id SP refname LF | |
| 19 | ||
| 20 | pack = ... ; packfile | |
| 21 | ---- | |
| 22 | ||
| c5aecfc8 | 23 | A v3 bundle looks like this: |
| 24 | ||
| 25 | ---- | |
| 26 | bundle = signature *capability *prerequisite *reference LF pack | |
| 27 | signature = "# v3 git bundle" LF | |
| 28 | ||
| 29 | capability = "@" key ["=" value] LF | |
| 30 | prerequisite = "-" obj-id SP comment LF | |
| 31 | comment = *CHAR | |
| 32 | reference = obj-id SP refname LF | |
| 33 | key = 1*(ALPHA / DIGIT / "-") | |
| 34 | value = *(%01-09 / %0b-FF) | |
| 35 | ||
| 36 | pack = ... ; packfile | |
| 37 | ---- | |
| 38 | ||
| 7378ec90 MS |
39 | == Semantics |
| 40 | ||
| c5aecfc8 | 41 | A Git bundle consists of several parts. |
| 42 | ||
| 43 | * "Capabilities", which are only in the v3 format, indicate functionality that | |
| 44 | the bundle requires to be read properly. | |
| 7378ec90 MS |
45 | |
| 46 | * "Prerequisites" lists the objects that are NOT included in the bundle and the | |
| 47 | reader of the bundle MUST already have, in order to use the data in the | |
| 48 | bundle. The objects stored in the bundle may refer to prerequisite objects and | |
| 49 | anything reachable from them (e.g. a tree object in the bundle can reference | |
| 50 | a blob that is reachable from a prerequisite) and/or expressed as a delta | |
| 51 | against prerequisite objects. | |
| 52 | ||
| 53 | * "References" record the tips of the history graph, iow, what the reader of the | |
| 54 | bundle CAN "git fetch" from it. | |
| 55 | ||
| 56 | * "Pack" is the pack data stream "git fetch" would send, if you fetch from a | |
| 57 | repository that has the references recorded in the "References" above into a | |
| 58 | repository that has references pointing at the objects listed in | |
| 59 | "Prerequisites" above. | |
| 60 | ||
| 61 | In the bundle format, there can be a comment following a prerequisite obj-id. | |
| 62 | This is a comment and it has no specific meaning. The writer of the bundle MAY | |
| 63 | put any string here. The reader of the bundle MUST ignore the comment. | |
| 64 | ||
| 65 | === Note on the shallow clone and a Git bundle | |
| 66 | ||
| 67 | Note that the prerequisites does not represent a shallow-clone boundary. The | |
| 68 | semantics of the prerequisites and the shallow-clone boundaries are different, | |
| 69 | and the Git bundle v2 format cannot represent a shallow clone repository. | |
| c5aecfc8 | 70 | |
| 71 | == Capabilities | |
| 72 | ||
| 73 | Because there is no opportunity for negotiation, unknown capabilities cause 'git | |
| 74 | bundle' to abort. The only known capability is `object-format`, which specifies | |
| 75 | the hash algorithm in use, and can take the same values as the | |
| 76 | `extensions.objectFormat` configuration value. |