#pragma section-numbers 2

<<Include(A:dev)>>

= Revision Context =

'''Status: Project'''

'''Main proponents:''' [[Pierre-YvesDavid]], YuyaNishihara

/!\ This is a speculative project and does not represent any firm decisions on future behavior. 

Fileset and revset might depend of revision context, there is current

== Goal ==

Various fileset (eg: `added(…)`, `modified(…)`, …) and revset (`follow(…)`, `followllines(…)`) depends of the "revision context". Currently they mostly use the working copy parent for this and sometime a revision specified to the command through another argument. We aim to provide a way to specify a wider range of revision context for them.

An example usecase would be to be able to do `hg archive --rev X 'set: rev(Y::X, modified() + added()` to archive all the file modified between Y and X at the state they are at X.

== Detailed Definition ==

There is multiple kind of eligible fileset.

=== changes-filesets ===

The one matching '''changes''' between multiple rev:

 * `added()`,
 * `clean()`,
 * `copied()`,
 * `deleted()`,
 * ''etc…''

There is multiples way to specify revision here:

 * on 1 rev: same as `hg status --change X`. the difference between this changeset and its parent,

 * between 2 revs: same as `hg status --rev X --rev Y`. the difference between the changeset, Should generalize to multiple rev?


=== property-filesets ===

The one matching a '''property''' specific to a content:

 * `binary()`,
 * `exec()`,
 * `grep(regex)`,
 * `size(…)`,
 * ''etc…''

There is multiple way to patch this:

 * files matching the property in '''any''' of this revision,

 * files matching the property in '''all''' of this revision,

=== revsets ===

In addition, some revset are also "content dependent" and need revision reference:

 * `followlines(…)`,
 * `follow(…, [startrev])`, (the startrev fits some of what we are discussion here)

It is unclear if we need to use the same approach for `fileset` and `revset` but the problem seems similar enough to be mentioned at the same time.

== Brain storming ==

Brain storming on possibilities

 * `revs(REVS, FILESET, [mode=any|all])` property matched in any (default to any),

 * `revs(REVS, FILESET, [mode=any|all])` if REVS match a single revs: works as `status --change`. if many works as `hg status --rev`, 

  * what if computed complex `REVS` happen to result in a single rev?
  `--change` and `--rev` are very different, which should be selected explicitly. -- yuya

 * `betweenrevs(ROOTS, HEADS, FILESET)` match changes between ROOTS and HEADS,

 * `anyrevs(REVS, FILESET)` property matched in any REVS,

 * `allrevs(REVS, FILESET)` property matched in all REVS,

== Proposal ==

(name are open for bikeshedding) 

 * `revs(REVS, FILESET, [match=any|all])`:

   * do ''property'' matching on all revision in `REVS`.

   * matches file that exists in ``REVS`` even if they do not exist in mainly matched context,

   * `match` argument control if a property needs to be `True` for ''any'' or ''all'' revision in REVS (default to ''any'')

   * fileset that track "changes" are treated like a property (eg: `revs(42+24, 'added()'` matches files added by `42` or `24`.

 * status(BASE, REV, FILESET):

   * do ''changes'' tracking between `BASE` and `BASE`.

   * error out if a ''property'' fileset is used ?

   * files are matches in the ctx of the head

== See Also ==

 * RevsetOperatorPlan

----
CategoryDeveloper CategoryNewFeatures