[Python-apps-team] Bug#611420: hg.1: description of backout command is confusing

[Jonathan Nieder]

Package: mercurial-common
Version: 1.7.3-1
Severity: minor
Tags: upstream

Hi,

The hg manpage describes "hg backout" like so:

| hg backout [OPTION]... [-r] REV
| 
| The backout command merges the reverse effect of the reverted
| changeset into the working directory.

Based on the glossary, it seems that

 - a changeset is what other version control systems call a
   revision or a commit;

 - to "merge" means to perform an rcs-style 3-way merge;

 - "working directory" does not mean what 'pwd' prints but what
   other version control systems call a checkout or working tree.

 - "reverted changeset" is not a common term.

If I had to guess, this means

	The backout command undoes the change made by the specified
	revision in the working directory.  This may result in a merge
	conflict if there have been overlapping changes since then.

The manpage elaborates:

| With the --merge option, it first commits the reverted changes
| as a new changeset.  This new changeset is a child of the reverted
| changeset.  The --merge option remembers the parent of the working
| directory before starting the backout, then merges the new head
| with that changeset afterwards.  This will result in an explicit
| merge in the history.

More jargon.  The glossary informs me that "parent of the working
directory" does not mean '..' but the last commited revision.  Ok.

I guess this means:

	One can specify the --merge option to make this merge explicit
	in history: mercurial will first commit a changeset undoing REV
	on top of REV and then prepare to commit a merge of the parent
	of the working directory with that changeset.

What if there were uncommitted changes in the working directory?

| If you backout a changeset other than the original parent of the
| working directory, the result of this merge is not committed,
| as with a normal merge.  Otherwise, no merge is needed and the
| commit is automatic.

Perhaps this means

	If REV is the parent of the working directory, there cannot
	be conflicts to resolve and the merge is committed automatically.
	Otherwise, as usual for a merge, the result of the merge is not
	committed automatically.

| Note that the default behavior (without --merge) has changed in
| version 1.7.  To restore the previous behavior, [...]

And what is the new default behavior?

Puzzled,
Jonathan