##// END OF EJS Templates
upstream » mercurial-mirror
RSS

Clone from https://www.mercurial-scm.org/repo/hg-all

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