Next: , Up: Advanced Uses



3.1 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 value. 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:

Author selection
Uses selector type a. For example, a:graydon matches author certs where the cert value begins with graydon.
Branch selection
Uses selector type b. For example, b:net.venge matches branch certs where the cert value begins with net.venge.
Date selection
Uses selector type d. For example, d:2004-04 matches date certs where the cert value begins with 2004-04.
Identifier selection
Uses selector type i. For example, i:0f3a matches revision IDs which begin with 0f3a.
Tag selection
Uses selector type t. For example, t:monotone-0.11 matches tag certs where the cert value begins with monotone-0.11.

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.

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.

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.