summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2020-02-14 20:42:32 (GMT)
committerJunio C Hamano <gitster@pobox.com>2020-02-14 20:42:32 (GMT)
commit7137d6089b510c73fe74136bf50dca53ec61a747 (patch)
tree26f9b0b1bdbda81c0db4c3e725177db2fa079d0f
parent52d620fdc670fb11101d6fe31d6a158e27c6d979 (diff)
parent7378ec90e1c59610dfcac8a4bce7a9d29681380d (diff)
downloadgit-7137d6089b510c73fe74136bf50dca53ec61a747.zip
git-7137d6089b510c73fe74136bf50dca53ec61a747.tar.gz
git-7137d6089b510c73fe74136bf50dca53ec61a747.tar.bz2
Merge branch 'ms/doc-bundle-format' into maint
Technical details of the bundle format has been documented. I think this is in a good enough shape. * ms/doc-bundle-format: doc: describe Git bundle format
-rw-r--r--Documentation/technical/bundle-format.txt48
1 files changed, 48 insertions, 0 deletions
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt
new file mode 100644
index 0000000..0e82815
--- /dev/null
+++ b/Documentation/technical/bundle-format.txt
@@ -0,0 +1,48 @@
+= Git bundle v2 format
+
+The Git bundle format is a format that represents both refs and Git objects.
+
+== Format
+
+We will use ABNF notation to define the Git bundle format. See
+protocol-common.txt for the details.
+
+----
+bundle = signature *prerequisite *reference LF pack
+signature = "# v2 git bundle" LF
+
+prerequisite = "-" obj-id SP comment LF
+comment = *CHAR
+reference = obj-id SP refname LF
+
+pack = ... ; packfile
+----
+
+== Semantics
+
+A Git bundle consists of three parts.
+
+* "Prerequisites" lists the objects that are NOT included in the bundle and the
+ reader of the bundle MUST already have, in order to use the data in the
+ bundle. The objects stored in the bundle may refer to prerequisite objects and
+ anything reachable from them (e.g. a tree object in the bundle can reference
+ a blob that is reachable from a prerequisite) and/or expressed as a delta
+ against prerequisite objects.
+
+* "References" record the tips of the history graph, iow, what the reader of the
+ bundle CAN "git fetch" from it.
+
+* "Pack" is the pack data stream "git fetch" would send, if you fetch from a
+ repository that has the references recorded in the "References" above into a
+ repository that has references pointing at the objects listed in
+ "Prerequisites" above.
+
+In the bundle format, there can be a comment following a prerequisite obj-id.
+This is a comment and it has no specific meaning. The writer of the bundle MAY
+put any string here. The reader of the bundle MUST ignore the comment.
+
+=== Note on the shallow clone and a Git bundle
+
+Note that the prerequisites does not represent a shallow-clone boundary. The
+semantics of the prerequisites and the shallow-clone boundaries are different,
+and the Git bundle v2 format cannot represent a shallow clone repository.