[PATCH v2] backout: make help more explicit about what backout does
Steve Borho
steve at borho.org
Wed Feb 2 18:40:55 CST 2011
On Wed, Feb 2, 2011 at 6:24 PM, Jonathan Nieder <jrnieder at gmail.com> wrote:
> # HG changeset patch
> # User Jonathan Nieder <jrnieder at gmail.com>
> # Date 1296692409 21600
> # Node ID d2f1fa1b002f11e972c11434a8c9414ad53bd523
> # 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 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,24 @@
> 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 tip, then this changeset is committed automatically.
If REV is the current working parent, then the changeset is committed
automatically.
> + Otherwise, hg needs to merge the changes and you can inspect
> + them before committing.
> + By default, the pending changeset will have one parent,
> + maintaining a linear history.
> +
> + With --merge, the next commit will have two parents: the old
> + parent of the working directory and a child of REV that simply
> + undoes REV.
> +
> + Before version 1.7, the default behavior was equivalent to
> + specifying --merge followed by :hg:`update --clean .` to cancel
> + the merge and leave the child of REV as a head to be merged
> + separately.
>
> See :hg:`help dates` for a list of formats valid for -d/--date.
>
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel
>
--
Steve Borho
More information about the Mercurial-devel
mailing list