3.2 Selectors

Revisions can be specified on the monotone command line, precisely, by entering the entire 40-character hexadecimal SHA1 code. This can be cumbersome, so monotone also allows a more general syntax called “selectors” which is less precise but more “human friendly”. Any command which expects a precise revision ID can also accept a selector in its place; in fact a revision ID is just a special type of selector which is very precise.

Simple examples

Some selector examples are helpful in clarifying the idea:

a432

Revision IDs beginning with the string a432

graydon@pobox.com/2004-04

Revisions written by graydon@pobox.com in April 2004.

"jrh@example.org/2 weeks ago"

Revisions written by jrh@example.org 2 weeks ago.

graydon/net.venge.monotone.win32/yesterday

Revisions in the net.venge.monotone.win32 branch, written by graydon, yesterday.

A moment’s examination reveals that these specifications are “fuzzy” and indeed may return multiple values, or may be ambiguous. When ambiguity arises, monotone will inform you that more detail is required, and list various possibilities. The precise specification of selectors follows.

Selectors in detail

A selector is a combination of a selector type, which is a single ASCII character, followed by a : character and a selector string. All selectors strings except for selector type c are just values. The value is matched against identifiers or certs, depending on its type, in an attempt to match a single revision. Selectors are matched as prefixes. The current set of selection types are:

Generic cert selector

Uses selector type c. The selector string has the syntax name or name=value. The former syntax will select any revision that has a cert with that name, regardless of value; the latter will match any revision that has a cert with that name and value. Values to match for can have shell wildcards. For example, c:tag matches all revisions that have a tag, and c:tag=monotone-0.25 will match the revision tagged monotone-0.25. (See also the t selector below.)

Author selection

Uses selector type a. For example, a:graydon matches author certs where the cert value contains graydon.

Key selection

Uses selector type k. For example, k:graydon@pobox.com matches all revisions where at least one cert was signed by the key graydon@pobox.com. Instead of the key’s given name, the local name or the full hash ID of the key can be specified as well.

Branch selection

Uses selector type b. For example, b:net.venge.monotone matches branch certs where the cert value is net.venge.monotone. Values to match for can have shell wildcards. If you give a bare b: monotone will require you to be in a workspace, and will use the branch value recorded in your _MTN/options file.

Heads selection

Uses selector type h. For example, h:net.venge.monotone matches branch certs where the cert value is net.venge.monotone and the associated revision is a head revision on that branch. Values to match for can have shell wildcards like the branch selector. If you give a bare h: monotone will require you to be in a workspace, and use the branch recorded in your _MTN/options file.

Date selection

Uses selector type d. For example, d:2004-04 matches date certs where the cert value begins with 2004-04. This selector also accepts expanded date syntax (see below).

Message selection

Uses selector type m. For example m:*foobar* matches changelog and comment certs where the cert value contains the glob *foobar*.

"Earlier or equal than" selection

Uses selector type e. For example, e:2004-04-25 matches date certs where the cert value is less or equal than 2004-04-25T00:00:00. If the time component is unspecified, monotone will assume 00:00:00. This selector also accepts expanded date syntax (see below)

"Later than" selection

Uses selector type l. For example, l:2004-04-25 matches date certs where the cert value is strictly greater than 2004-04-25T00:00:00. If the time component is unspecified, monotone will assume 00:00:00. This selector also accepts expanded date syntax (see below)

Identifier selection

Uses selector type i. For example, i:0f3a matches revision IDs which begin with 0f3a.

Parent selection

Uses selector type p. For example, p:0f3a matches the revision IDs which are the parent of the revision ID which begins with 0f3a. If you give a bare p:, monotone will require you to be in a workspace, and query the parent of the base workspace revision.

Update selection

Uses selector type u. This selector must be used from within a workspace and must not have any associated value. It matches the base revision ID of the workspace before the last update command was executed. This can be useful for reviewing incoming revisions. After each update operation, or at least before the next update operation, run a command similar to the following:

$ mtn log --to u: --diffs

to log all revisions back to the last update. It can also be used for quickly jumping between two different revisions. For example, the following command:

$ mtn update -r u:

will update back to the previous update revision. Repeating this command will swap the current and previous update revision.

Tag selection

Uses selector type t. For example, t:monotone-0.11 matches tag certs where the cert value begins with monotone-0.11. Values to match for can have shell wildcards.

Workspace base revision

Uses selector type w. This selector must be used from within a workspace and must not have any associated value. It matches the base revision ID(s) this workspace is based on.

Further selector types may be added in the future.

Composite selectors

Selectors may be combined with and and or operators and parentheses, and may be modified using a function-call style syntax. The recognized special characters are /, |, ;, ( and ), and \ (forward slash, pipe, semicolon, left and right parentheses, and backslash); to use any of these characters in a selector value, precede it with a backslash (\).

The and operator is the / character. For example, the selector a:graydon/d:2004-04 can be used to select a revision which has an author cert beginning with graydon as well as a date cert beginning with 2004-04.

The or operator is the | character. For example, the selector h:some-feature-branch|h:other-feature-branch can be used to select the heads of two specific branches.

There are also several selector functions defined, which take one or more selectors as arguments. The general form for these is name '(' selector [ ';' selector ... ] ')', that is, arguments are enclosed in parentheses and separated by semicolons. These are:

difference(A;B)

Set difference; this returns all revisions selected by A but not by B. For example, difference(a:graydon;b:net.venge.monotone) would return all revisions which have an author cert beginning with graydon which are not in the branch net.venge.monotone.

not(A)

Set complement; this returns all revisions not selected by A. For example, not(c:testresult) would return all revisions which do not have any testresult certs. Conceptually not(A) is equivalent to difference(*, A), where * selects all revisions. The previous example to return all revisions which have an author cert beginning with graydon and are not in the branch net.venge.monotone, can be written as a:graydon/not(b:net.venge.monotone).

lca(A;B)

Least common ancestors; this is identical to max((ancestors(A)|A)/(ancestors(B)|B)), but it may be faster and is certainly more convenient to type. For example, lca(h:net.venge.monotone;h:net.venge.monotone.extended-selectors) would return the last propagate between the given branches, or the branch point if there were no subsequent propagates yet. This could be particularly useful with the diff command, to see exactly what has changed on a given branch.

max(A)

Erase ancestors; this returns all revisions selected by A which are not ancestors of other revisions selected by A. For example, max(b:net.venge.monotone/a:graydon) would return the latest revision(s) on branch net.venge.monotone which have an author cert beginning with graydon.

min(A)

Erase descendants; this returns all revisions selected by A which are not descendants of other revisions selected by A. For example, min(b:net.venge.monotone) would return the earliest revision(s) on branch net.venge.monotone.

ancestors(A)

Strict ancestors; returns all revisions which are an ancestor of a revision selected by A. For example, ancestors(b:net.venge.monotone) would return all revisions in branch net.venge.monotone except for the branch heads, and all revisions in branches which have been merged back into net.venge.monotone.

descendants(A)

Strict descendants; returns all revisions which are a descendant of a revision selected by A. For example, descendants(b:net.venge.monotone/a:graydon) would return all revisions which are descended from a revision which is in branch net.venge.monotone and has an author cert beginning with graydon.

parents(A)

Returns all revisions which are a parent of a revision selected by A. For example, parents(m:*foobar*) would return the parents of any revisions which have comment or changelog certs containing the word foobar.

children(A)

Returns all revisions which are a child of a revision selected by A. For example, children(m:*foobar*) would return the children of any revisions which have comment or changelog certs containing the word foobar.

pick(A)

Picks one of the revisions selected by A, and returns that. For example, h:some-branch is often used with mtn update, but will fail if some-branch has multiple heads. Using pick(h:some-branch) instead will always choose a single head, and not fail if there is more than one.

Selector expansion

Before selectors are passed to the database, they are expanded using a Lua hook: expand_selector. The default definition of this hook attempts to guess a number of common forms for selection, allowing you to omit selector types in many cases. For example, the hook guesses that the typeless selector jrh@example.org is an author selector, due to its syntactic form, so modifies it to read a:jrh@example.org. This hook will generally assign a selector type to values which “look like” partial hex strings, email addresses, branch names, or date specifications. For the complete source code of the hook, see Default hooks.

Expanding dates

All date-related selectors (d, e, l) support an English-like syntax similar to CVS. This syntax is expanded to the numeric format by the Lua hook expand_date. The allowed date formats are:

now

Expands to the current date and time.

today

Expands to today’s date. e and l selectors assume time 00:00:00

yesterday

Expands to yesterday’s date. e and l selectors assume time 00:00:00

<number> {minute|hour} <ago>

Expands to today date and time, minus the specified number of minutes|hours.

<number> {day|week|month|year} <ago>

Expands to today date, minus the specified number of days|weeks|months|years. e and l selectors assume time 00:00:00

<year>-<month>[-day[Thour:minute:second]]

Expands to the supplied year/month. The day and time component are optional. If missing, e and l selectors assume the first day of month and time 00:00:00. The time component, if supplied, must be complete to the second.

Typeless selection

If, after expansion, a selector still has no type, it is matched as a special “unknown” selector type, which will match either a tag, an author, or a branch. This costs slightly more database access, but often permits simple selection using an author’s login name and a date. For example, the selector graydon/net.venge.monotone.win32/yesterday would pass through the selector graydon as an unknown selector; so long as there are no branches or tags beginning with the string graydon this is just as effective as specifying a:graydon.