doc: describe Git bundle format
The bundle format was not documented. Describe the format with ABNF and explain the meaning of each part. Signed-off-by: Masaya Suzuki <masayasuzuki@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Masaya Suzuki committed
Feb 7, 2020 at 12:42 UTC
7378ec90e1c59610dfcac8a4bce7a9d29681380d
1 file changed
+48
Documentation/technical/bundle-format.txt
new
+48
@@ -0,0 +1,48 @@
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
+
10
+----
11
+bundle = signature *prerequisite *reference LF pack
12
+signature = "# v2 git bundle" LF
13
+
14
+prerequisite = "-" obj-id SP comment LF
15
+comment = *CHAR
16
+reference = obj-id SP refname LF
17
+
18
+pack = ... ; packfile
19
+----
20
+
21
+== Semantics
22
+
23
+A Git bundle consists of three parts.
24
+
25
+* "Prerequisites" lists the objects that are NOT included in the bundle and the
26
+ reader of the bundle MUST already have, in order to use the data in the
27
+ bundle. The objects stored in the bundle may refer to prerequisite objects and
28
+ anything reachable from them (e.g. a tree object in the bundle can reference
29
+ a blob that is reachable from a prerequisite) and/or expressed as a delta
30
+ against prerequisite objects.
31
+
32
+* "References" record the tips of the history graph, iow, what the reader of the
33
+ bundle CAN "git fetch" from it.
34
+
35
+* "Pack" is the pack data stream "git fetch" would send, if you fetch from a
36
+ repository that has the references recorded in the "References" above into a
37
+ repository that has references pointing at the objects listed in
38
+ "Prerequisites" above.
39
+
40
+In the bundle format, there can be a comment following a prerequisite obj-id.
41
+This is a comment and it has no specific meaning. The writer of the bundle MAY
42
+put any string here. The reader of the bundle MUST ignore the comment.
43
+
44
+=== Note on the shallow clone and a Git bundle
45
+
46
+Note that the prerequisites does not represent a shallow-clone boundary. The
47
+semantics of the prerequisites and the shallow-clone boundaries are different,
48
+and the Git bundle v2 format cannot represent a shallow clone repository.