[PATCH] backout: make help more explicit about what backout does

[Gilles Moris]

On Wednesday 02 February 2011 09:10:27 am Jonathan Nieder wrote:
> # HG changeset patch
> # User Jonathan Nieder <jrnieder at gmail.com>
> # Date 1296633712 21600
> # Node ID 91804c80761f531f6b5eac52af7c8b9e6f9cd32f
> # Parent  6bf8d48bec8e1ab2e0462ce14a914d06e64f7117
> backout: make help more explicit about what backout does
>
> The help for backout explains:
>
>     The backout command merges the reverse effect of the reverted
>     changeset into the working directory.
>
> Unfortunately, that does not make it obvious to a newcomer what the
> backout command does.  Since it performs a 3-way merge, what is the
> common ancestor?  Will the result be automatically committed?  What is
> this reverted changeset --- is it the rev passed with -r on the
> command line or its inverse?
>
> So try to clarify the description, avoiding jargon and being
> explicit about what happens from the user's perspective.

Certainly needed.

>
> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -204,24 +204,20 @@
>  def backout(ui, repo, node=None, rev=None, **opts):
>      '''reverse effect of earlier changeset
>
> -    The backout command merges the reverse effect of the reverted
> -    changeset into the working directory.
> -
> -    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.
> -
> -    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.
> -
> -    Note that the default behavior (without --merge) has changed in
> -    version 1.7. To restore the previous default behavior, use
> +    Prepare a new changeset with the effect of REV undone in the
> +    current working directory.
> +
> +    If REV is the tip, then this changeset is committed automatically.
> +
> +    Otherwise, a merge was necessary, so you should inspect the result
> +    and then commit it.

Why are you switching to the past tense just here? May be:
+    Otherwise, a merge IS necessary, so you should inspect ITS result
+    and then commit it.

> +    If the --merge option is supplied, the next commit will have two
> +    parents: the old parent of the working directory and a child
> +    of REV that simply undoes REV.  Otherwise, the next commit will
> +    have one parent, maintaining a linear history.

Tentatively:
+ have JUST one parent, ...

> +
> +    Before version 1.7, the default behavior (without --merge) was
> +    different. To restore the previous default behavior, use
>
>      :hg:`backout --merge` and then :hg:`update --clean .` to get rid of
>
>      the ongoing merge.

Please feel free to discard those non English speaker comments if you think 
they don't make sense.
Anyway, this is now clearer and more compact help text.

Thanks.
Gilles.