Commit f07b642f authored by Jonathan Nieder's avatar Jonathan Nieder
Browse files

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.

--HG--
branch : stable
parent 22167be007ed
......@@ -204,26 +204,22 @@ def archive(ui, repo, dest, **opts):
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.
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.
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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment