]>
Commit | Line | Data |
---|---|---|
844739ba ÆAB |
1 | gitformat-bundle(5) |
2 | =================== | |
7378ec90 | 3 | |
844739ba ÆAB |
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. | |
7378ec90 | 21 | |
844739ba ÆAB |
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 | ------ | |
7378ec90 MS |
28 | |
29 | We will use ABNF notation to define the Git bundle format. See | |
5db92105 | 30 | linkgit:gitprotocol-common[5] for the details. |
7378ec90 | 31 | |
c5aecfc8 | 32 | A v2 bundle looks like this: |
33 | ||
7378ec90 MS |
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 | ||
c5aecfc8 | 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 | ||
844739ba ÆAB |
61 | |
62 | SEMANTICS | |
63 | --------- | |
7378ec90 | 64 | |
c5aecfc8 | 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. | |
7378ec90 | 69 | |
ce14cc0b | 70 | * "Prerequisites" list the objects that are NOT included in the bundle and the |
7378ec90 MS |
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 | ||
cf6cac20 EN |
89 | Note on shallow clones and Git bundles |
90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7378ec90 | 91 | |
cf6cac20 | 92 | Note that the prerequisites do not represent a shallow-clone boundary. The |
7378ec90 MS |
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. | |
c5aecfc8 | 95 | |
844739ba ÆAB |
96 | CAPABILITIES |
97 | ------------ | |
c5aecfc8 | 98 | |
99 | Because there is no opportunity for negotiation, unknown capabilities cause 'git | |
105c6f14 DS |
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. | |
844739ba ÆAB |
108 | |
109 | GIT | |
110 | --- | |
111 | Part of the linkgit:git[1] suite |