[PATCH] backout: make help more explicit about what backout does
jrnieder at gmail.com
Wed Feb 2 02:10:27 CST 2011
# HG changeset patch
# User Jonathan Nieder <jrnieder at gmail.com>
# Date 1296633712 21600
# Node ID 91804c80761f531f6b5eac52af7c8b9e6f9cd32f
# 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.
diff --git a/mercurial/commands.py b/mercurial/commands.py
@@ -204,24 +204,20 @@
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
- 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
+ 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.
+ Otherwise, a merge was necessary, so you should inspect the result
+ and then commit it.
+ If the --merge option is supplied, the next commit will have two
+ parents: the old parent of the working directory and a child
+ of REV that simply undoes REV. Otherwise, the next commit will
+ have one parent, maintaining a linear history.
+ Before version 1.7, the default behavior (without --merge) was
+ different. To restore the previous default behavior, use
:hg:`backout --merge` and then :hg:`update --clean .` to get rid of
the ongoing merge.
More information about the Mercurial-devel