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