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
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:
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.)
a
. For example, a:graydon
matches
author
certs where the cert value contains graydon
.
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.
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.
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).
m
. For example m:*foobar*
matches
changelog
and comment
certs where the cert value
contains the glob *foobar*
.
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)
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)
i
. For example, i:0f3a
matches
revision IDs which begin with 0f3a
.
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.
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.
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.
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.
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.
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.
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
today
e
and l
selectors assume time 00:00:00
yesterday
e
and l
selectors assume
time 00:00:00
<number> {minute|hour} <ago>
number
of
minutes|hours.
<number> {day|week|month|year} <ago>
number
of
days|weeks|months|years. e
and l
selectors assume time
00:00:00
<year>-<month>[-day[Thour:minute:second]]
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.
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
.