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

Kevin Bullock kbullock+mercurial at ringworld.org
Thu Feb 3 13:27:24 CST 2011


On Feb 3, 2011, at 12:33 AM, Jonathan Nieder wrote:

> How about this?  Thanks for your patience.
> 
> # HG changeset patch
> # User Jonathan Nieder <jrnieder at gmail.com>
> # Date 1296714464 21600
> # Node ID ed8709d7bc21ad24d5bd6f0c6e4b18e7d44a24fc
> # 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.
> 
> Thanks to Gilles Moris, Steve Borho, Kevin Bullock, and timeless for
> help.
> 
> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -204,26 +204,26 @@
> 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
> -    :hg:`backout --merge` and then :hg:`update --clean .` to get rid of
> -    the ongoing merge.
> +    Prepare a new changeset with the effect of REV undone in the
> +    current working directory.
> +
> +    If REV is the parent of the working directory, then this changeset
> +    is committed automatically.
> +
> +    Otherwise, hg needs to merge the changes and the merged result is
> +    left uncommitted.

My sense of the style used for other help entries is that the foregoing two paragraphs should be one...

> +
> +    By default, the pending changeset will have one parent,
> +    maintaining a linear history.
> +
> +    With --merge, the pending changeset will instead have two parents:
> +    the old parent of the working directory and a child of REV that
> +    simply undoes REV.

...and likewise here. The second of each pair shows a contrast with the first, but they are talking about the same point of behavior.

pacem in terris / mir / shanti / salaam / heiwa
Kevin R. Bullock



More information about the Mercurial-devel mailing list