[PATCH 2 of 8 techdocs] help: add documentation for bundle types

Gregory Szorc gregory.szorc at gmail.com
Sun Dec 13 13:46:55 CST 2015


# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1450034872 28800
#      Sun Dec 13 11:27:52 2015 -0800
# Node ID 5cb89fe10dc8f9d016a81ff0c93af8fb68df2c8f
# Parent  d222327955686e4cbc7e1b3c6fe08d78691e3602
help: add documentation for bundle types

Bundle types and the high-level data format of each bundle isn't
documented anywhere. Let's document this as well.

Obviously there are many more details about bundles that could be
written about. But you have to start somewhere.

diff --git a/mercurial/help/internals/bundles.txt b/mercurial/help/internals/bundles.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/internals/bundles.txt
@@ -0,0 +1,97 @@
+Bundles
+=======
+
+A bundle is a container for repository data.
+
+Bundles are used as standalone files as well as the interchange format
+over the wire protocol used when two Mercurial peers communicate with
+each other.
+
+Headers
+-------
+
+Bundles produced since Mercurial 0.7 (September 2005) have a 4 byte
+header identifying the major bundle type. The header always begins with
+``HG`` and the follow 2 bytes indicate the bundle type/version. Some
+bundle types have additional data after this 4 byte header.
+
+The following sections describe each bundle header/type.
+
+HG10
+----
+
+``HG10`` headers indicate a *changegroup bundle*. This is the original
+bundle format, so it is sometimes referred to as *bundle1*. It has been
+present since version 0.7 (released September 2005).
+
+This header is followed by 2 bytes indicating the compression algorithm
+used for data that follows. All subsequent data following this
+compression identifier is compressed according to the algorithm/method
+specified.
+
+Supported algorithms include the following.
+
+``BZ``
+   *bzip2* compression.
+
+   Bzip2 compressors emit a leading ``BZ`` header. Mercurial uses this
+   leading ``BZ`` as part of the bundle header. Therefore consumers
+   of bzip2 bundles need to *seed* the bzip2 decompressor with ``BZ`` or
+   seek the input stream back to the beginning of the algorithm component
+   of the bundle header so that decompressor input is valid. This behavior
+   is unique among supported compression algorithms.
+
+   Supported since version 0.7 (released December 2006).
+
+``GZ``
+  *zlib* compression.
+
+   Supported since version 0.9.2 (released December 2006).
+
+``UN``
+  *Uncompressed* or no compression. Unmodified changegroup data follows.
+
+  Supported since version 0.9.2 (released December 2006).
+
+3rd party extensions may implement their own compression. However, no
+authority reserves values for their compression algorithm identifiers.
+
+HG2X
+----
+
+``HG2X`` headers (where ``X`` is any value) denote a *bundle2* bundle.
+Bundle2 bundles are a container format for various kinds of repository
+data and capabilities, beyond changegroup data (which was the only data
+supported by ``HG10`` bundles.
+
+``HG20`` is currently the only defined bundle2 version.
+
+The ``HG20`` format is not yet documented here. See the inline comments
+in ``mercurial/exchange.py`` for now.
+
+Initial ``HG20`` support was added in Mercurial 3.0 (released May
+2014). However, bundle2 bundles were hidden behind an experimental flag
+until version 3.5 (released August 2015), when they were enabled in the
+wire protocol. Various commands (including ``hg bundle``) did not
+support generating bundle2 files until Mercurial 3.6 (released November
+2015).
+
+HGS1
+----
+
+*Experimental*
+
+A ``HGS1`` header indicates a *streaming clone bundle*. This is a bundle
+that contains raw revlog data from a repository store. (Typically revlog
+data is exchanged in the form of changegroups.)
+
+The purpose of *streaming clone bundles* are to *clone* repository data
+very efficiently.
+
+The ``HGS1`` header is always followed by 2 bytes indicating a
+compression algorithm of the data that follows. Only ``UN``
+(uncompressed data) is currently allowed.
+
+``HGS1UN`` support was added as an experimental feature in version 3.6
+(released November 2015) as part of the initial offering of the *clone
+bundles* feature.


More information about the Mercurial-devel mailing list