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

[Javi Merino]

tags 611420 wontfix
thanks

On 29/01/11 05:13, Jonathan Nieder wrote:
> 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;

changeset is also popular in version control systems. At least svn and
bitkeeper also talk about changesets. Trac also call changeset what
other call commit. Besides, the whole mercurial documentation talks
about changesets, it's not just the backout command.

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

Yes

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

git also considers working directory to be "the directory that holds the
current checkout of the files you are working on"

[0] http://book.git-scm.com/1_git_directory_and_working_directory.html

>  - "reverted changeset" is not a common term.

Revert is also used in git with the same meaning.

> 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.

Maybe this is better worded than the backout description, but I don't
really see what is wrong with the original one. Propose your change in
mercurial-devel at selenic.com and discuss it there, but I think
"changeset", "merge" and "revert" are common concepts of VCSs, hence
tagging this bug wontfix.

Regards,
Javi (Vicho)

> 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
> 
> 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 262 bytes
Desc: OpenPGP digital signature
URL: <http://lists.alioth.debian.org/pipermail/python-apps-team/attachments/20110201/d7d8a194/attachment-0001.pgp>