[PATCH 3 of 3] help: describe new cross-branch behavior in update help text, plus cleanups

[Stuart W Marks]

# HG changeset patch
# User Stuart W Marks <smarks at smarks.org>
# Date 1256870891 25200
# Node ID a3b4b243a53d5b78ee3eb6e3d701275a917ae10d
# Parent  669cf63c049aa832c67a7d5a062f55c61ffbbb2b
help: describe new cross-branch behavior in update help text, plus cleanups

diff -r 669cf63c049a -r a3b4b243a53d mercurial/commands.py
--- a/mercurial/commands.py	Thu Oct 29 19:48:11 2009 -0700
+++ b/mercurial/commands.py	Thu Oct 29 19:48:11 2009 -0700
@@ -3129,30 +3129,33 @@
     """update working directory
 
     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
+    revision.
+
+    If no revision is specified, attempt to update to the head of the
+    current branch. If this head is a descendant of the working
+    directory's parent, update to it, otherwise abort.
+
+    The following rules apply when the working directory contains
+    uncommitted changes:
+    
+    1. With neither the -c/--check nor the -C/--clean option, uncommitted
+    changes are merged into the requested revision, and the merged result
+    is left uncommitted. Updating and merging will occur only if the
+    requested revision is an ancestor or descendant of the parent
+    revision. Otherwise, the uncommitted changes are preserved
+    and the working directory is not updated.
+    
+    2. With the -c/--check option, uncommitted changes are preserved and
+    the working directory is not updated.
+    
+    3. With the -C/--clean option, uncommitted changes are discarded and
+    the working directory is updated to the requested revision.
+    
+    Use null as the revision to remove the working directory (like 'hg
     clone -U').
 
-    When the working directory contains no uncommitted changes, it
-    will be replaced by the state of the requested revision from the
-    repository. When the requested revision is on a different branch,
-    the working directory will additionally be switched to that
-    branch.
-
-    When there are uncommitted changes, use option -C/--clean to
-    discard them, forcibly replacing the state of the working
-    directory with the requested revision. Alternately, use -c/--check
-    to abort.
-
-    When there are uncommitted changes and option -C/--clean 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 you want to update just one file to an older revision, use
-    revert.
+    'hg revert'.
 
     See 'hg help dates' for a list of formats valid for -d/--date.
     """
@@ -3672,11 +3675,11 @@
          _('[-u] FILE...')),
     "^update|up|checkout|co":
         (update,
-         [('C', 'clean', None, _('overwrite locally modified files (no backup)')),
+         [('C', 'clean', None, _('discard uncommitted changes (no backup)')),
           ('c', 'check', None, _('check for uncommitted changes')),
           ('d', 'date', '', _('tipmost revision matching date')),
           ('r', 'rev', '', _('revision'))],
-         _('[-C] [-d DATE] [[-r] REV]')),
+         _('[-c] [-C] [-d DATE] [[-r] REV]')),
     "verify": (verify, []),
     "version": (version_, []),
 }