moinsetup

Help

Changegroups
""""""""""""

    Changegroups are representations of repository revlog data, specifically
    the changelog data, root/flat manifest data, treemanifest data, and
    filelogs.
    
    There are 3 versions of changegroups: ``1``, ``2``, and ``3``. From a
    high-level, versions ``1`` and ``2`` are almost exactly the same, with the
    only difference being an additional item in the *delta header*. Version
    ``3`` adds support for storage flags in the *delta header* and optionally
    exchanging treemanifests (enabled by setting an option on the
    ``changegroup`` part in the bundle2).
    
    Changegroups when not exchanging treemanifests consist of 3 logical
    segments::
    
       +---------------------------------+
       |           |          |          |
       | changeset | manifest | filelogs |
       |           |          |          |
       |           |          |          |
       +---------------------------------+
    
    When exchanging treemanifests, there are 4 logical segments::
    
       +-------------------------------------------------+
       |           |          |               |          |
       | changeset |   root   | treemanifests | filelogs |
       |           | manifest |               |          |
       |           |          |               |          |
       +-------------------------------------------------+
    
    The principle building block of each segment is a *chunk*. A *chunk*
    is a framed piece of data::
    
       +---------------------------------------+
       |           |                           |
       |  length   |           data            |
       | (4 bytes) |   (<length - 4> bytes)    |
       |           |                           |
       +---------------------------------------+
    
    All integers are big-endian signed integers. Each chunk starts with a 32-bit
    integer indicating the length of the entire chunk (including the length field
    itself).
    
    There is a special case chunk that has a value of 0 for the length
    (``0x00000000``). We call this an *empty chunk*.
    
    Delta Groups
    ============
    
    A *delta group* expresses the content of a revlog as a series of deltas,
    or patches against previous revisions.
    
    Delta groups consist of 0 or more *chunks* followed by the *empty chunk*
    to signal the end of the delta group::
    
      +------------------------------------------------------------------------+
      |                |             |               |             |           |
      | chunk0 length  | chunk0 data | chunk1 length | chunk1 data |    0x0    |
      |   (4 bytes)    |  (various)  |   (4 bytes)   |  (various)  | (4 bytes) |
      |                |             |               |             |           |
      +------------------------------------------------------------------------+
    
    Each *chunk*'s data consists of the following::
    
      +---------------------------------------+
      |                        |              |
      |     delta header       |  delta data  |
      |  (various by version)  |  (various)   |
      |                        |              |
      +---------------------------------------+
    
    The *delta data* is a series of *delta*s that describe a diff from an existing
    entry (either that the recipient already has, or previously specified in the
    bundle/changegroup).
    
    The *delta header* is different between versions ``1``, ``2``, and
    ``3`` of the changegroup format.
    
    Version 1 (headerlen=80)::
    
       +------------------------------------------------------+
       |            |             |             |             |
       |    node    |   p1 node   |   p2 node   |  link node  |
       | (20 bytes) |  (20 bytes) |  (20 bytes) |  (20 bytes) |
       |            |             |             |             |
       +------------------------------------------------------+
    
    Version 2 (headerlen=100)::
    
       +------------------------------------------------------------------+
       |            |             |             |            |            |
       |    node    |   p1 node   |   p2 node   | base node  | link node  |
       | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) |
       |            |             |             |            |            |
       +------------------------------------------------------------------+
    
    Version 3 (headerlen=102)::
    
       +------------------------------------------------------------------------------+
       |            |             |             |            |            |           |
       |    node    |   p1 node   |   p2 node   | base node  | link node  |   flags   |
       | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) |
       |            |             |             |            |            |           |
       +------------------------------------------------------------------------------+
    
    The *delta data* consists of ``chunklen - 4 - headerlen`` bytes, which contain a
    series of *delta*s, densely packed (no separators). These deltas describe a diff
    from an existing entry (either that the recipient already has, or previously
    specified in the bundle/changegroup). The format is described more fully in
    ``hg help internals.bdiff``, but briefly::
    
       +---------------------------------------------------------------+
       |              |            |            |                      |
       | start offset | end offset | new length |        content       |
       |  (4 bytes)   |  (4 bytes) |  (4 bytes) | (<new length> bytes) |
       |              |            |            |                      |
       +---------------------------------------------------------------+
    
    Please note that the length field in the delta data does *not* include itself.
    
    In version 1, the delta is always applied against the previous node from
    the changegroup or the first parent if this is the first entry in the
    changegroup.
    
    In version 2 and up, the delta base node is encoded in the entry in the
    changegroup. This allows the delta to be expressed against any parent,
    which can result in smaller deltas and more efficient encoding of data.
    
    The *flags* field holds bitwise flags affecting the processing of revision
    data. The following flags are defined:
    
    32768
       Censored revision. The revision's fulltext has been replaced by censor
       metadata. May only occur on file revisions.
    16384
       Ellipsis revision. Revision hash does not match data (likely due to rewritten
       parents).
    8192
       Externally stored. The revision fulltext contains ``key:value`` ``\n``
       delimited metadata defining an object stored elsewhere. Used by the LFS
       extension.
    
    For historical reasons, the integer values are identical to revlog version 1
    per-revision storage flags and correspond to bits being set in this 2-byte
    field. Bits were allocated starting from the most-significant bit, hence the
    reverse ordering and allocation of these flags.
    
    Changeset Segment
    =================
    
    The *changeset segment* consists of a single *delta group* holding
    changelog data. The *empty chunk* at the end of the *delta group* denotes
    the boundary to the *manifest segment*.
    
    Manifest Segment
    ================
    
    The *manifest segment* consists of a single *delta group* holding manifest
    data. If treemanifests are in use, it contains only the manifest for the
    root directory of the repository. Otherwise, it contains the entire
    manifest data. The *empty chunk* at the end of the *delta group* denotes
    the boundary to the next segment (either the *treemanifests segment* or the
    *filelogs segment*, depending on version and the request options).
    
    Treemanifests Segment
    ---------------------
    
    The *treemanifests segment* only exists in changegroup version ``3``, and
    only if the 'treemanifest' param is part of the bundle2 changegroup part
    (it is not possible to use changegroup version 3 outside of bundle2).
    Aside from the filenames in the *treemanifests segment* containing a
    trailing ``/`` character, it behaves identically to the *filelogs segment*
    (see below). The final sub-segment is followed by an *empty chunk* (logically,
    a sub-segment with filename size 0). This denotes the boundary to the
    *filelogs segment*.
    
    Filelogs Segment
    ================
    
    The *filelogs segment* consists of multiple sub-segments, each
    corresponding to an individual file whose data is being described::
    
       +--------------------------------------------------+
       |          |          |          |     |           |
       | filelog0 | filelog1 | filelog2 | ... |    0x0    |
       |          |          |          |     | (4 bytes) |
       |          |          |          |     |           |
       +--------------------------------------------------+
    
    The final filelog sub-segment is followed by an *empty chunk* (logically,
    a sub-segment with filename size 0). This denotes the end of the segment
    and of the overall changegroup.
    
    Each filelog sub-segment consists of the following::
    
       +------------------------------------------------------+
       |                 |                      |             |
       | filename length |       filename       | delta group |
       |    (4 bytes)    | (<length - 4> bytes) |  (various)  |
       |                 |                      |             |
       +------------------------------------------------------+
    
    That is, a *chunk* consisting of the filename (not terminated or padded)
    followed by N chunks constituting the *delta group* for this file. The
    *empty chunk* at the end of each *delta group* denotes the boundary to the
    next filelog sub-segment.