## page was renamed from RevisionArgumentPlan
= Revision Argument Plan =

'''Main proponents:''' Martin von Zweigbergk

== Current state ==

Many commands accept a `--rev` argument. There are different categories of what they're used for, as the following sub-sections will detail.

=== Commands that default to the working copy  ===

These commands default to the working copy but allow the user to pass a `--rev` to work on a different commit. They treat the working copy the same as that other commit.

 * `hg annotate`
 * `hg branch` (experimental `--rev` support)
 * `hg files`
 * `hg grep`
 * `hg identify`
 * `hg parents` (deprecated)
 * `hg topic` (from the topic extension)

=== Commands that default to the working copy's parent  ===

These commands default to the working copy parent. Some of them allow `--rev 'wdir()'`.

 * `hg cat` (allows `--rev 'wdir()')
 * `hg phase`
 * `hg log` (kind of, it defaults to all revisions, but not including `wdir()` and `null`)
 * `hg manifest` (allows `--rev 'wdir()')
 * `hg revert`

I haven't listed `hg rebase` here, because even though it has a `--rev` option, it defaults to the `--base` option.

===  Commands that work on two commits ===

These commands use `--rev` to specify two commits, but they're used differently. That was a mistake in my opinion.

 * `hg status --rev X --rev Y`
 * `hg diff --rev X --rev Y`

=== Commands that currently work only on the working copy ===

These currently work only on the working copy.

 * `hg absorb`
 * `hg amend`
 * `hg add`
 * `hg copy`
 * `hg forget`
 * `hg rename`
 * `hg remove`
 * `hg resolve`
 * `hg uncommit`
 * `hg unamend`

=== Commands that cannot work on the working copy ===

These commands are not very interesting for the discussion, but I've added them here for completeness.

 * `hg bisect [--good|--bad]`
 * `hg bookmarks`
 * `hg bundle`
 * `hg outgoing`
 * `hg pull`
 * `hg push`
 * `hg tag`

=== Others ===

 * `hg status --change X`
   This one makes `--change X` work like regular diff for the working copy (i.e. `hg status --change 'wdir()'` is effectively the default)

== Future plans ==

The immediate plan is to teach `hg copy` a `--rev` argument that defaults to the working copy (for both usability and backwards-compatibility reasons).

We would also like to add a `--rev` argument to `hg absorb`. That would default to the working copy (again, for both usability and backwards-compatibility reasons). Note that `hg absorb` has one source revision and a set of target revisions. The user could reasonably want to specify the target revisions too. That would then be a different flag (maybe called `--into`).

Many of the other commands that currently work only on the working copy could potentially accept a `--rev` argument to work on a different commit. For example `hg amend -r X` would then become equivalent to `hg fold --rev X^ --rev X --exact`. It might be more useful with the `--interactive` flag to move part of a commit into its parent (and rewrite both commits).

For some commands that currently default to `.`, it might have been better to make them default to work on the working copy. For example, it might have been better (or not) for `hg phase` to mark the request phase in the working copy and apply it at `hg commit` time. However, we clearly cannot do that because of backwards compatibility.