[PATCH] expand and clarify help for update

[Adrian Buehlmann]

# HG changeset patch
# User Adrian Buehlmann <adrian at cadifra.com>
# Date 1225212020 -3600
# Node ID 4413349bda891b3cae2a9124f4dfd54172f9c1ca
# Parent  08dc0152bb5e0d40eaa3d862a6a02e55b5e83d27
expand and clarify help for update

* use the term "working copy" more often
* stress 'hg parents'
* mention -C resetting second parent
* describe what happens on uncommitted merges

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2851,29 +2851,46 @@
     return postincoming(ui, repo, modheads, opts.get('update'), None)
 
 def update(ui, repo, node=None, rev=None, clean=False, date=None):
-    """update working directory
+    """update working copy
 
-    Update the repository's working directory to the specified revision,
-    or the tip of the current branch if none is specified. Use null as
-    the revision to remove the working copy (like 'hg clone -U').
+    Update the repository's working directory (the "working copy") to
+    the specified revision of the repository or to the tip revision of
+    the current branch if no revision is specified.
 
-    When the working dir contains no uncommitted changes, it will be
-    replaced by the state of the requested revision from the repo.  When
-    the requested revision is on a different branch, the working dir
-    will additionally be switched to that branch.
+    Specify 'null' as the requested revision to remove the entire working
+    copy (like 'hg clone -U').
 
-    When there are uncommitted changes, use option -C to discard them,
-    forcibly replacing the state of the working dir with the requested
-    revision.
+    If there are no uncommitted changes and there is no uncommitted
+    'hg merge', the working copy is replaced by the state of the
+    repository at the requested revision and the working directory's
+    (first) parent revision is set to that revision.
 
-    When there are uncommitted changes and option -C is not used, and
-    the parent revision and requested revision are on the same branch,
-    and one of them is an ancestor of the other, then the new working
-    directory will contain the requested revision merged with the
-    uncommitted changes.  Otherwise, the update will fail with a
-    suggestion to use 'merge' or 'update -C' instead.
+    If the working directory's second parent is not null - that is, after
+    an uncomitted 'hg merge' - the update will be rejected with the error
+    'abort: outstanding uncommitted merges' (if option -C was not used).
 
-    If you want to update just one file to an older revision, use revert.
+    Use 'hg parents' to show the current parent revision(s) of the working
+    directory.
+
+    If the requested revision is on a different named branch, the working
+    directory's branch name will be switched to the branch name of the
+    requested revision.
+
+    Use option -C to discard all uncommitted changes (no backups!) and
+    to discard any uncomitted 'hg merge', thus forcibly replacing the
+    working copy with the state of the repository at the requested revision
+    and resetting the working directory's second parent revision to null.
+
+    If there are uncommitted changes and option -C is not used, and
+    both the working directory's (first) parent revision and the requested
+    revision are on the same branch and one of them is an ancestor of the
+    other, the requested revision will be merged into the uncommitted
+    changes (without setting the second parent, as on 'hg merge').
+    Otherwise, the update will be rejected with a suggestion to use
+    'hg merge' or 'hg update -C' instead.
+
+    If you want to change just one file to an older revision (without
+    changing the working directory's parents), use the revert command.
 
     See 'hg help dates' for a list of formats valid for --date.
     """