mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Masaya Suzuki <>
Cc: Masaya Suzuki <>
Subject: [PATCH v3] doc: describe Git bundle format
Date: Fri,  7 Feb 2020 12:42:25 -0800	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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

Signed-off-by: Masaya Suzuki <>
Changes from v2:

* Change "sender" and "receiver" to "writer" and "reader".
* Add an example of a case that a bundle can reference an object outside of the
* Mention that the prerequisites are different from the shallow
  boundary, and the bundle format cannot represent a shallow clone repository.

 Documentation/technical/bundle-format.txt | 48 +++++++++++++++++++++++
 1 file changed, 48 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..0e828151a5
--- /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.

  parent reply	other threads:[~2020-02-07 20:42 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-01-30 22:58 [PATCH] doc: describe Git bundle format Masaya Suzuki
2020-01-31 13:56 ` Johannes Schindelin
2020-01-31 20:38 ` Junio C Hamano
2020-01-31 21:49   ` Masaya Suzuki
2020-01-31 23:01     ` Junio C Hamano
2020-01-31 23:57       ` Masaya Suzuki
2020-02-04 18:20         ` Junio C Hamano
2020-01-31 22:18 ` [PATCH v2] " Masaya Suzuki
2020-01-31 23:06   ` Junio C Hamano
2020-02-07 20:42   ` Masaya Suzuki [this message]
2020-02-07 20:44     ` [PATCH v3] " Masaya Suzuki
2020-02-07 20:59       ` Junio C Hamano
2020-02-07 22:21         ` Masaya Suzuki
2020-02-08  1:49           ` Junio C Hamano
2020-02-12 22:13             ` Masaya Suzuki
2020-02-12 22:43               ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).