3.12 Reserved Certs

Every certificate has a name. Some names have meaning which is built in to monotone, others may be used for customization by a particular user, site, or community. If you wish to define custom certificates, you should prefix such certificate names with x-. For example, if you want to make a certificate describing the existence of security vulnerabilities in a revision, you might wish to create a certificate called x-vulnerability. Monotone reserves all names which do not begin with x- for possible internal use. If an x- certificate becomes widely used, monotone will likely adopt it as a reserved cert name and standardize its semantics.

Most reserved certificate names have no meaning yet; some do. Usually monotone is also responsible for generating many of these certs as part of normal operation, such as during a commit. Others will be added explicitly via other commands, like tag or approve.

As well as carrying other information, certs (and combinations of certs) are useful for identifying revisions with Selectors; in particular, this is the primary purpose of the tag cert.

The pre-defined, reserved certificate names are:

author

This cert’s value is the name of a person who committed the revision the cert is attached to. The cert is generated when you commit a revision. It is displayed by the log command.

branch

This cert’s value is the name of a branch. A branch cert associates a revision with a branch. The revision is said to be “in the branch” named by the cert. The cert is generated when you commit a revision, either directly with the commit command or indirectly with the merge or propagate commands. The branch certs are read and directly interpreted by many monotone commands, and play a fundamental role in organizing work in any monotone database.

changelog

This cert’s value is the change log message you provide when you commit a revision. It is displayed by the log command.

comment

This cert’s value is an additional comment, usually provided after committing, about a revision. Certs with the name comment will be shown together with changelog certs by the log command.

date

This cert’s value is an ISO date string indicating the time at which a revision was committed. It is displayed by the log command, and may be used as an additional heuristic or selection criterion in other commands in the future.

suspend

This cert’s value is the name of a branch (see the branch cert). This cert is generated by the suspend command. A suspended revision is removed from the list of head revisions of a branch in most cases. A branch with all its heads suspended will not appear in the list of branches. Suspended revisions can still have children, and those children are in no way affected by the suspend cert on their parent.

tag

This cert’s value is a symbolic name given to a revision, which may be used as a way of selecting the revision by name for later commands like checkout, log or diff.

testresult

This cert’s value is interpreted as a boolean string, either 0 or 1. It is generated by the testresult command and represents the results of running a particular test on the underlying revision. Typically you will make a separate signing key for each test you intend to run on revisions. This cert influences the update algorithm.