changegroups: add documentation for cg3

mercurial/help/internals/changegroups.txt

@@ -4,9 +4,11 b' Changegroups'
 Changegroups are representations of repository revlog data, specifically
 the changelog, manifest, and filelogs.
 
-There are 2 versions of changegroups: ``1`` and ``2``. From a
-high-level, they are almost exactly the same, with the only difference
-being a header on entries in the changeset segment.
+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 a header on entries in the changeset
+segment. Version ``3`` adds support for exchanging treemanifests and
+includes revlog flags in the delta header.
 
 Changegroups consists of 3 logical segments::
 
@@ -60,8 +62,8 b" Each *chunk*'s data consists of the foll"
 The *length* field is the byte length of the remaining 3 logical pieces
 of data. The *delta* is a diff from an existing entry in the changelog.
 
-The *delta header* is different between versions ``1`` and ``2`` of the
-changegroup format.
+The *delta header* is different between versions ``1``, ``2``, and
+``3`` of the changegroup format.
 
 Version 1::
 
@@ -81,6 +83,15 b' Version 2::'
    |            |             |             |            |            |
    +------------------------------------------------------------------+
 
+Version 3::
+
+   +------------------------------------------------------------------------------+
+   |            |             |             |            |            |           |
+   |    node    |   p1 node   |   p2 node   | base node  | link node  | flags     |
+   | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) |
+   |            |             |             |            |            |           |
+   +------------------------------------------------------------------------------+
+
 The *mdiff header* consists of 3 32-bit big-endian signed integers
 describing offsets at which to apply the following delta content::
 
@@ -125,6 +136,10 b' corresponding to an individual file whos'
    |          |          |          |     |
    +--------------------------------------+
 
+In version ``3`` of the changegroup format, filelogs may include
+directory logs when treemanifests are in use. directory logs are
+identified by having a trailing '/' on their filename (see below).
+
 The final filelog sub-segment is followed by an *empty chunk* to denote
 the end of the segment and the overall changegroup.
 

tests/test-help.t

@@ -885,9 +885,11 b' sub-topics can be accessed'
       Changegroups are representations of repository revlog data, specifically
       the changelog, manifest, and filelogs.
   
-      There are 2 versions of changegroups: "1" and "2". From a high-level, they
-      are almost exactly the same, with the only difference being a header on
-      entries in the changeset segment.
+      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 a header on entries in the changeset segment. Version "3"
+      adds support for exchanging treemanifests and includes revlog flags in the
+      delta header.
   
       Changegroups consists of 3 logical segments:
   
@@ -941,7 +943,7 b' sub-topics can be accessed'
       The *length* field is the byte length of the remaining 3 logical pieces of
       data. The *delta* is a diff from an existing entry in the changelog.
   
-      The *delta header* is different between versions "1" and "2" of the
+      The *delta header* is different between versions "1", "2", and "3" of the
       changegroup format.
   
       Version 1:
@@ -962,6 +964,15 b' sub-topics can be accessed'
         |            |             |             |            |            |
         +------------------------------------------------------------------+
   
+      Version 3:
+  
+        +------------------------------------------------------------------------------+
+        |            |             |             |            |            |           |
+        |    node    |   p1 node   |   p2 node   | base node  | link node  | flags     |
+        | (20 bytes) |  (20 bytes) |  (20 bytes) | (20 bytes) | (20 bytes) | (2 bytes) |
+        |            |             |             |            |            |           |
+        +------------------------------------------------------------------------------+
+  
       The *mdiff header* consists of 3 32-bit big-endian signed integers
       describing offsets at which to apply the following delta content:
   
@@ -1006,6 +1017,10 b' sub-topics can be accessed'
         |          |          |          |     |
         +--------------------------------------+
   
+      In version "3" of the changegroup format, filelogs may include directory
+      logs when treemanifests are in use. directory logs are identified by
+      having a trailing '/' on their filename (see below).
+  
       The final filelog sub-segment is followed by an *empty chunk* to denote
       the end of the segment and the overall changegroup.