mercurial: comparison tests/test-help.t

equal deleted inserted replaced

-:08e26ef4ad35
+:119790e1c67c
 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-
+There are 4 versions of changegroups: "1", "2", "3" and "4". 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).
+"changegroup" part in the bundle2). Version "4" adds support for
+exchanging sidedata (additional revision metadata not part of the digest).
 Changegroups when not exchanging treemanifests consist of 3 logical
 segments:
 +---------------------------------+
 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
+The *delta header* is different between versions "1", "2", "3" and "4" of
-changegroup format.
+the changegroup format.
 Version 1 (headerlen=80):
 +------------------------------------------------------+
 |            |             |             |             |
 |    node    |   p1 node   |   p2 node   | base node  | link node  |   flags   |
 | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) |
 |            |             |             |            |            |           |
 +------------------------------------------------------------------------------+
+Version 4 (headerlen=103):
++------------------------------------------------------------------------------+----------+
+|            |             |             |            |            |           |          |
+|    node    |   p1 node   |   p2 node   | base node  | link node  |   flags   |  pflags  |
+| (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) | (1 byte) |
+|            |             |             |            |            |           |          |
++------------------------------------------------------------------------------+----------+
 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:
 8192
 Externally stored. The revision fulltext contains "key:value" "\n"
 delimited metadata defining an object stored elsewhere. Used by the LFS
 extension.
+4096
+Contains copy information. This revision changes files in a way that
+could affect copy tracing. This does *not* affect changegroup handling,
+but is relevant for other parts of Mercurial.
 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.
+The *pflags* (protocol flags) field holds bitwise flags affecting the
+protocol itself. They are first in the header since they may affect the
+handling of the rest of the fields in a future version. They are defined
+as such:
+1 indicates whether to read a chunk of sidedata (of variable length) right
+after the revision flags.
 Changeset Segment
 =================
 The *changeset segment* consists of a single *delta group* holding
 the *filelogs segment*, depending on version and the request options).
 Treemanifests Segment
 ---------------------
-The *treemanifests segment* only exists in changegroup version "3", and
+The *treemanifests segment* only exists in changegroup version "3" and
-only if the 'treemanifest' param is part of the bundle2 changegroup part
+"4", and only if the 'treemanifest' param is part of the bundle2
-(it is not possible to use changegroup version 3 outside of bundle2).
+changegroup part (it is not possible to use changegroup version 3 or 4
-Aside from the filenames in the *treemanifests segment* containing a
+outside of bundle2). Aside from the filenames in the *treemanifests
-trailing "/" character, it behaves identically to the *filelogs segment*
+segment* containing a trailing "/" character, it behaves identically to
-(see below). The final sub-segment is followed by an *empty chunk*
+the *filelogs segment* (see below). The final sub-segment is followed by
-(logically, a sub-segment with filename size 0). This denotes the boundary
+an *empty chunk* (logically, a sub-segment with filename size 0). This
-to the *filelogs segment*.
+denotes the boundary to the *filelogs segment*.
 Filelogs Segment
 ================
 The *filelogs segment* consists of multiple sub-segments, each
 Changegroups are representations of repository revlog data, specifically
 the changelog data, root/flat manifest data, treemanifest data, and
 filelogs.
 </p>
 <p>
-There are 3 versions of changegroups: &quot;1&quot;, &quot;2&quot;, and &quot;3&quot;. From a
+There are 4 versions of changegroups: &quot;1&quot;, &quot;2&quot;, &quot;3&quot; and &quot;4&quot;. From a
 high-level, versions &quot;1&quot; and &quot;2&quot; are almost exactly the same, with the
 only difference being an additional item in the *delta header*. Version
 &quot;3&quot; adds support for storage flags in the *delta header* and optionally
 exchanging treemanifests (enabled by setting an option on the
-&quot;changegroup&quot; part in the bundle2).
+&quot;changegroup&quot; part in the bundle2). Version &quot;4&quot; adds support for exchanging
+sidedata (additional revision metadata not part of the digest).
 </p>
 <p>
 Changegroups when not exchanging treemanifests consist of 3 logical
 segments:
 </p>
 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).
 </p>
 <p>
-The *delta header* is different between versions &quot;1&quot;, &quot;2&quot;, and
+The *delta header* is different between versions &quot;1&quot;, &quot;2&quot;, &quot;3&quot; and &quot;4&quot;
-&quot;3&quot; of the changegroup format.
+of the changegroup format.
 </p>
 <p>
 Version 1 (headerlen=80):
 </p>
 <pre>
 | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) |
 |            |             |             |            |            |           |
 +------------------------------------------------------------------------------+
 </pre>
 <p>
+Version 4 (headerlen=103):
+</p>
+<pre>
++------------------------------------------------------------------------------+----------+
+|            |             |             |            |            |           |          |
+|    node    |   p1 node   |   p2 node   | base node  | link node  |   flags   |  pflags  |
+| (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) | (1 byte) |
+|            |             |             |            |            |           |          |
++------------------------------------------------------------------------------+----------+
+</pre>
+<p>
 The *delta data* consists of &quot;chunklen - 4 - headerlen&quot; 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
 &quot;hg help internals.bdiff&quot;, but briefly:
 <dd>Censored revision. The revision's fulltext has been replaced by censor metadata. May only occur on file revisions.
 <dt>16384
 <dd>Ellipsis revision. Revision hash does not match data (likely due to rewritten parents).
 <dt>8192
 <dd>Externally stored. The revision fulltext contains &quot;key:value&quot; &quot;\n&quot; delimited metadata defining an object stored elsewhere. Used by the LFS extension.
+<dt>4096
+<dd>Contains copy information. This revision changes files in a way that could affect copy tracing. This does *not* affect changegroup handling, but is relevant for other parts of Mercurial.
 </dl>
 <p>
 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.
 </p>
+<p>
+The *pflags* (protocol flags) field holds bitwise flags affecting the protocol
+itself. They are first in the header since they may affect the handling of the
+rest of the fields in a future version. They are defined as such:
+</p>
+<dl>
+<dt>1 indicates whether to read a chunk of sidedata (of variable length) right
+<dd>after the revision flags.
+</dl>
 <h2>Changeset Segment</h2>
 <p>
 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*.
 the boundary to the next segment (either the *treemanifests segment* or the
 *filelogs segment*, depending on version and the request options).
 </p>
 <h3>Treemanifests Segment</h3>
 <p>
-The *treemanifests segment* only exists in changegroup version &quot;3&quot;, and
+The *treemanifests segment* only exists in changegroup version &quot;3&quot; and &quot;4&quot;,
-only if the 'treemanifest' param is part of the bundle2 changegroup part
+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).
+(it is not possible to use changegroup version 3 or 4 outside of bundle2).
 Aside from the filenames in the *treemanifests segment* containing a
 trailing &quot;/&quot; 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*.

changeset 47077	119790e1c67c
parent 47017	da4e6d7a8fdd
child 47274	0470a44b9e74