[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