**Experimental and under active development**
This section documents the wire protocol commands exposed to transports using the frame-based protocol. The set of commands exposed through these transports is distinct from the set of commands exposed to legacy transports.
The frame-based protocol uses CBOR to encode command execution requests. All command arguments must be mapped to a specific or set of CBOR data types.
The response to many commands is also CBOR. There is no common response format: each command defines its own response format.
The sections below detail all commands available to wire protocol version 2.
Obtain heads in named branches.
Receives no arguments.
The response is a map with bytestring keys defining the branch name. Values are arrays of bytestring defining raw changeset nodes.
Obtain the server's capabilities.
Receives no arguments.
This command is typically called only as part of the handshake during initial connection establishment.
The response is a map with bytestring keys defining server information.
The defined keys are:
Keys in the map are the names of commands that can be invoked. Values are maps defining information about that command. The bytestring keys are:
Keys are bytestrings denoting the argument name.
Values are maps describing the argument. The map has the following bytestring keys:
Obtain various data related to changesets.
The command accepts the following arguments:
Data will be sent for the union of all revisions resolved by all revision specifiers.
Only revision specifiers operating on changeset revisions are allowed.
The response bytestream starts with a CBOR map describing the data that follows. This map has the following bytestring keys:
Following the map header is a series of 0 or more CBOR values. If values are present, the first value will always be a map describing a single changeset revision.
If the "fieldsfollowing" key is present, the map will immediately be followed by N CBOR bytestring values, where N is the number of elements in "fieldsfollowing". Each bytestring value corresponds to a field denoted by "fieldsfollowing".
Following the optional bytestring field values is the next revision descriptor map, or end of stream.
Each revision descriptor map has the following bytestring keys:
If this key isn't present, no special fields will follow this map.
The following fields may be present:
Only present if the "revision" field was requested.
The set of changeset revisions emitted may not match the exact set of changesets requested. Furthermore, the set of keys present on each map may vary. This is to facilitate emitting changeset updates as well as new revisions.
For example, if the request wants "phase" and "revision" data, the response may contain entries for each changeset in the common nodes set with the "phase" key and without the "revision" key in order to reflect a phase-only update.
TODO support different revision selection mechanisms (e.g. non-public, specific revisions) TODO support different hash "namespaces" for revisions (e.g. sha-1 versus other) TODO support emitting obsolescence data TODO support filtering based on relevant paths (narrow clone) TODO support hgtagsfnodes cache / tags data TODO support branch heads cache TODO consider unify query mechanism. e.g. as an array of "query descriptors" rather than a set of top-level arguments that have semantics when combined.
Obtain various data related to an individual tracked file.
The command accepts the following arguments:
False is assumed in the absence of any value.
TODO allow specifying revisions via alternate means (such as from changeset revisions or ranges)
The response bytestream starts with a CBOR map describing the data that follows. It has the following bytestream keys:
Following the map header is a series of 0 or more CBOR values. If values are present, the first value will always be a map describing a single changeset revision.
If the "fieldsfollowing" key is present, the map will immediately be followed by N CBOR bytestring values, where N is the number of elements in "fieldsfollowing". Each bytestring value corresponds to a field denoted by "fieldsfollowing".
Following the optional bytestring field values is the next revision descriptor map, or end of stream.
Each revision descriptor map has the following bytestring keys:
Each map has the following bytestring keys:
Only present if the "revision" field is requested and delta data follows this map.
The following named fields may be present:
Only present if the "revision" field is requested and a delta is being emitted. The "deltabasenode" top-level key will also be present if this field is being emitted.
Only present if the "parents" field is requested.
When "revision" data is requested, the server chooses to emit either fulltext revision data or a delta. What the server decides can be inferred by looking for the presence of the "delta" or "revision" keys in the "fieldsfollowing" array.
Obtain various data related to multiple tracked files for specific changesets.
This command is similar to "filedata" with the main difference being that individual requests operate on multiple file paths. This allows clients to request data for multiple paths by issuing a single command.
The command accepts the following arguments:
See the *Path Filters* section for more.
If the argument is omitted, it is assumed that all paths are relevant.
Data will be sent for the union of all revisions resolved by all revision specifiers.
Only revision specifiers operating on changeset revisions are allowed.
The response bytestream starts with a CBOR map describing the data that follows. This map has the following bytestring keys:
Following the map header are 0 or more sequences of CBOR values. Each sequence represents data for a specific tracked path. Each sequence begins with a CBOR map describing the file data that follows. Following that map is N CBOR values describing file revision data. The format of this data is identical to that returned by the "filedata" command.
Each sequence's map header has the following bytestring keys:
The "haveparents" argument has significant implications on the data transferred.
When "haveparents" is true, the command MAY only emit data for file revisions introduced by the set of changeset revisions whose data is being requested. In other words, the command may assume that all file revisions for all relevant paths for ancestors of the requested changeset revisions are present on the receiver.
When "haveparents" is false, the command MUST assume that the receiver has no file revisions data. This means that all referenced file revisions in the queried set of changeset revisions will be sent.
TODO we'll probably want a more complicated mechanism for the client to specify which ancestor revisions are known. TODO we may want to make linknodes an array so multiple changesets can be marked as introducing a file revision, since this can occur with e.g. hidden changesets.
Obtain DAG heads in the repository.
The command accepts the following arguments:
The response is a CBOR array of bytestrings defining changeset nodes of DAG heads. The array can be empty if the repository is empty or no changesets satisfied the request.
TODO consider exposing phase of heads in response
Determine whether a series of changeset nodes is known to the server.
The command accepts the following arguments:
The response is a bytestring where each byte contains a 0 or 1 for the corresponding requested node at the same index.
TODO use a bit array for even more compact response
List values in a specified "pushkey" namespace.
The command receives the following arguments:
The response is a map with bytestring keys and values.
TODO consider using binary to represent nodes in certain pushkey namespaces.
Try to resolve a value to a changeset revision.
Unlike "known" which operates on changeset nodes, lookup operates on node fragments and other names that a user may use.
The command receives the following arguments:
On success, returns a bytestring containing the resolved node.
Obtain various data related to manifests (which are lists of files in a revision).
The command accepts the following arguments:
False is assumed in the absence of any value.
TODO allow specifying revisions via alternate means (such as from changeset revisions or ranges) TODO consider recursive expansion of manifests (with path filtering for narrow use cases)
The response bytestream starts with a CBOR map describing the data that follows. It has the following bytestring keys:
Following the map header is a series of 0 or more CBOR values. If values are present, the first value will always be a map describing a single manifest revision.
If the "fieldsfollowing" key is present, the map will immediately be followed by N CBOR bytestring values, where N is the number of elements in "fieldsfollowing". Each bytestring value corresponds to a field denoted by "fieldsfollowing".
Following the optional bytestring field values is the next revision descriptor map, or end of stream.
Each revision descriptor map has the following bytestring keys:
The following named fields may be present:
Only present if the "revision" field is requested and a delta is being emitted. The "deltabasenode" top-level key will also be present if this field is being emitted.
When "revision" data is requested, the server chooses to emit either fulltext revision data or a delta. What the server decides can be inferred by looking for the presence of "delta" or "revision" in the "fieldsfollowing" array.
Servers MAY advertise the following extra fields in the capabilities descriptor for this command:
Set a value using the "pushkey" protocol.
The command receives the following arguments:
TODO consider using binary to represent nodes is certain pushkey namespaces. TODO better define response type and meaning.
Allows retrieving raw files used to store repository data.
The command accepts the following arguments:
The meaning of values in this array is dependent on the storage backend used by the server.
The response bytestream starts with a CBOR map describing the data that follows. This map has the following bytestring keys:
Following the map header are N file segments. Each file segment consists of a CBOR map followed by an indefinite length bytestring. Each map has the following bytestring keys:
TODO this command is woefully incomplete. If we are to move forward with a stream clone analog, it needs a lot more metadata around how to describe what files are available to retrieve, other semantics.
A *revision specifier* is a map that evaluates to a set of revisions.
A *revision specifier* has a "type" key that defines the revision selection type to perform. Other keys in the map are used in a type-specific manner.
The following types are defined:
The "nodes" key MUST contain an array of full binary nodes, expressed as bytestrings.
The "roots" key MUST contain an array of full, binary node values representing the *root* revisions.
The "heads" key MUST contain an array of full, binary nodes values representing the *head* revisions.
The DAG range between "roots" and "heads" will be resolved and all revisions between will be used. Nodes in "roots" are not part of the resolved set. Nodes in "heads" are. The "roots" array may be empty. The "heads" array MUST be defined.
Various commands accept a *path filter* argument that defines the set of file paths relevant to the request.
A *path filter* is defined as a map with the bytestring keys "include" and "exclude". Each is an array of bytestring values. Each value defines a pattern rule (see 'hg help patterns') that is used to match file paths.
A path matches the path filter if it is matched by a rule in the "include" set but doesn't match a rule in the "exclude" set. In other words, a path matcher takes the union of all "include" patterns and then substracts the union of all "exclude" patterns.
Patterns MUST be prefixed with their pattern type. Only the following pattern types are allowed: "path:", "rootfilesin:".
If the "include" key is omitted, it is assumed that all paths are relevant. The patterns from "exclude" will still be used, if defined.
An example value is "path:tests/foo", which would match a file named "tests/foo" or a directory "tests/foo" and all files under it.