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.
Some selector examples are helpful in clarifying the idea:
a432
a432
graydon@pobox.com/2004-04
graydon@pobox.com
in April 2004.
'jrh@example.org/2 weeks ago'
jrh@example.org
2 weeks ago.
graydon/net.venge.monotone.win32/yesterday
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.
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:
a
. For example, a:graydon
matches
author
certs where the cert value begins with graydon
.
b
. For example, b:net.venge
matches
branch
certs where the cert value begins with net.venge
.
d
. For example, d:2004-04
matches
date
certs where the cert value begins with 2004-04
.
i
. For example, i:0f3a
matches
revision IDs which begin with 0f3a
.
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.
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
.
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.
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
.