[v2] doc: describe Git bundle format

Commit Message

Masaya Suzuki Jan. 31, 2020, 10:18 p.m. UTC

The bundle format was not documented. Describe the format with ABNF and
explain the meaning of each part.

Signed-off-by: Masaya Suzuki <[e-mail]>
---
Changes from v1:

* Update the ABNF definition so that prerequisites come before references.
* Adopt Junio's suggestion on the semantics section.
* State that the receiver MUST ignore the comments in the prereqs.
* Change "you" to "the receiver" and "the sender" (I wonder if this should be
  "writer" and "reader").

 Documentation/technical/bundle-format.txt | 41 +++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 Documentation/technical/bundle-format.txt

Comments

Junio C Hamano Jan. 31, 2020, 11:06 p.m. UTC | #1

Masaya Suzuki <[e-mail]> writes:

> * Change "you" to "the receiver" and "the sender" (I wonder if this should be
>   "writer" and "reader").

I come from "a bundle is a frozen snapshot of 'git fetch' transfer"
school, and consider the act of reading a "fetch" too much, but I
think "writer" and "reader" is more understandable for new readers.

Thanks.

Patch

diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt
new file mode 100644
index 0000000000..f568fcd7d1
--- /dev/null
+++ b/Documentation/technical/bundle-format.txt
@@ -0,0 +1,41 @@ 
+= 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
+  receiver 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 and/or expressed as a delta against prerequisite
+  objects.
+
+* "References" record the tips of the history graph, iow, what the receiver 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 sender of the bundle MAY
+put any string here. The receiver of the bundle MUST ignore the comment.