The branch nvm.extended-selectors introduced so-called selector functions which enable some of the below talked use cases, such as an "lca" function with which the last branch / merge point of two branches can be selected.

The contents below are still there for the record.

---

Preface

There are a number of interesting problems and use cases where the current selector syntax isn't quite as useful as might be desirable. Various forms of "magic" selectors have been suggested. Some of these allow reasonably basic navigation of parts of the ancestry graph that don't currently have good names, others verge on the truly magical or are useful for very clever selection descriptions.

The most comprehensive original proposal can be found in the mailing list archives, together with some followups in the thread: http://lists.gnu.org/archive/html/monotone-devel/2005-09/msg00164.html

There are also various other messages where similar ideas have come up.

Apparently clearcase has something similar, and git has been developing similar notions as well -- someone should track down links to their documentation and add those here.

This page should collect ideas and template definitions for possible magic selectors. There are also some questions about how selectors should work in total, and whether selectors have any access to "context" from other parts of a compound selector. See also the Selector Syntax discussion in BranchNamingConventions.

Individual Selector Suggestions

working copy base

the version in _MTN/revision. Requires a working copy. Possible syntax: w: Usage: 'mtn diff -rw:' is equivalent to 'monotone diff' Implemented in mtn: yes, since 0.44

update target

the version(s) that 'monotone update' will take you to (maybe allow a branch as the selector value, and that means what 'monotone update -bfoo' does?)

 Requires a working copy.

 Possible syntax: u:
 Usage: 'mtn diff -rw: -ru:' prints the changes that will be applied to the working copy if 'monotone update' is run.

Implemented in mtn: yes, since 0.43

branch point

the minimal common ancestor(s) of the current version and the heads of some other branch.

 In sh:
   (mtn automate ancestors $(cat MT/revision) &&
    mtn automate heads $BRANCH | mtn automate ancestors -@-) \
   | sort | uniq -d | mtn erase_ancestors -@-

 Requires a working copy.

 Possible syntax: lca(SELECTOR;SELECTOR)
 Usage:
  'mtn diff -rlca(h:;h:net.venge.monotone)'
    -- what does this branch have that net.venge.monotone doesn't?
  'mtn diff -rlca(h:;h:net.venge.monotone) -rh:net.venge.monotone'
    -- what does net.venge.monotone have that this branch doesn't?

Implemented in mtn: yes, since 0.99

predecessor

takes a number (defaults to 1), and after evaluating the rest of the selector, replaces each selected revision with the set of revisions that are reachable by taking a length-n walk upwards from that revision.

 Possible syntax: parents(SELECTOR)

Implemented in mtn: yes, since 0.99, but without number evaluation

successor

same as predecessor, but with a downward walk.

 Possible syntax: descendants(SELECTOR)

Implemented in mtn: yes, since 0.99, but also without number evaluation

heads

after evaluating the rest of the selector, runs erase_ancestors on the set so generated.

 Possible syntax: H:
 (NB: different from non-magic "h:" which gives heads of a branch
 -- this will probably confuse people?)

Implemented in mtn: no

disambiguation

Takes a single number. When the rest of the selector does not specify a unique revision, then this can be used to pick the nth of the revisions that were narrowed down to (ordered lexicographically, say).

 Possible syntax: pick(SELECTOR)
 Usage: 'mtn diff -rfoo' <get a message saying that there are
  three revisions matching foo, with a list.  list has a number in
  front of each> 'mtn diff -rpick(foo)' (to pick the first
  item in that list)

Implemented in mtn: yes, since 0.99

initial/root revision

The root of the ancestry tree (for the current revision?)

Implemented in mtn: no

time-based?

would it be useful to have "latest of this set", "earliest of this set" selectors? obviously time is not normally very useful in our model, but perhaps it would come in handy sometimes.

Implemented in mtn: no