Next: , Previous: Other Transports, Up: Advanced Uses


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.
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 the / character. The combination acts as database intersection (or logical and). 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 / character can be escaped using the \ character if necessary.

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 Hook Reference.

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 a 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.

For the complete source code of the hook, see Hook Reference.

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.