[PATCH] expand and clarify help for update

[Adrian Buehlmann]

# HG changeset patch
# User Adrian Buehlmann <adrian at cadifra.com>
# Date 1225322906 -3600
# Node ID 94bae0c425ba312c560c7cbe889554ab5bfbbd30
# Parent  1493d1e05ca3034a104afca2f49aec2783be3df6
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

patch changelog:

2008-10-30 00:25 CET:
- Inserted "(named)" in ".. the current (named) branch if no revision is
  specified" (in first para).
- Added "However, untracked files are not removed."
- Used "--" for dashes
- Removed one "thus"

2008-10-28 20:50 CET:
- Typofix: uncomitted -> uncommitted

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 (named) 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'). However, untracked files are not removed.
 
-    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 uncommitted 'hg merge' -- the update will be rejected (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 uncommitted 'hg merge', 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.
     """