# HG changeset patch # User Gregory Szorc # Date 2016-08-23 02:48:31 # Node ID 2435ba6c82e68a90aef129214af9dd9585442380 # Parent b42c26b0a78550d1b238674b5ffad6123ec9b76c help: document wire protocol capabilities All capabilities from the history of the project are now documented. diff --git a/mercurial/help/internals/wireprotocol.txt b/mercurial/help/internals/wireprotocol.txt --- a/mercurial/help/internals/wireprotocol.txt +++ b/mercurial/help/internals/wireprotocol.txt @@ -153,3 +153,218 @@ If the server receives an unknown comman response. The server terminates if it receives an empty command (a ``\n`` character). + +Capabilities +============ + +Servers advertise supported wire protocol features. This allows clients to +probe for server features before blindly calling a command or passing a +specific argument. + +The server's features are exposed via a *capabilities* string. This is a +space-delimited string of tokens/features. Some features are single words +like ``lookup`` or ``batch``. Others are complicated key-value pairs +advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word +values are used, each feature name can define its own encoding of sub-values. +Comma-delimited and ``x-www-form-urlencoded`` values are common. + +The following document capabilities defined by the canonical Mercurial server +implementation. + +batch +----- + +Whether the server supports the ``batch`` command. + +This capability/command was introduced in Mercurial 1.9 (released July 2011). + +branchmap +--------- + +Whether the server supports the ``branchmap`` command. + +This capability/command was introduced in Mercurial 1.3 (released July 2009). + +bundle2-exp +----------- + +Precursor to ``bundle2`` capability that was used before bundle2 was a +stable feature. + +This capability was introduced in Mercurial 3.0 behind an experimental +flag. This capability should not be observed in the wild. + +bundle2 +------- + +Indicates whether the server supports the ``bundle2`` data exchange format. + +The value of the capability is a URL quoted, newline (``\n``) delimited +list of keys or key-value pairs. + +A key is simply a URL encoded string. + +A key-value pair is a URL encoded key separated from a URL encoded value by +an ``=``. If the value is a list, elements are delimited by a ``,`` after +URL encoding. + +For example, say we have the values:: + + {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']} + +We would first construct a string:: + + HG20\nchangegroup=01,02\ndigests=sha1,sha512 + +We would then URL quote this string:: + + HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512 + +This capability was introduced in Mercurial 3.4 (released May 2015). + +changegroupsubset +----------------- + +Whether the server supports the ``changegroupsubset`` command. + +This capability was introduced in Mercurial 0.9.2 (released December +2006). + +This capability was introduced at the same time as the ``lookup`` +capability/command. + +getbundle +--------- + +Whether the server supports the ``getbundle`` command. + +This capability was introduced in Mercurial 1.9 (released July 2011). + +httpheader +---------- + +Whether the server supports receiving command arguments via HTTP request +headers. + +The value of the capability is an integer describing the max header +length that clients should send. Clients should ignore any content after a +comma in the value, as this is reserved for future use. + +This capability was introduced in Mercurial 1.9 (released July 2011). + +httppostargs +------------ + +**Experimental** + +Indicates that the server supports and prefers clients send command arguments +via a HTTP POST request as part of the request body. + +This capability was introduced in Mercurial 3.8 (released May 2016). + +known +----- + +Whether the server supports the ``known`` command. + +This capability/command was introduced in Mercurial 1.9 (released July 2011). + +lookup +------ + +Whether the server supports the ``lookup`` command. + +This capability was introduced in Mercurial 0.9.2 (released December +2006). + +This capability was introduced at the same time as the ``changegroupsubset`` +capability/command. + +pushkey +------- + +Whether the server supports the ``pushkey`` and ``listkeys`` commands. + +This capability was introduced in Mercurial 1.6 (released July 2010). + +standardbundle +-------------- + +**Unsupported** + +This capability was introduced during the Mercurial 0.9.2 development cycle in +2006. It was never present in a release, as it was replaced by the ``unbundle`` +capability. This capability should not be encountered in the wild. + +stream-preferred +---------------- + +If present the server prefers that clients clone using the streaming clone +protocol (``hg clone --uncompressed``) rather than the standard +changegroup/bundle based protocol. + +This capability was introduced in Mercurial 2.2 (released May 2012). + +streamreqs +---------- + +Indicates whether the server supports *streaming clones* and the *requirements* +that clients must support to receive it. + +If present, the server supports the ``stream_out`` command, which transmits +raw revlogs from the repository instead of changegroups. This provides a faster +cloning mechanism at the expense of more bandwidth used. + +The value of this capability is a comma-delimited list of repo format +*requirements*. These are requirements that impact the reading of data in +the ``.hg/store`` directory. An example value is +``streamreqs=generaldelta,revlogv1`` indicating the server repo requires +the ``revlogv1`` and ``generaldelta`` requirements. + +If the only format requirement is ``revlogv1``, the server may expose the +``stream`` capability instead of the ``streamreqs`` capability. + +This capability was introduced in Mercurial 1.7 (released November 2010). + +stream +------ + +Whether the server supports *streaming clones* from ``revlogv1`` repos. + +If present, the server supports the ``stream_out`` command, which transmits +raw revlogs from the repository instead of changegroups. This provides a faster +cloning mechanism at the expense of more bandwidth used. + +This capability was introduced in Mercurial 0.9.1 (released July 2006). + +When initially introduced, the value of the capability was the numeric +revlog revision. e.g. ``stream=1``. This indicates the changegroup is using +``revlogv1``. This simple integer value wasn't powerful enough, so the +``streamreqs`` capability was invented to handle cases where the repo +requirements have more than just ``revlogv1``. Newer servers omit the +``=1`` since it was the only value supported and the value of ``1`` can +be implied by clients. + +unbundlehash +------------ + +Whether the ``unbundle`` commands supports receiving a hash of all the +heads instead of a list. + +For more, see the documentation for the ``unbundle`` command. + +This capability was introduced in Mercurial 1.9 (released July 2011). + +unbundle +-------- + +Whether the server supports pushing via the ``unbundle`` command. + +This capability/command has been present since Mercurial 0.9.1 (released +July 2006). + +Mercurial 0.9.2 (released December 2006) added values to the capability +indicating which bundle types the server supports receiving. This value is a +comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values +reflects the priority/preference of that type, where the first value is the +most preferred type.