]>
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. |