Mercurial > public > mercurial-scm > hg-stable

annotate mercurial/help/internals/wireprotocol.txt @ 31267:11831d755b51

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge: remove uses of manifest.matches This gets rid of the manifest.matches calls in merge.py in favor of the new api. This is part of getting rid of manifest.matches since it is O(manifest).
author Durham Goode <durham@fb.com>
date Tue, 07 Mar 2017 18:38:20 -0800
parents 7283719e2bfd
children 435a3842ca3a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
29865
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
1 The Mercurial wire protocol is a request-response based protocol
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
2 with multiple wire representations.
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
3
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
4 Each request is modeled as a command name, a dictionary of arguments, and
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
5 optional raw input. Command arguments and their types are intrinsic
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
6 properties of commands. So is the response type of the command. This means
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
7 clients can't always send arbitrary arguments to servers and servers can't
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
8 return multiple response types.
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
9
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
10 The protocol is synchronous and does not support multiplexing (concurrent
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
11 commands).
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
12
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
13 Transport Protocols
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
14 ===================
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
15
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
16 HTTP Transport
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
17 --------------
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
18
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
19 Commands are issued as HTTP/1.0 or HTTP/1.1 requests. Commands are
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
20 sent to the base URL of the repository with the command name sent in
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
21 the ``cmd`` query string parameter. e.g.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
22 ``https://example.com/repo?cmd=capabilities``. The HTTP method is ``GET``
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
23 or ``POST`` depending on the command and whether there is a request
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
24 body.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
25
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
26 Command arguments can be sent multiple ways.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
27
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
28 The simplest is part of the URL query string using ``x-www-form-urlencoded``
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
29 encoding (see Python's ``urllib.urlencode()``. However, many servers impose
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
30 length limitations on the URL. So this mechanism is typically only used if
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
31 the server doesn't support other mechanisms.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
32
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
33 If the server supports the ``httpheader`` capability, command arguments can
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
34 be sent in HTTP request headers named ``X-HgArg-<N>`` where ``<N>`` is an
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
35 integer starting at 1. A ``x-www-form-urlencoded`` representation of the
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
36 arguments is obtained. This full string is then split into chunks and sent
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
37 in numbered ``X-HgArg-<N>`` headers. The maximum length of each HTTP header
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
38 is defined by the server in the ``httpheader`` capability value, which defaults
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
39 to ``1024``. The server reassembles the encoded arguments string by
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
40 concatenating the ``X-HgArg-<N>`` headers then URL decodes them into a
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
41 dictionary.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
42
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
43 The list of ``X-HgArg-<N>`` headers should be added to the ``Vary`` request
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
44 header to instruct caches to take these headers into consideration when caching
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
45 requests.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
46
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
47 If the server supports the ``httppostargs`` capability, the client
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
48 may send command arguments in the HTTP request body as part of an
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
49 HTTP POST request. The command arguments will be URL encoded just like
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
50 they would for sending them via HTTP headers. However, no splitting is
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
51 performed: the raw arguments are included in the HTTP request body.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
52
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
53 The client sends a ``X-HgArgs-Post`` header with the string length of the
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
54 encoded arguments data. Additional data may be included in the HTTP
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
55 request body immediately following the argument data. The offset of the
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
56 non-argument data is defined by the ``X-HgArgs-Post`` header. The
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
57 ``X-HgArgs-Post`` header is not required if there is no argument data.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
58
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
59 Additional command data can be sent as part of the HTTP request body. The
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
60 default ``Content-Type`` when sending data is ``application/mercurial-0.1``.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
61 A ``Content-Length`` header is currently always sent.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
62
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
63 Example HTTP requests::
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
64
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
65 GET /repo?cmd=capabilities
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
66 X-HgArg-1: foo=bar&baz=hello%20world
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
67
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
68 The request media type should be chosen based on server support. If the
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
69 ``httpmediatype`` server capability is present, the client should send
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
70 the newest mutually supported media type. If this capability is absent,
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
71 the client must assume the server only supports the
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
72 ``application/mercurial-0.1`` media type.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
73
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
74 The ``Content-Type`` HTTP response header identifies the response as coming
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
75 from Mercurial and can also be used to signal an error has occurred.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
76
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
77 The ``application/mercurial-*`` media types indicate a generic Mercurial
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
78 data type.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
79
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
80 The ``application/mercurial-0.1`` media type is raw Mercurial data. It is the
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
81 predecessor of the format below.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
82
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
83 The ``application/mercurial-0.2`` media type is compression framed Mercurial
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
84 data. The first byte of the payload indicates the length of the compression
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
85 format identifier that follows. Next are N bytes indicating the compression
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
86 format. e.g. ``zlib``. The remaining bytes are compressed according to that
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
87 compression format. The decompressed data behaves the same as with
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
88 ``application/mercurial-0.1``.
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
89
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
90 The ``application/hg-error`` media type indicates a generic error occurred.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
91 The content of the HTTP response body typically holds text describing the
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
92 error.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
93
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
94 The ``application/hg-changegroup`` media type indicates a changegroup response
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
95 type.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
96
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
97 Clients also accept the ``text/plain`` media type. All other media
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
98 types should cause the client to error.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
99
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
100 Behavior of media types is further described in the ``Content Negotiation``
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
101 section below.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
102
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
103 Clients should issue a ``User-Agent`` request header that identifies the client.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
104 The server should not use the ``User-Agent`` for feature detection.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
105
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
106 A command returning a ``string`` response issues a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
107 ``application/mercurial-0.*`` media type and the HTTP response body contains
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
108 the raw string value (after compression decoding, if used). A
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
109 ``Content-Length`` header is typically issued, but not required.
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
110
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
111 A command returning a ``stream`` response issues a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
112 ``application/mercurial-0.*`` media type and the HTTP response is typically
29866
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
113 using *chunked transfer* (``Transfer-Encoding: chunked``).
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
114
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
115 SSH Transport
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
116 =============
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
117
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
118 The SSH transport is a custom text-based protocol suitable for use over any
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
119 bi-directional stream transport. It is most commonly used with SSH.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
120
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
121 A SSH transport server can be started with ``hg serve --stdio``. The stdin,
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
122 stderr, and stdout file descriptors of the started process are used to exchange
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
123 data. When Mercurial connects to a remote server over SSH, it actually starts
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
124 a ``hg serve --stdio`` process on the remote server.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
125
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
126 Commands are issued by sending the command name followed by a trailing newline
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
127 ``\n`` to the server. e.g. ``capabilities\n``.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
128
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
129 Command arguments are sent in the following format::
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
130
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
131 <argument> <length>\n<value>
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
132
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
133 That is, the argument string name followed by a space followed by the
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
134 integer length of the value (expressed as a string) followed by a newline
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
135 (``\n``) followed by the raw argument value.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
136
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
137 Dictionary arguments are encoded differently::
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
138
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
139 <argument> <# elements>\n
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
140 <key1> <length1>\n<value1>
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
141 <key2> <length2>\n<value2>
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
142 ...
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
143
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
144 Non-argument data is sent immediately after the final argument value. It is
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
145 encoded in chunks::
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
146
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
147 <length>\n<data>
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
148
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
149 Each command declares a list of supported arguments and their types. If a
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
150 client sends an unknown argument to the server, the server should abort
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
151 immediately. The special argument ``*`` in a command's definition indicates
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
152 that all argument names are allowed.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
153
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
154 The definition of supported arguments and types is initially made when a
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
155 new command is implemented. The client and server must initially independently
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
156 agree on the arguments and their types. This initial set of arguments can be
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
157 supplemented through the presence of *capabilities* advertised by the server.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
158
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
159 Each command has a defined expected response type.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
160
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
161 A ``string`` response type is a length framed value. The response consists of
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
162 the string encoded integer length of a value followed by a newline (``\n``)
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
163 followed by the value. Empty values are allowed (and are represented as
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
164 ``0\n``).
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
165
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
166 A ``stream`` response type consists of raw bytes of data. There is no framing.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
167
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
168 A generic error response type is also supported. It consists of a an error
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
169 message written to ``stderr`` followed by ``\n-\n``. In addition, ``\n`` is
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
170 written to ``stdout``.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
171
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
172 If the server receives an unknown command, it will send an empty ``string``
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
173 response.
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
174
b42c26b0a785 help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29865
diff changeset
175 The server terminates if it receives an empty command (a ``\n`` character).
29867
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
176
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
177 Capabilities
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
178 ============
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
179
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
180 Servers advertise supported wire protocol features. This allows clients to
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
181 probe for server features before blindly calling a command or passing a
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
182 specific argument.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
183
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
184 The server's features are exposed via a *capabilities* string. This is a
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
185 space-delimited string of tokens/features. Some features are single words
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
186 like ``lookup`` or ``batch``. Others are complicated key-value pairs
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
187 advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
188 values are used, each feature name can define its own encoding of sub-values.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
189 Comma-delimited and ``x-www-form-urlencoded`` values are common.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
190
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
191 The following document capabilities defined by the canonical Mercurial server
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
192 implementation.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
193
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
194 batch
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
195 -----
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
196
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
197 Whether the server supports the ``batch`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
198
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
199 This capability/command was introduced in Mercurial 1.9 (released July 2011).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
200
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
201 branchmap
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
202 ---------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
203
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
204 Whether the server supports the ``branchmap`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
205
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
206 This capability/command was introduced in Mercurial 1.3 (released July 2009).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
207
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
208 bundle2-exp
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
209 -----------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
210
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
211 Precursor to ``bundle2`` capability that was used before bundle2 was a
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
212 stable feature.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
213
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
214 This capability was introduced in Mercurial 3.0 behind an experimental
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
215 flag. This capability should not be observed in the wild.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
216
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
217 bundle2
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
218 -------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
219
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
220 Indicates whether the server supports the ``bundle2`` data exchange format.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
221
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
222 The value of the capability is a URL quoted, newline (``\n``) delimited
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
223 list of keys or key-value pairs.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
224
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
225 A key is simply a URL encoded string.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
226
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
227 A key-value pair is a URL encoded key separated from a URL encoded value by
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
228 an ``=``. If the value is a list, elements are delimited by a ``,`` after
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
229 URL encoding.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
230
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
231 For example, say we have the values::
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
232
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
233 {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']}
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
234
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
235 We would first construct a string::
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
236
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
237 HG20\nchangegroup=01,02\ndigests=sha1,sha512
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
238
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
239 We would then URL quote this string::
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
240
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
241 HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
242
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
243 This capability was introduced in Mercurial 3.4 (released May 2015).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
244
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
245 changegroupsubset
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
246 -----------------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
247
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
248 Whether the server supports the ``changegroupsubset`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
249
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
250 This capability was introduced in Mercurial 0.9.2 (released December
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
251 2006).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
252
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
253 This capability was introduced at the same time as the ``lookup``
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
254 capability/command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
255
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
256 compression
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
257 -----------
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
258
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
259 Declares support for negotiating compression formats.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
260
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
261 Presence of this capability indicates the server supports dynamic selection
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
262 of compression formats based on the client request.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
263
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
264 Servers advertising this capability are required to support the
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
265 ``application/mercurial-0.2`` media type in response to commands returning
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
266 streams. Servers may support this media type on any command.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
267
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
268 The value of the capability is a comma-delimited list of strings declaring
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
269 supported compression formats. The order of the compression formats is in
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
270 server-preferred order, most preferred first.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
271
30761
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
272 The identifiers used by the official Mercurial distribution are:
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
273
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
274 bzip2
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
275 bzip2
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
276 none
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
277 uncompressed / raw data
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
278 zlib
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
279 zlib (no gzip header)
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
280 zstd
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
281 zstd
7283719e2bfd util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30760
diff changeset
282
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
283 This capability was introduced in Mercurial 4.1 (released February 2017).
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
284
29867
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
285 getbundle
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
286 ---------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
287
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
288 Whether the server supports the ``getbundle`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
289
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
290 This capability was introduced in Mercurial 1.9 (released July 2011).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
291
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
292 httpheader
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
293 ----------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
294
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
295 Whether the server supports receiving command arguments via HTTP request
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
296 headers.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
297
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
298 The value of the capability is an integer describing the max header
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
299 length that clients should send. Clients should ignore any content after a
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
300 comma in the value, as this is reserved for future use.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
301
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
302 This capability was introduced in Mercurial 1.9 (released July 2011).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
303
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
304 httpmediatype
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
305 -------------
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
306
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
307 Indicates which HTTP media types (``Content-Type`` header) the server is
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
308 capable of receiving and sending.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
309
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
310 The value of the capability is a comma-delimited list of strings identifying
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
311 support for media type and transmission direction. The following strings may
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
312 be present:
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
313
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
314 0.1rx
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
315 Indicates server support for receiving ``application/mercurial-0.1`` media
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
316 types.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
317
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
318 0.1tx
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
319 Indicates server support for sending ``application/mercurial-0.1`` media
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
320 types.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
321
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
322 0.2rx
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
323 Indicates server support for receiving ``application/mercurial-0.2`` media
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
324 types.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
325
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
326 0.2tx
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
327 Indicates server support for sending ``application/mercurial-0.2`` media
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
328 types.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
329
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
330 minrx=X
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
331 Minimum media type version the server is capable of receiving. Value is a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
332 string like ``0.2``.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
333
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
334 This capability can be used by servers to limit connections from legacy
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
335 clients not using the latest supported media type. However, only clients
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
336 with knowledge of this capability will know to consult this value. This
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
337 capability is present so the client may issue a more user-friendly error
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
338 when the server has locked out a legacy client.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
339
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
340 mintx=X
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
341 Minimum media type version the server is capable of sending. Value is a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
342 string like ``0.1``.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
343
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
344 Servers advertising support for the ``application/mercurial-0.2`` media type
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
345 should also advertise the ``compression`` capability.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
346
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
347 This capability was introduced in Mercurial 4.1 (released February 2017).
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
348
29867
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
349 httppostargs
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
350 ------------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
351
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
352 **Experimental**
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
353
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
354 Indicates that the server supports and prefers clients send command arguments
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
355 via a HTTP POST request as part of the request body.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
356
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
357 This capability was introduced in Mercurial 3.8 (released May 2016).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
358
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
359 known
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
360 -----
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
361
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
362 Whether the server supports the ``known`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
363
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
364 This capability/command was introduced in Mercurial 1.9 (released July 2011).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
365
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
366 lookup
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
367 ------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
368
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
369 Whether the server supports the ``lookup`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
370
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
371 This capability was introduced in Mercurial 0.9.2 (released December
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
372 2006).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
373
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
374 This capability was introduced at the same time as the ``changegroupsubset``
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
375 capability/command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
376
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
377 pushkey
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
378 -------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
379
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
380 Whether the server supports the ``pushkey`` and ``listkeys`` commands.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
381
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
382 This capability was introduced in Mercurial 1.6 (released July 2010).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
383
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
384 standardbundle
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
385 --------------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
386
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
387 **Unsupported**
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
388
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
389 This capability was introduced during the Mercurial 0.9.2 development cycle in
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
390 2006. It was never present in a release, as it was replaced by the ``unbundle``
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
391 capability. This capability should not be encountered in the wild.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
392
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
393 stream-preferred
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
394 ----------------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
395
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
396 If present the server prefers that clients clone using the streaming clone
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
397 protocol (``hg clone --uncompressed``) rather than the standard
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
398 changegroup/bundle based protocol.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
399
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
400 This capability was introduced in Mercurial 2.2 (released May 2012).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
401
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
402 streamreqs
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
403 ----------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
404
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
405 Indicates whether the server supports *streaming clones* and the *requirements*
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
406 that clients must support to receive it.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
407
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
408 If present, the server supports the ``stream_out`` command, which transmits
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
409 raw revlogs from the repository instead of changegroups. This provides a faster
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
410 cloning mechanism at the expense of more bandwidth used.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
411
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
412 The value of this capability is a comma-delimited list of repo format
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
413 *requirements*. These are requirements that impact the reading of data in
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
414 the ``.hg/store`` directory. An example value is
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
415 ``streamreqs=generaldelta,revlogv1`` indicating the server repo requires
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
416 the ``revlogv1`` and ``generaldelta`` requirements.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
417
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
418 If the only format requirement is ``revlogv1``, the server may expose the
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
419 ``stream`` capability instead of the ``streamreqs`` capability.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
420
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
421 This capability was introduced in Mercurial 1.7 (released November 2010).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
422
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
423 stream
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
424 ------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
425
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
426 Whether the server supports *streaming clones* from ``revlogv1`` repos.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
427
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
428 If present, the server supports the ``stream_out`` command, which transmits
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
429 raw revlogs from the repository instead of changegroups. This provides a faster
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
430 cloning mechanism at the expense of more bandwidth used.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
431
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
432 This capability was introduced in Mercurial 0.9.1 (released July 2006).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
433
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
434 When initially introduced, the value of the capability was the numeric
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
435 revlog revision. e.g. ``stream=1``. This indicates the changegroup is using
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
436 ``revlogv1``. This simple integer value wasn't powerful enough, so the
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
437 ``streamreqs`` capability was invented to handle cases where the repo
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
438 requirements have more than just ``revlogv1``. Newer servers omit the
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
439 ``=1`` since it was the only value supported and the value of ``1`` can
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
440 be implied by clients.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
441
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
442 unbundlehash
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
443 ------------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
444
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
445 Whether the ``unbundle`` commands supports receiving a hash of all the
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
446 heads instead of a list.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
447
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
448 For more, see the documentation for the ``unbundle`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
449
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
450 This capability was introduced in Mercurial 1.9 (released July 2011).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
451
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
452 unbundle
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
453 --------
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
454
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
455 Whether the server supports pushing via the ``unbundle`` command.
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
456
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
457 This capability/command has been present since Mercurial 0.9.1 (released
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
458 July 2006).
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
459
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
460 Mercurial 0.9.2 (released December 2006) added values to the capability
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
461 indicating which bundle types the server supports receiving. This value is a
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
462 comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
463 reflects the priority/preference of that type, where the first value is the
2435ba6c82e6 help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29866
diff changeset
464 most preferred type.
29868
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
465
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
466 Handshake Protocol
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
467 ==================
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
468
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
469 While not explicitly required, it is common for clients to perform a
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
470 *handshake* when connecting to a server. The handshake accomplishes 2 things:
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
471
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
472 * Obtaining capabilities and other server features
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
473 * Flushing extra server output (e.g. SSH servers may print extra text
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
474 when connecting that may confuse the wire protocol)
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
475
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
476 This isn't a traditional *handshake* as far as network protocols go because
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
477 there is no persistent state as a result of the handshake: the handshake is
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
478 simply the issuing of commands and commands are stateless.
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
479
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
480 The canonical clients perform a capabilities lookup at connection establishment
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
481 time. This is because clients must assume a server only supports the features
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
482 of the original Mercurial server implementation until proven otherwise (from
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
483 advertised capabilities). Nearly every server running today supports features
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
484 that weren't present in the original Mercurial server implementation. Rather
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
485 than wait for a client to perform functionality that needs to consult
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
486 capabilities, it issues the lookup at connection start to avoid any delay later.
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
487
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
488 For HTTP servers, the client sends a ``capabilities`` command request as
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
489 soon as the connection is established. The server responds with a capabilities
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
490 string, which the client parses.
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
491
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
492 For SSH servers, the client sends the ``hello`` command (no arguments)
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
493 and a ``between`` command with the ``pairs`` argument having the value
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
494 ``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``.
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
495
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
496 The ``between`` command has been supported since the original Mercurial
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
497 server. Requesting the empty range will return a ``\n`` string response,
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
498 which will be encoded as ``1\n\n`` (value length of ``1`` followed by a newline
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
499 followed by the value, which happens to be a newline).
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
500
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
501 The ``hello`` command was later introduced. Servers supporting it will issue
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
502 a response to that command before sending the ``1\n\n`` response to the
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
503 ``between`` command. Servers not supporting ``hello`` will send an empty
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
504 response (``0\n``).
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
505
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
506 In addition to the expected output from the ``hello`` and ``between`` commands,
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
507 servers may also send other output, such as *message of the day (MOTD)*
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
508 announcements. Clients assume servers will send this output before the
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
509 Mercurial server replies to the client-issued commands. So any server output
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
510 not conforming to the expected command responses is assumed to be not related
f0d47aca1d47 help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29867
diff changeset
511 to Mercurial and can be ignored.
29869
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
512
30760
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
513 Content Negotiation
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
514 ===================
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
515
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
516 The wire protocol has some mechanisms to help peers determine what content
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
517 types and encoding the other side will accept. Historically, these mechanisms
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
518 have been built into commands themselves because most commands only send a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
519 well-defined response type and only certain commands needed to support
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
520 functionality like compression.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
521
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
522 Currently, only the HTTP transport supports content negotiation at the protocol
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
523 layer.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
524
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
525 HTTP requests advertise supported response formats via the ``X-HgProto-<N>``
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
526 request header, where ``<N>`` is an integer starting at 1 allowing the logical
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
527 value to span multiple headers. This value consists of a list of
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
528 space-delimited parameters. Each parameter denotes a feature or capability.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
529
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
530 The following parameters are defined:
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
531
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
532 0.1
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
533 Indicates the client supports receiving ``application/mercurial-0.1``
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
534 responses.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
535
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
536 0.2
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
537 Indicates the client supports receiving ``application/mercurial-0.2``
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
538 responses.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
539
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
540 comp
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
541 Indicates compression formats the client can decode. Value is a list of
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
542 comma delimited strings identifying compression formats ordered from
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
543 most preferential to least preferential. e.g. ``comp=zstd,zlib,none``.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
544
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
545 This parameter does not have an effect if only the ``0.1`` parameter
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
546 is defined, as support for ``application/mercurial-0.2`` or greater is
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
547 required to use arbitrary compression formats.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
548
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
549 If this parameter is not advertised, the server interprets this as
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
550 equivalent to ``zlib,none``.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
551
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
552 Clients may choose to only send this header if the ``httpmediatype``
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
553 server capability is present, as currently all server-side features
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
554 consulting this header require the client to opt in to new protocol features
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
555 advertised via the ``httpmediatype`` capability.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
556
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
557 A server that doesn't receive an ``X-HgProto-<N>`` header should infer a
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
558 value of ``0.1``. This is compatible with legacy clients.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
559
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
560 A server receiving a request indicating support for multiple media type
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
561 versions may respond with any of the supported media types. Not all servers
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
562 may support all media types on all commands.
753b9d43ca81 internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29869
diff changeset
563
29869
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
564 Commands
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
565 ========
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
566
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
567 This section contains a list of all wire protocol commands implemented by
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
568 the canonical Mercurial server.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
569
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
570 batch
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
571 -----
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
572
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
573 Issue multiple commands while sending a single command request. The purpose
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
574 of this command is to allow a client to issue multiple commands while avoiding
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
575 multiple round trips to the server therefore enabling commands to complete
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
576 quicker.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
577
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
578 The command accepts a ``cmds`` argument that contains a list of commands to
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
579 execute.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
580
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
581 The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
582 form ``<command> <arguments>``. That is, the command name followed by a space
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
583 followed by an argument string.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
584
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
585 The argument string is a ``,`` delimited list of ``<key>=<value>`` values
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
586 corresponding to command arguments. Both the argument name and value are
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
587 escaped using a special substitution map::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
588
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
589 : -> :c
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
590 , -> :o
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
591 ; -> :s
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
592 = -> :e
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
593
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
594 The response type for this command is ``string``. The value contains a
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
595 ``;`` delimited list of responses for each requested command. Each value
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
596 in this list is escaped using the same substitution map used for arguments.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
597
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
598 If an error occurs, the generic error response may be sent.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
599
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
600 between
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
601 -------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
602
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
603 (Legacy command used for discovery in old clients)
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
604
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
605 Obtain nodes between pairs of nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
606
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
607 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
608 hex node pairs. e.g.::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
609
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
610 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
611
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
612 Return type is a ``string``. Value consists of lines corresponding to each
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
613 requested range. Each line contains a space-delimited list of hex nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
614 A newline ``\n`` terminates each line, including the last one.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
615
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
616 branchmap
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
617 ---------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
618
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
619 Obtain heads in named branches.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
620
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
621 Accepts no arguments. Return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
622
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
623 Return value contains lines with URL encoded branch names followed by a space
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
624 followed by a space-delimited list of hex nodes of heads on that branch.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
625 e.g.::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
626
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
627 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
628 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
629
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
630 There is no trailing newline.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
631
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
632 branches
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
633 --------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
634
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
635 Obtain ancestor changesets of specific nodes back to a branch point.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
636
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
637 Despite the name, this command has nothing to do with Mercurial named branches.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
638 Instead, it is related to DAG branches.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
639
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
640 The command accepts a ``nodes`` argument, which is a string of space-delimited
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
641 hex nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
642
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
643 For each node requested, the server will find the first ancestor node that is
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
644 a DAG root or is a merge.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
645
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
646 Return type is a ``string``. Return value contains lines with result data for
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
647 each requested node. Each line contains space-delimited nodes followed by a
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
648 newline (``\n``). The 4 nodes reported on each line correspond to the requested
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
649 node, the ancestor node found, and its 2 parent nodes (which may be the null
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
650 node).
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
651
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
652 capabilities
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
653 ------------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
654
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
655 Obtain the capabilities string for the repo.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
656
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
657 Unlike the ``hello`` command, the capabilities string is not prefixed.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
658 There is no trailing newline.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
659
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
660 This command does not accept any arguments. Return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
661
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
662 changegroup
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
663 -----------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
664
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
665 (Legacy command: use ``getbundle`` instead)
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
666
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
667 Obtain a changegroup version 1 with data for changesets that are
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
668 descendants of client-specified changesets.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
669
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
670 The ``roots`` arguments contains a list of space-delimited hex nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
671
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
672 The server responds with a changegroup version 1 containing all
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
673 changesets between the requested root/base nodes and the repo's head nodes
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
674 at the time of the request.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
675
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
676 The return type is a ``stream``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
677
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
678 changegroupsubset
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
679 -----------------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
680
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
681 (Legacy command: use ``getbundle`` instead)
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
682
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
683 Obtain a changegroup version 1 with data for changesetsets between
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
684 client specified base and head nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
685
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
686 The ``bases`` argument contains a list of space-delimited hex nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
687 The ``heads`` argument contains a list of space-delimited hex nodes.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
688
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
689 The server responds with a changegroup version 1 containing all
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
690 changesets between the requested base and head nodes at the time of the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
691 request.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
692
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
693 The return type is a ``stream``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
694
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
695 clonebundles
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
696 ------------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
697
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
698 Obtains a manifest of bundle URLs available to seed clones.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
699
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
700 Each returned line contains a URL followed by metadata. See the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
701 documentation in the ``clonebundles`` extension for more.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
702
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
703 The return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
704
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
705 getbundle
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
706 ---------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
707
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
708 Obtain a bundle containing repository data.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
709
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
710 This command accepts the following arguments:
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
711
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
712 heads
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
713 List of space-delimited hex nodes of heads to retrieve.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
714 common
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
715 List of space-delimited hex nodes that the client has in common with the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
716 server.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
717 obsmarkers
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
718 Boolean indicating whether to include obsolescence markers as part
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
719 of the response. Only works with bundle2.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
720 bundlecaps
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
721 Comma-delimited set of strings defining client bundle capabilities.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
722 listkeys
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
723 Comma-delimited list of strings of ``pushkey`` namespaces. For each
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
724 namespace listed, a bundle2 part will be included with the content of
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
725 that namespace.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
726 cg
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
727 Boolean indicating whether changegroup data is requested.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
728 cbattempted
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
729 Boolean indicating whether the client attempted to use the *clone bundles*
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
730 feature before performing this request.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
731
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
732 The return type on success is a ``stream`` where the value is bundle.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
733 On the HTTP transport, the response is zlib compressed.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
734
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
735 If an error occurs, a generic error response can be sent.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
736
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
737 Unless the client sends a false value for the ``cg`` argument, the returned
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
738 bundle contains a changegroup with the nodes between the specified ``common``
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
739 and ``heads`` nodes. Depending on the command arguments, the type and content
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
740 of the returned bundle can vary significantly.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
741
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
742 The default behavior is for the server to send a raw changegroup version
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
743 ``01`` response.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
744
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
745 If the ``bundlecaps`` provided by the client contain a value beginning
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
746 with ``HG2``, a bundle2 will be returned. The bundle2 data may contain
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
747 additional repository data, such as ``pushkey`` namespace values.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
748
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
749 heads
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
750 -----
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
751
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
752 Returns a list of space-delimited hex nodes of repository heads followed
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
753 by a newline. e.g.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
754 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n``
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
755
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
756 This command does not accept any arguments. The return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
757
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
758 hello
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
759 -----
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
760
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
761 Returns lines describing interesting things about the server in an RFC-822
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
762 like format.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
763
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
764 Currently, the only line defines the server capabilities. It has the form::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
765
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
766 capabilities: <value>
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
767
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
768 See above for more about the capabilities string.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
769
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
770 SSH clients typically issue this command as soon as a connection is
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
771 established.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
772
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
773 This command does not accept any arguments. The return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
774
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
775 listkeys
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
776 --------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
777
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
778 List values in a specified ``pushkey`` namespace.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
779
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
780 The ``namespace`` argument defines the pushkey namespace to operate on.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
781
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
782 The return type is a ``string``. The value is an encoded dictionary of keys.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
783
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
784 Key-value pairs are delimited by newlines (``\n``). Within each line, keys and
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
785 values are separated by a tab (``\t``). Keys and values are both strings.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
786
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
787 lookup
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
788 ------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
789
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
790 Try to resolve a value to a known repository revision.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
791
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
792 The ``key`` argument is converted from bytes to an
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
793 ``encoding.localstr`` instance then passed into
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
794 ``localrepository.__getitem__`` in an attempt to resolve it.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
795
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
796 The return type is a ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
797
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
798 Upon successful resolution, returns ``1 <hex node>\n``. On failure,
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
799 returns ``0 <error string>\n``. e.g.::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
800
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
801 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
802
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
803 0 unknown revision 'foo'\n
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
804
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
805 known
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
806 -----
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
807
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
808 Determine whether multiple nodes are known.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
809
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
810 The ``nodes`` argument is a list of space-delimited hex nodes to check
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
811 for existence.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
812
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
813 The return type is ``string``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
814
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
815 Returns a string consisting of ``0``s and ``1``s indicating whether nodes
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
816 are known. If the Nth node specified in the ``nodes`` argument is known,
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
817 a ``1`` will be returned at byte offset N. If the node isn't known, ``0``
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
818 will be present at byte offset N.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
819
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
820 There is no trailing newline.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
821
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
822 pushkey
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
823 -------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
824
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
825 Set a value using the ``pushkey`` protocol.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
826
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
827 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
828 correspond to the pushkey namespace to operate on, the key within that
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
829 namespace to change, the old value (which may be empty), and the new value.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
830 All arguments are string types.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
831
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
832 The return type is a ``string``. The value depends on the transport protocol.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
833
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
834 The SSH transport sends a string encoded integer followed by a newline
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
835 (``\n``) which indicates operation result. The server may send additional
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
836 output on the ``stderr`` stream that should be displayed to the user.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
837
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
838 The HTTP transport sends a string encoded integer followed by a newline
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
839 followed by additional server output that should be displayed to the user.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
840 This may include output from hooks, etc.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
841
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
842 The integer result varies by namespace. ``0`` means an error has occurred
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
843 and there should be additional output to display to the user.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
844
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
845 stream_out
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
846 ----------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
847
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
848 Obtain *streaming clone* data.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
849
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
850 The return type is either a ``string`` or a ``stream``, depending on
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
851 whether the request was fulfilled properly.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
852
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
853 A return value of ``1\n`` indicates the server is not configured to serve
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
854 this data. If this is seen by the client, they may not have verified the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
855 ``stream`` capability is set before making the request.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
856
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
857 A return value of ``2\n`` indicates the server was unable to lock the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
858 repository to generate data.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
859
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
860 All other responses are a ``stream`` of bytes. The first line of this data
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
861 contains 2 space-delimited integers corresponding to the path count and
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
862 payload size, respectively::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
863
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
864 <path count> <payload size>\n
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
865
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
866 The ``<payload size>`` is the total size of path data: it does not include
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
867 the size of the per-path header lines.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
868
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
869 Following that header are ``<path count>`` entries. Each entry consists of a
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
870 line with metadata followed by raw revlog data. The line consists of::
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
871
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
872 <store path>\0<size>\n
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
873
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
874 The ``<store path>`` is the encoded store path of the data that follows.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
875 ``<size>`` is the amount of data for this store path/revlog that follows the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
876 newline.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
877
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
878 There is no trailer to indicate end of data. Instead, the client should stop
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
879 reading after ``<path count>`` entries are consumed.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
880
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
881 unbundle
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
882 --------
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
883
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
884 Send a bundle containing data (usually changegroup data) to the server.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
885
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
886 Accepts the argument ``heads``, which is a space-delimited list of hex nodes
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
887 corresponding to server repository heads observed by the client. This is used
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
888 to detect race conditions and abort push operations before a server performs
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
889 too much work or a client transfers too much data.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
890
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
891 The request payload consists of a bundle to be applied to the repository,
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
892 similarly to as if :hg:`unbundle` were called.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
893
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
894 In most scenarios, a special ``push response`` type is returned. This type
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
895 contains an integer describing the change in heads as a result of the
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
896 operation. A value of ``0`` indicates nothing changed. ``1`` means the number
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
897 of heads remained the same. Values ``2`` and larger indicate the number of
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
898 added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
899 indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
900 is 1 fewer head.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
901
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
902 The encoding of the ``push response`` type varies by transport.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
903
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
904 For the SSH transport, this type is composed of 2 ``string`` responses: an
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
905 empty response (``0\n``) followed by the integer result value. e.g.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
906 ``1\n2``. So the full response might be ``0\n1\n2``.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
907
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
908 For the HTTP transport, the response is a ``string`` type composed of an
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
909 integer result value followed by a newline (``\n``) followed by string
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
910 content holding server output that should be displayed on the client (output
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
911 hooks, etc).
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
912
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
913 In some cases, the server may respond with a ``bundle2`` bundle. In this
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
914 case, the response type is ``stream``. For the HTTP transport, the response
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
915 is zlib compressed.
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
916
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
917 The server may also respond with a generic error type, which contains a string
80c11c1a64bf help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29868
diff changeset
918 indicating the failure.