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.