1GITFORMAT-BUNDLE(5)               Git Manual               GITFORMAT-BUNDLE(5)
2
3
4

NAME

6       gitformat-bundle - The bundle file format
7

SYNOPSIS

9       *.bundle
10       *.bdl
11

DESCRIPTION

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

FORMAT

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

SEMANTICS

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" list 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 shallow clones and Git bundles
77       Note that the prerequisites do not represent a shallow-clone boundary.
78       The semantics of the prerequisites and the shallow-clone boundaries are
79       different, and the Git bundle v2 format cannot represent a shallow
80       clone repository.
81

CAPABILITIES

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

GIT

94       Part of the git(1) suite
95
96
97
98Git 2.43.0                        11/20/2023               GITFORMAT-BUNDLE(5)
Impressum