# # # patch "wiki/MagicSelectors.mdwn" # from [c32e925331bd8b7e91d9dd1ab418e14a293cce7e] # to [0202cd2584124449ed0a3d4207725e4d5bb0fe3e] # # patch "wiki/RoadMap.mdwn" # from [3e142fa6fe38fecf40f2d36bcb38544a817513af] # to [46a4e07ef51eeab42d6d48bfdd8473e582dc8bbc] # ============================================================ --- wiki/MagicSelectors.mdwn c32e925331bd8b7e91d9dd1ab418e14a293cce7e +++ wiki/MagicSelectors.mdwn 0202cd2584124449ed0a3d4207725e4d5bb0fe3e @@ -1,117 +1,141 @@ [[!tag migration-done]] -[[!toc levels=2]] -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 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 most comprehensive original proposal can be found in the mailing list archives, together with some followups in the thread: +The contents below are still there for the record. -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. +[[!toc levels=2]] -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]]. +# 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. -# Selector Naming Styles +The most comprehensive original proposal can be found in the mailing list +archives, together with some followups in the thread: + -## Capital Letters +There are also various other messages where similar ideas have come up. -Let's make them all CAPITALIZED -because 1) they're all sort of "magic", and that marks them off from -the point of view of users. 2) we're running out of letters and this -lets us reuse some :-). +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. -Examples: B: (base), A: (ancestor) +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]]. -## m: for magic -m: is the magical selector, that accesses named revisions by smarter, dynamic, possibly context-sensitive names as the selector value. Gives a wider, and perhaps more mnemonic, form, with the potential for further syntax confusion if these need to take values of their own as arguments. At least some of these names could be used plain, with the m: inserted in the same way as others by the selector guessing hook in the same way as email addresses and dates are. - -Examples: m:HEAD, m:BASE, m:ANCESTOR, m:LEFT-ANCESTOR, m:LAST-PROPAGATE - - # Individual Selector Suggestions -## working copy base +## working copy base -the version in MT/revision. Requires a working copy. - Possible letters: B? - Usage: 'monotone diff -rB:' is equivalent to 'monotone diff' +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 +## 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?) +means what 'monotone update -bfoo' does?) Requires a working copy. - possible letters: U? - usage: 'monotone diff -rB: -rU:' prints the changes that will be - applied to the working copy if 'monotone update' is run. + Possible syntax: u: + Usage: 'mtn diff -rw: -ru:' prints the changes that will be applied to the working copy if 'monotone update' is run. -## branch point +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. +and the heads of some other branch. In sh: - (monotone automate ancestors $(cat MT/revision) && - monotone automate heads $BRANCH | monotone automate ancestors address@hidden) \ - | sort | uniq -d | monotone erase_ancestors address@hidden - Requires a working copy. - possible letters: B? ("branch"), S? ("split") - usage: - 'monotone diff -rS:net.venge.monotone' + (mtn automate ancestors $(cat MT/revision) && + mtn automate heads $BRANCH | mtn automate ancestors address@hidden) \ + | sort | uniq -d | mtn erase_ancestors address@hidden + + 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? - 'monotone diff -rS:net.venge.monotone -rh:net.venge.monotone' + 'mtn diff -rlca(h:;h:net.venge.monotone) -rh:net.venge.monotone' -- what does net.venge.monotone have that this branch doesn't? -## predecessor +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 letters: P? ("predecessor", "parent") A? ("ancestor") -## successor + 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 letters: S? C? ("child"), D? ("descendent") -## heads + 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 letters: H? + + Possible syntax: H: (NB: different from non-magic "h:" which gives heads of a branch -- this will probably confuse people?) -## disambiguation +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 letters: N? D? - usage: 'monotone diff -rfoo' 'monotone diff -rfoo/N:2' (to pick the second + front of each> 'mtn diff -rpick(foo)' (to pick the first item in that list) - usage: 'monotone update' ' to pick from - following list:> -## initial/root revision +Implemented in mtn: yes, since 0.99 +## initial/root revision + The root of the ancestry tree (for the current revision?) -## time-based? +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. -# Selector Behaviour +Implemented in mtn: no + ============================================================ --- wiki/RoadMap.mdwn 3e142fa6fe38fecf40f2d36bcb38544a817513af +++ wiki/RoadMap.mdwn 46a4e07ef51eeab42d6d48bfdd8473e582dc8bbc @@ -5,8 +5,8 @@ Description | More Info | Branch(es) | S [[!table data=""" Description | More Info | Branch(es) | Status | +Extended selectors | [[MagicSelectors]] | `nvm.extended-selectors` | merged | Netsync URI refactoring | n/a | `nvm.connection_info_cleanup` | in development | -Extended selectors | [[MagicSelectors]] | `nvm.extended-selectors` | in development | netsync --anonymous | n/a | `nvm.bugfest-2010.28805-rlevitte` | in development | Fix `rename foo foo` | n/a | `nvm.bugfest-2010.29484-rlevitte` | in development | `kill_certs_locally` | n/a | `nvm.kill_certs_locally` | in development |