[PATCH] help: Refine a bit the help text of "hg update"

[Giorgos Keramidas]

On Mon, 27 Oct 2008 13:38:31 -0400, Greg Ward <gerg.ward+hg at gmail.com> wrote:
> How about:
>
>     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.
>     [...]

On Tue, 28 Oct 2008 08:49:23 +0100, "Benoit Boissinot" <bboissin at gmail.com> wrote:
> On Mon, Oct 27, 2008 at 6:38 PM, Greg Ward <gerg.ward+hg at gmail.com> wrote:
>> On 27 October 2008, Kauker, Hubert said:
>>> So what?
>>> Maybe the following help text might be more user-friendly:
>
> Would it be possible to have someone send a patch for this ?
>
> (the docstring lives in mercurial/commands.py, then search for
> "def update").

Here it is.  I tried to add Greg's name and the date he posted the
original text to the list, but we can't have multiple authors per
changeset, so I had to mention'd Hubert name in the commit log.

I don't see any tests failing after the patch, so it should be
relatively safe to push to crew.

--- patch starts here ---
# HG changeset patch
# User Greg Ward <gerg.ward+hg at gmail.com>
# Date 1225129111 14400
# Node ID ef552151b65c0508560191ac141f808f0c158931
# Parent  7e963c80bbe67ee3284c451e442551196c70d512
help: Refine a bit the help text of "hg update"

Parts of the original text were submitted by Hubert Kauker (Hubert
dot Kauker at travelbasys.de).  This is a slightly revised version
of Hubert's original text.

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2862,14 +2862,21 @@
     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').
 
-    If the requested revision is a descendant of the working
-    directory, any outstanding changes in the working directory will
-    be merged into the result. If it is not directly descended but is
-    on the same named branch, update aborts with a suggestion to use
-    merge or update -C instead.
+    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.
 
-    If the requested revision is on a different named branch and the
-    working directory is clean, update quietly switches branches.
+    When there are uncommitted changes, use option -C to discard them,
+    forcibly replacing the state of the working dir with the requested
+    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 you want to update just one file to an older revision, use revert.
 
--- patch ends here ---