[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