|
1 **Experimental and under active development** |
|
2 |
|
3 This section documents the wire protocol commands exposed to transports |
|
4 using the frame-based protocol. The set of commands exposed through |
|
5 these transports is distinct from the set of commands exposed to legacy |
|
6 transports. |
|
7 |
|
8 The frame-based protocol uses CBOR to encode command execution requests. |
|
9 All command arguments must be mapped to a specific or set of CBOR data |
|
10 types. |
|
11 |
|
12 The response to many commands is also CBOR. There is no common response |
|
13 format: each command defines its own response format. |
|
14 |
|
15 TODOs |
|
16 ===== |
|
17 |
|
18 * Add "node namespace" support to each command. In order to support |
|
19 SHA-1 hash transition, we want servers to be able to expose different |
|
20 "node namespaces" for the same data. Every command operating on nodes |
|
21 should specify which "node namespace" it is operating on and responses |
|
22 should encode the "node namespace" accordingly. |
|
23 |
|
24 Commands |
|
25 ======== |
|
26 |
|
27 The sections below detail all commands available to wire protocol version |
|
28 2. |
|
29 |
|
30 branchmap |
|
31 --------- |
|
32 |
|
33 Obtain heads in named branches. |
|
34 |
|
35 Receives no arguments. |
|
36 |
|
37 The response is a map with bytestring keys defining the branch name. |
|
38 Values are arrays of bytestring defining raw changeset nodes. |
|
39 |
|
40 capabilities |
|
41 ------------ |
|
42 |
|
43 Obtain the server's capabilities. |
|
44 |
|
45 Receives no arguments. |
|
46 |
|
47 This command is typically called only as part of the handshake during |
|
48 initial connection establishment. |
|
49 |
|
50 The response is a map with bytestring keys defining server information. |
|
51 |
|
52 The defined keys are: |
|
53 |
|
54 commands |
|
55 A map defining available wire protocol commands on this server. |
|
56 |
|
57 Keys in the map are the names of commands that can be invoked. Values |
|
58 are maps defining information about that command. The bytestring keys |
|
59 are: |
|
60 |
|
61 args |
|
62 (map) Describes arguments accepted by the command. |
|
63 |
|
64 Keys are bytestrings denoting the argument name. |
|
65 |
|
66 Values are maps describing the argument. The map has the following |
|
67 bytestring keys: |
|
68 |
|
69 default |
|
70 (varied) The default value for this argument if not specified. Only |
|
71 present if ``required`` is not true. |
|
72 |
|
73 required |
|
74 (boolean) Whether the argument must be specified. Failure to send |
|
75 required arguments will result in an error executing the command. |
|
76 |
|
77 type |
|
78 (bytestring) The type of the argument. e.g. ``bytes`` or ``bool``. |
|
79 |
|
80 validvalues |
|
81 (set) Values that are recognized for this argument. Some arguments |
|
82 only allow a fixed set of values to be specified. These arguments |
|
83 may advertise that set in this key. If this set is advertised and |
|
84 a value not in this set is specified, the command should result |
|
85 in error. |
|
86 |
|
87 permissions |
|
88 An array of permissions required to execute this command. |
|
89 |
|
90 * |
|
91 (various) Individual commands may define extra keys that supplement |
|
92 generic command metadata. See the command definition for more. |
|
93 |
|
94 framingmediatypes |
|
95 An array of bytestrings defining the supported framing protocol |
|
96 media types. Servers will not accept media types not in this list. |
|
97 |
|
98 pathfilterprefixes |
|
99 (set of bytestring) Matcher prefixes that are recognized when performing |
|
100 path filtering. Specifying a path filter whose type/prefix does not |
|
101 match one in this set will likely be rejected by the server. |
|
102 |
|
103 rawrepoformats |
|
104 An array of storage formats the repository is using. This set of |
|
105 requirements can be used to determine whether a client can read a |
|
106 *raw* copy of file data available. |
|
107 |
|
108 redirect |
|
109 A map declaring potential *content redirects* that may be used by this |
|
110 server. Contains the following bytestring keys: |
|
111 |
|
112 targets |
|
113 (array of maps) Potential redirect targets. Values are maps describing |
|
114 this target in more detail. Each map has the following bytestring keys: |
|
115 |
|
116 name |
|
117 (bytestring) Identifier for this target. The identifier will be used |
|
118 by clients to uniquely identify this target. |
|
119 |
|
120 protocol |
|
121 (bytestring) High-level network protocol. Values can be |
|
122 ``http``, ```https``, ``ssh``, etc. |
|
123 |
|
124 uris |
|
125 (array of bytestrings) Representative URIs for this target. |
|
126 |
|
127 snirequired (optional) |
|
128 (boolean) Indicates whether Server Name Indication is required |
|
129 to use this target. Defaults to False. |
|
130 |
|
131 tlsversions (optional) |
|
132 (array of bytestring) Indicates which TLS versions are supported by |
|
133 this target. Values are ``1.1``, ``1.2``, ``1.3``, etc. |
|
134 |
|
135 hashes |
|
136 (array of bytestring) Indicates support for hashing algorithms that are |
|
137 used to ensure content integrity. Values include ``sha1``, ``sha256``, |
|
138 etc. |
|
139 |
|
140 changesetdata |
|
141 ------------- |
|
142 |
|
143 Obtain various data related to changesets. |
|
144 |
|
145 The command accepts the following arguments: |
|
146 |
|
147 revisions |
|
148 (array of maps) Specifies revisions whose data is being requested. Each |
|
149 value in the array is a map describing revisions. See the |
|
150 *Revisions Specifiers* section below for the format of this map. |
|
151 |
|
152 Data will be sent for the union of all revisions resolved by all |
|
153 revision specifiers. |
|
154 |
|
155 Only revision specifiers operating on changeset revisions are allowed. |
|
156 |
|
157 fields |
|
158 (set of bytestring) Which data associated with changelog revisions to |
|
159 fetch. The following values are recognized: |
|
160 |
|
161 bookmarks |
|
162 Bookmarks associated with a revision. |
|
163 |
|
164 parents |
|
165 Parent revisions. |
|
166 |
|
167 phase |
|
168 The phase state of a revision. |
|
169 |
|
170 revision |
|
171 The raw, revision data for the changelog entry. The hash of this data |
|
172 will match the revision's node value. |
|
173 |
|
174 The response bytestream starts with a CBOR map describing the data that follows. |
|
175 This map has the following bytestring keys: |
|
176 |
|
177 totalitems |
|
178 (unsigned integer) Total number of changelog revisions whose data is being |
|
179 transferred. This maps to the set of revisions in the requested node |
|
180 range, not the total number of records that follow (see below for why). |
|
181 |
|
182 Following the map header is a series of 0 or more CBOR values. If values |
|
183 are present, the first value will always be a map describing a single changeset |
|
184 revision. |
|
185 |
|
186 If the ``fieldsfollowing`` key is present, the map will immediately be followed |
|
187 by N CBOR bytestring values, where N is the number of elements in |
|
188 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted |
|
189 by ``fieldsfollowing``. |
|
190 |
|
191 Following the optional bytestring field values is the next revision descriptor |
|
192 map, or end of stream. |
|
193 |
|
194 Each revision descriptor map has the following bytestring keys: |
|
195 |
|
196 node |
|
197 (bytestring) The node value for this revision. This is the SHA-1 hash of |
|
198 the raw revision data. |
|
199 |
|
200 bookmarks (optional) |
|
201 (array of bytestrings) Bookmarks attached to this revision. Only present |
|
202 if ``bookmarks`` data is being requested and the revision has bookmarks |
|
203 attached. |
|
204 |
|
205 fieldsfollowing (optional) |
|
206 (array of 2-array) Denotes what fields immediately follow this map. Each |
|
207 value is an array with 2 elements: the bytestring field name and an unsigned |
|
208 integer describing the length of the data, in bytes. |
|
209 |
|
210 If this key isn't present, no special fields will follow this map. |
|
211 |
|
212 The following fields may be present: |
|
213 |
|
214 revision |
|
215 Raw, revision data for the changelog entry. Contains a serialized form |
|
216 of the changeset data, including the author, date, commit message, set |
|
217 of changed files, manifest node, and other metadata. |
|
218 |
|
219 Only present if the ``revision`` field was requested. |
|
220 |
|
221 parents (optional) |
|
222 (array of bytestrings) The nodes representing the parent revisions of this |
|
223 revision. Only present if ``parents`` data is being requested. |
|
224 |
|
225 phase (optional) |
|
226 (bytestring) The phase that a revision is in. Recognized values are |
|
227 ``secret``, ``draft``, and ``public``. Only present if ``phase`` data |
|
228 is being requested. |
|
229 |
|
230 The set of changeset revisions emitted may not match the exact set of |
|
231 changesets requested. Furthermore, the set of keys present on each |
|
232 map may vary. This is to facilitate emitting changeset updates as well |
|
233 as new revisions. |
|
234 |
|
235 For example, if the request wants ``phase`` and ``revision`` data, |
|
236 the response may contain entries for each changeset in the common nodes |
|
237 set with the ``phase`` key and without the ``revision`` key in order |
|
238 to reflect a phase-only update. |
|
239 |
|
240 TODO support different revision selection mechanisms (e.g. non-public, specific |
|
241 revisions) |
|
242 TODO support different hash "namespaces" for revisions (e.g. sha-1 versus other) |
|
243 TODO support emitting obsolescence data |
|
244 TODO support filtering based on relevant paths (narrow clone) |
|
245 TODO support hgtagsfnodes cache / tags data |
|
246 TODO support branch heads cache |
|
247 TODO consider unify query mechanism. e.g. as an array of "query descriptors" |
|
248 rather than a set of top-level arguments that have semantics when combined. |
|
249 |
|
250 filedata |
|
251 -------- |
|
252 |
|
253 Obtain various data related to an individual tracked file. |
|
254 |
|
255 The command accepts the following arguments: |
|
256 |
|
257 fields |
|
258 (set of bytestring) Which data associated with a file to fetch. |
|
259 The following values are recognized: |
|
260 |
|
261 linknode |
|
262 The changeset node introducing this revision. |
|
263 |
|
264 parents |
|
265 Parent nodes for the revision. |
|
266 |
|
267 revision |
|
268 The raw revision data for a file. |
|
269 |
|
270 haveparents |
|
271 (bool) Whether the client has the parent revisions of all requested |
|
272 nodes. If set, the server may emit revision data as deltas against |
|
273 any parent revision. If not set, the server MUST only emit deltas for |
|
274 revisions previously emitted by this command. |
|
275 |
|
276 False is assumed in the absence of any value. |
|
277 |
|
278 nodes |
|
279 (array of bytestrings) File nodes whose data to retrieve. |
|
280 |
|
281 path |
|
282 (bytestring) Path of the tracked file whose data to retrieve. |
|
283 |
|
284 TODO allow specifying revisions via alternate means (such as from |
|
285 changeset revisions or ranges) |
|
286 |
|
287 The response bytestream starts with a CBOR map describing the data that |
|
288 follows. It has the following bytestream keys: |
|
289 |
|
290 totalitems |
|
291 (unsigned integer) Total number of file revisions whose data is |
|
292 being returned. |
|
293 |
|
294 Following the map header is a series of 0 or more CBOR values. If values |
|
295 are present, the first value will always be a map describing a single changeset |
|
296 revision. |
|
297 |
|
298 If the ``fieldsfollowing`` key is present, the map will immediately be followed |
|
299 by N CBOR bytestring values, where N is the number of elements in |
|
300 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted |
|
301 by ``fieldsfollowing``. |
|
302 |
|
303 Following the optional bytestring field values is the next revision descriptor |
|
304 map, or end of stream. |
|
305 |
|
306 Each revision descriptor map has the following bytestring keys: |
|
307 |
|
308 Each map has the following bytestring keys: |
|
309 |
|
310 node |
|
311 (bytestring) The node of the file revision whose data is represented. |
|
312 |
|
313 deltabasenode |
|
314 (bytestring) Node of the file revision the following delta is against. |
|
315 |
|
316 Only present if the ``revision`` field is requested and delta data |
|
317 follows this map. |
|
318 |
|
319 fieldsfollowing |
|
320 (array of 2-array) Denotes extra bytestring fields that following this map. |
|
321 See the documentation for ``changesetdata`` for semantics. |
|
322 |
|
323 The following named fields may be present: |
|
324 |
|
325 ``delta`` |
|
326 The delta data to use to construct the fulltext revision. |
|
327 |
|
328 Only present if the ``revision`` field is requested and a delta is |
|
329 being emitted. The ``deltabasenode`` top-level key will also be |
|
330 present if this field is being emitted. |
|
331 |
|
332 ``revision`` |
|
333 The fulltext revision data for this manifest. Only present if the |
|
334 ``revision`` field is requested and a fulltext revision is being emitted. |
|
335 |
|
336 parents |
|
337 (array of bytestring) The nodes of the parents of this file revision. |
|
338 |
|
339 Only present if the ``parents`` field is requested. |
|
340 |
|
341 When ``revision`` data is requested, the server chooses to emit either fulltext |
|
342 revision data or a delta. What the server decides can be inferred by looking |
|
343 for the presence of the ``delta`` or ``revision`` keys in the |
|
344 ``fieldsfollowing`` array. |
|
345 |
|
346 filesdata |
|
347 --------- |
|
348 |
|
349 Obtain various data related to multiple tracked files for specific changesets. |
|
350 |
|
351 This command is similar to ``filedata`` with the main difference being that |
|
352 individual requests operate on multiple file paths. This allows clients to |
|
353 request data for multiple paths by issuing a single command. |
|
354 |
|
355 The command accepts the following arguments: |
|
356 |
|
357 fields |
|
358 (set of bytestring) Which data associated with a file to fetch. |
|
359 The following values are recognized: |
|
360 |
|
361 linknode |
|
362 The changeset node introducing this revision. |
|
363 |
|
364 parents |
|
365 Parent nodes for the revision. |
|
366 |
|
367 revision |
|
368 The raw revision data for a file. |
|
369 |
|
370 haveparents |
|
371 (bool) Whether the client has the parent revisions of all requested |
|
372 nodes. |
|
373 |
|
374 pathfilter |
|
375 (map) Defines a filter that determines what file paths are relevant. |
|
376 |
|
377 See the *Path Filters* section for more. |
|
378 |
|
379 If the argument is omitted, it is assumed that all paths are relevant. |
|
380 |
|
381 revisions |
|
382 (array of maps) Specifies revisions whose data is being requested. Each value |
|
383 in the array is a map describing revisions. See the *Revisions Specifiers* |
|
384 section below for the format of this map. |
|
385 |
|
386 Data will be sent for the union of all revisions resolved by all revision |
|
387 specifiers. |
|
388 |
|
389 Only revision specifiers operating on changeset revisions are allowed. |
|
390 |
|
391 The response bytestream starts with a CBOR map describing the data that |
|
392 follows. This map has the following bytestring keys: |
|
393 |
|
394 totalpaths |
|
395 (unsigned integer) Total number of paths whose data is being transferred. |
|
396 |
|
397 totalitems |
|
398 (unsigned integer) Total number of file revisions whose data is being |
|
399 transferred. |
|
400 |
|
401 Following the map header are 0 or more sequences of CBOR values. Each sequence |
|
402 represents data for a specific tracked path. Each sequence begins with a CBOR |
|
403 map describing the file data that follows. Following that map is N CBOR values |
|
404 describing file revision data. The format of this data is identical to that |
|
405 returned by the ``filedata`` command. |
|
406 |
|
407 Each sequence's map header has the following bytestring keys: |
|
408 |
|
409 path |
|
410 (bytestring) The tracked file path whose data follows. |
|
411 |
|
412 totalitems |
|
413 (unsigned integer) Total number of file revisions whose data is being |
|
414 transferred. |
|
415 |
|
416 The ``haveparents`` argument has significant implications on the data |
|
417 transferred. |
|
418 |
|
419 When ``haveparents`` is true, the command MAY only emit data for file |
|
420 revisions introduced by the set of changeset revisions whose data is being |
|
421 requested. In other words, the command may assume that all file revisions |
|
422 for all relevant paths for ancestors of the requested changeset revisions |
|
423 are present on the receiver. |
|
424 |
|
425 When ``haveparents`` is false, the command MUST assume that the receiver |
|
426 has no file revisions data. This means that all referenced file revisions |
|
427 in the queried set of changeset revisions will be sent. |
|
428 |
|
429 TODO we want a more complicated mechanism for the client to specify which |
|
430 ancestor revisions are known. This is needed so intelligent deltas can be |
|
431 emitted and so updated linknodes can be sent if the client needs to adjust |
|
432 its linknodes for existing file nodes to older changeset revisions. |
|
433 TODO we may want to make linknodes an array so multiple changesets can be |
|
434 marked as introducing a file revision, since this can occur with e.g. hidden |
|
435 changesets. |
|
436 |
|
437 heads |
|
438 ----- |
|
439 |
|
440 Obtain DAG heads in the repository. |
|
441 |
|
442 The command accepts the following arguments: |
|
443 |
|
444 publiconly (optional) |
|
445 (boolean) If set, operate on the DAG for public phase changesets only. |
|
446 Non-public (i.e. draft) phase DAG heads will not be returned. |
|
447 |
|
448 The response is a CBOR array of bytestrings defining changeset nodes |
|
449 of DAG heads. The array can be empty if the repository is empty or no |
|
450 changesets satisfied the request. |
|
451 |
|
452 TODO consider exposing phase of heads in response |
|
453 |
|
454 known |
|
455 ----- |
|
456 |
|
457 Determine whether a series of changeset nodes is known to the server. |
|
458 |
|
459 The command accepts the following arguments: |
|
460 |
|
461 nodes |
|
462 (array of bytestrings) List of changeset nodes whose presence to |
|
463 query. |
|
464 |
|
465 The response is a bytestring where each byte contains a 0 or 1 for the |
|
466 corresponding requested node at the same index. |
|
467 |
|
468 TODO use a bit array for even more compact response |
|
469 |
|
470 listkeys |
|
471 -------- |
|
472 |
|
473 List values in a specified ``pushkey`` namespace. |
|
474 |
|
475 The command receives the following arguments: |
|
476 |
|
477 namespace |
|
478 (bytestring) Pushkey namespace to query. |
|
479 |
|
480 The response is a map with bytestring keys and values. |
|
481 |
|
482 TODO consider using binary to represent nodes in certain pushkey namespaces. |
|
483 |
|
484 lookup |
|
485 ------ |
|
486 |
|
487 Try to resolve a value to a changeset revision. |
|
488 |
|
489 Unlike ``known`` which operates on changeset nodes, lookup operates on |
|
490 node fragments and other names that a user may use. |
|
491 |
|
492 The command receives the following arguments: |
|
493 |
|
494 key |
|
495 (bytestring) Value to try to resolve. |
|
496 |
|
497 On success, returns a bytestring containing the resolved node. |
|
498 |
|
499 manifestdata |
|
500 ------------ |
|
501 |
|
502 Obtain various data related to manifests (which are lists of files in |
|
503 a revision). |
|
504 |
|
505 The command accepts the following arguments: |
|
506 |
|
507 fields |
|
508 (set of bytestring) Which data associated with manifests to fetch. |
|
509 The following values are recognized: |
|
510 |
|
511 parents |
|
512 Parent nodes for the manifest. |
|
513 |
|
514 revision |
|
515 The raw revision data for the manifest. |
|
516 |
|
517 haveparents |
|
518 (bool) Whether the client has the parent revisions of all requested |
|
519 nodes. If set, the server may emit revision data as deltas against |
|
520 any parent revision. If not set, the server MUST only emit deltas for |
|
521 revisions previously emitted by this command. |
|
522 |
|
523 False is assumed in the absence of any value. |
|
524 |
|
525 nodes |
|
526 (array of bytestring) Manifest nodes whose data to retrieve. |
|
527 |
|
528 tree |
|
529 (bytestring) Path to manifest to retrieve. The empty bytestring represents |
|
530 the root manifest. All other values represent directories/trees within |
|
531 the repository. |
|
532 |
|
533 TODO allow specifying revisions via alternate means (such as from changeset |
|
534 revisions or ranges) |
|
535 TODO consider recursive expansion of manifests (with path filtering for |
|
536 narrow use cases) |
|
537 |
|
538 The response bytestream starts with a CBOR map describing the data that |
|
539 follows. It has the following bytestring keys: |
|
540 |
|
541 totalitems |
|
542 (unsigned integer) Total number of manifest revisions whose data is |
|
543 being returned. |
|
544 |
|
545 Following the map header is a series of 0 or more CBOR values. If values |
|
546 are present, the first value will always be a map describing a single manifest |
|
547 revision. |
|
548 |
|
549 If the ``fieldsfollowing`` key is present, the map will immediately be followed |
|
550 by N CBOR bytestring values, where N is the number of elements in |
|
551 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted |
|
552 by ``fieldsfollowing``. |
|
553 |
|
554 Following the optional bytestring field values is the next revision descriptor |
|
555 map, or end of stream. |
|
556 |
|
557 Each revision descriptor map has the following bytestring keys: |
|
558 |
|
559 node |
|
560 (bytestring) The node of the manifest revision whose data is represented. |
|
561 |
|
562 deltabasenode |
|
563 (bytestring) The node that the delta representation of this revision is |
|
564 computed against. Only present if the ``revision`` field is requested and |
|
565 a delta is being emitted. |
|
566 |
|
567 fieldsfollowing |
|
568 (array of 2-array) Denotes extra bytestring fields that following this map. |
|
569 See the documentation for ``changesetdata`` for semantics. |
|
570 |
|
571 The following named fields may be present: |
|
572 |
|
573 ``delta`` |
|
574 The delta data to use to construct the fulltext revision. |
|
575 |
|
576 Only present if the ``revision`` field is requested and a delta is |
|
577 being emitted. The ``deltabasenode`` top-level key will also be |
|
578 present if this field is being emitted. |
|
579 |
|
580 ``revision`` |
|
581 The fulltext revision data for this manifest. Only present if the |
|
582 ``revision`` field is requested and a fulltext revision is being emitted. |
|
583 |
|
584 parents |
|
585 (array of bytestring) The nodes of the parents of this manifest revision. |
|
586 Only present if the ``parents`` field is requested. |
|
587 |
|
588 When ``revision`` data is requested, the server chooses to emit either fulltext |
|
589 revision data or a delta. What the server decides can be inferred by looking |
|
590 for the presence of ``delta`` or ``revision`` in the ``fieldsfollowing`` array. |
|
591 |
|
592 Servers MAY advertise the following extra fields in the capabilities |
|
593 descriptor for this command: |
|
594 |
|
595 recommendedbatchsize |
|
596 (unsigned integer) Number of revisions the server recommends as a batch |
|
597 query size. If defined, clients needing to issue multiple ``manifestdata`` |
|
598 commands to obtain needed data SHOULD construct their commands to have |
|
599 this many revisions per request. |
|
600 |
|
601 pushkey |
|
602 ------- |
|
603 |
|
604 Set a value using the ``pushkey`` protocol. |
|
605 |
|
606 The command receives the following arguments: |
|
607 |
|
608 namespace |
|
609 (bytestring) Pushkey namespace to operate on. |
|
610 key |
|
611 (bytestring) The pushkey key to set. |
|
612 old |
|
613 (bytestring) Old value for this key. |
|
614 new |
|
615 (bytestring) New value for this key. |
|
616 |
|
617 TODO consider using binary to represent nodes is certain pushkey namespaces. |
|
618 TODO better define response type and meaning. |
|
619 |
|
620 rawstorefiledata |
|
621 ---------------- |
|
622 |
|
623 Allows retrieving raw files used to store repository data. |
|
624 |
|
625 The command accepts the following arguments: |
|
626 |
|
627 files |
|
628 (array of bytestring) Describes the files that should be retrieved. |
|
629 |
|
630 The meaning of values in this array is dependent on the storage backend used |
|
631 by the server. |
|
632 |
|
633 The response bytestream starts with a CBOR map describing the data that follows. |
|
634 This map has the following bytestring keys: |
|
635 |
|
636 filecount |
|
637 (unsigned integer) Total number of files whose data is being transferred. |
|
638 |
|
639 totalsize |
|
640 (unsigned integer) Total size in bytes of files data that will be |
|
641 transferred. This is file on-disk size and not wire size. |
|
642 |
|
643 Following the map header are N file segments. Each file segment consists of a |
|
644 CBOR map followed by an indefinite length bytestring. Each map has the following |
|
645 bytestring keys: |
|
646 |
|
647 location |
|
648 (bytestring) Denotes the location in the repository where the file should be |
|
649 written. Values map to vfs instances to use for the writing. |
|
650 |
|
651 path |
|
652 (bytestring) Path of file being transferred. Path is the raw store |
|
653 path and can be any sequence of bytes that can be tracked in a Mercurial |
|
654 manifest. |
|
655 |
|
656 size |
|
657 (unsigned integer) Size of file data. This will be the final written |
|
658 file size. The total size of the data that follows the CBOR map |
|
659 will be greater due to encoding overhead of CBOR. |
|
660 |
|
661 TODO this command is woefully incomplete. If we are to move forward with a |
|
662 stream clone analog, it needs a lot more metadata around how to describe what |
|
663 files are available to retrieve, other semantics. |
|
664 |
|
665 Revision Specifiers |
|
666 =================== |
|
667 |
|
668 A *revision specifier* is a map that evaluates to a set of revisions. |
|
669 |
|
670 A *revision specifier* has a ``type`` key that defines the revision |
|
671 selection type to perform. Other keys in the map are used in a |
|
672 type-specific manner. |
|
673 |
|
674 The following types are defined: |
|
675 |
|
676 changesetexplicit |
|
677 An explicit set of enumerated changeset revisions. |
|
678 |
|
679 The ``nodes`` key MUST contain an array of full binary nodes, expressed |
|
680 as bytestrings. |
|
681 |
|
682 changesetexplicitdepth |
|
683 Like ``changesetexplicit``, but contains a ``depth`` key defining the |
|
684 unsigned integer number of ancestor revisions to also resolve. For each |
|
685 value in ``nodes``, DAG ancestors will be walked until up to N total |
|
686 revisions from that ancestry walk are present in the final resolved set. |
|
687 |
|
688 changesetdagrange |
|
689 Defines revisions via a DAG range of changesets on the changelog. |
|
690 |
|
691 The ``roots`` key MUST contain an array of full, binary node values |
|
692 representing the *root* revisions. |
|
693 |
|
694 The ``heads`` key MUST contain an array of full, binary nodes values |
|
695 representing the *head* revisions. |
|
696 |
|
697 The DAG range between ``roots`` and ``heads`` will be resolved and all |
|
698 revisions between will be used. Nodes in ``roots`` are not part of the |
|
699 resolved set. Nodes in ``heads`` are. The ``roots`` array may be empty. |
|
700 The ``heads`` array MUST be defined. |
|
701 |
|
702 Path Filters |
|
703 ============ |
|
704 |
|
705 Various commands accept a *path filter* argument that defines the set of file |
|
706 paths relevant to the request. |
|
707 |
|
708 A *path filter* is defined as a map with the bytestring keys ``include`` and |
|
709 ``exclude``. Each is an array of bytestring values. Each value defines a pattern |
|
710 rule (see :hg:`help patterns`) that is used to match file paths. |
|
711 |
|
712 A path matches the path filter if it is matched by a rule in the ``include`` |
|
713 set but doesn't match a rule in the ``exclude`` set. In other words, a path |
|
714 matcher takes the union of all ``include`` patterns and then substracts the |
|
715 union of all ``exclude`` patterns. |
|
716 |
|
717 Patterns MUST be prefixed with their pattern type. Only the following pattern |
|
718 types are allowed: ``path:``, ``rootfilesin:``. |
|
719 |
|
720 If the ``include`` key is omitted, it is assumed that all paths are |
|
721 relevant. The patterns from ``exclude`` will still be used, if defined. |
|
722 |
|
723 An example value is ``path:tests/foo``, which would match a file named |
|
724 ``tests/foo`` or a directory ``tests/foo`` and all files under it. |