142 |
142 |
143 Obtain various data related to changesets. |
143 Obtain various data related to changesets. |
144 |
144 |
145 The command accepts the following arguments: |
145 The command accepts the following arguments: |
146 |
146 |
147 noderange |
147 revisions |
148 (array of arrays of bytestrings) An array of 2 elements, each being an |
148 (array of maps) Specifies revisions whose data is being requested. Each |
149 array of node bytestrings. The first array denotes the changelog revisions |
149 value in the array is a map describing revisions. See the |
150 that are already known to the client. The second array denotes the changelog |
150 *Revisions Specifiers* section below for the format of this map. |
151 revision DAG heads to fetch. The argument essentially defines a DAG range |
151 |
152 bounded by root and head nodes to fetch. |
152 Data will be sent for the union of all revisions resolved by all |
153 |
153 revision specifiers. |
154 The roots array may be empty. The heads array must be defined. |
154 |
155 |
155 Only revision specifiers operating on changeset revisions are allowed. |
156 nodes |
|
157 (array of bytestrings) Changelog revisions to request explicitly. |
|
158 |
|
159 nodesdepth |
|
160 (unsigned integer) Number of ancestor revisions of elements in ``nodes`` |
|
161 to also fetch. When defined, for each element in ``nodes``, DAG ancestors |
|
162 will be walked until at most N total revisions are emitted. |
|
163 |
156 |
164 fields |
157 fields |
165 (set of bytestring) Which data associated with changelog revisions to |
158 (set of bytestring) Which data associated with changelog revisions to |
166 fetch. The following values are recognized: |
159 fetch. The following values are recognized: |
167 |
160 |
175 The phase state of a revision. |
168 The phase state of a revision. |
176 |
169 |
177 revision |
170 revision |
178 The raw, revision data for the changelog entry. The hash of this data |
171 The raw, revision data for the changelog entry. The hash of this data |
179 will match the revision's node value. |
172 will match the revision's node value. |
180 |
|
181 The server resolves the set of revisions relevant to the request by taking |
|
182 the union of the ``noderange`` and ``nodes`` arguments. At least one of these |
|
183 arguments must be defined. |
|
184 |
173 |
185 The response bytestream starts with a CBOR map describing the data that follows. |
174 The response bytestream starts with a CBOR map describing the data that follows. |
186 This map has the following bytestring keys: |
175 This map has the following bytestring keys: |
187 |
176 |
188 totalitems |
177 totalitems |
235 |
224 |
236 phase (optional) |
225 phase (optional) |
237 (bytestring) The phase that a revision is in. Recognized values are |
226 (bytestring) The phase that a revision is in. Recognized values are |
238 ``secret``, ``draft``, and ``public``. Only present if ``phase`` data |
227 ``secret``, ``draft``, and ``public``. Only present if ``phase`` data |
239 is being requested. |
228 is being requested. |
240 |
|
241 If nodes are requested via ``noderange``, they will be emitted in DAG order, |
|
242 parents always before children. |
|
243 |
|
244 If nodes are requested via ``nodes``, they will be emitted in requested order. |
|
245 |
|
246 Nodes from ``nodes`` are emitted before nodes from ``noderange``. |
|
247 |
229 |
248 The set of changeset revisions emitted may not match the exact set of |
230 The set of changeset revisions emitted may not match the exact set of |
249 changesets requested. Furthermore, the set of keys present on each |
231 changesets requested. Furthermore, the set of keys present on each |
250 map may vary. This is to facilitate emitting changeset updates as well |
232 map may vary. This is to facilitate emitting changeset updates as well |
251 as new revisions. |
233 as new revisions. |
538 new |
520 new |
539 (bytestring) New value for this key. |
521 (bytestring) New value for this key. |
540 |
522 |
541 TODO consider using binary to represent nodes is certain pushkey namespaces. |
523 TODO consider using binary to represent nodes is certain pushkey namespaces. |
542 TODO better define response type and meaning. |
524 TODO better define response type and meaning. |
|
525 |
|
526 Revision Specifiers |
|
527 =================== |
|
528 |
|
529 A *revision specifier* is a map that evaluates to a set of revisions. |
|
530 |
|
531 A *revision specifier* has a ``type`` key that defines the revision |
|
532 selection type to perform. Other keys in the map are used in a |
|
533 type-specific manner. |
|
534 |
|
535 The following types are defined: |
|
536 |
|
537 changesetexplicit |
|
538 An explicit set of enumerated changeset revisions. |
|
539 |
|
540 The ``nodes`` key MUST contain an array of full binary nodes, expressed |
|
541 as bytestrings. |
|
542 |
|
543 changesetexplicitdepth |
|
544 Like ``changesetexplicit``, but contains a ``depth`` key defining the |
|
545 unsigned integer number of ancestor revisions to also resolve. For each |
|
546 value in ``nodes``, DAG ancestors will be walked until up to N total |
|
547 revisions from that ancestry walk are present in the final resolved set. |
|
548 |
|
549 changesetdagrange |
|
550 Defines revisions via a DAG range of changesets on the changelog. |
|
551 |
|
552 The ``roots`` key MUST contain an array of full, binary node values |
|
553 representing the *root* revisions. |
|
554 |
|
555 The ``heads`` key MUST contain an array of full, binary nodes values |
|
556 representing the *head* revisions. |
|
557 |
|
558 The DAG range between ``roots`` and ``heads`` will be resolved and all |
|
559 revisions between will be used. Nodes in ``roots`` are not part of the |
|
560 resolved set. Nodes in ``heads`` are. The ``roots`` array may be empty. |
|
561 The ``heads`` array MUST be defined. |