The bundle format was not documented. Describe the format with ABNF and explain the meaning of each part. Signed-off-by: Masaya Suzuki <masayasuzuki@xxxxxxxxxx> --- 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 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. -- 2.25.0.341.g760bfbb309-goog
