[PATCH/RFC] Documentation/checkout: explain behavior wrt local changes

[Jonathan Nieder <jrnieder@gmail.com>]

Jonathan Nieder wrote:

> Proposed clearer text would be welcome, especially if in the form of
> a patch to Documentation/git-checkout.txt (see Documentation/SubmittingPatches).

Like this, maybe?

-- 8< --
Subject: Documentation/checkout: explain behavior wrt local changes

The current start of the description to "git checkout" tries to
combine an explanation of "git checkout <branch> --" with "git
checkout -- <paths>" and ends up with a muddle (as Jeff noticed).

In particular, the text does not make it obvious that the "git
checkout <branch> --" form does not clobber local changes relative
to the HEAD commit in the worktree and index.

Reported-by: r.ductor <r.ductor@gmail.com>
Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
I somehow suspect that a mention of --merge would make this clearer
but good words for it aren't coming at the moment.  Improvements
welcome.

 Documentation/git-checkout.txt |   14 ++++++++------
 1 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 22d3611..cfb71a8 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -15,16 +15,18 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Updates files in the working tree to match the version in the index
-or the specified tree.  If no paths are given, 'git checkout' will
-also update `HEAD` to set the specified branch as the current
-branch.
+There are two different modes -- one to switch branches and one to
+make some paths in the work tree match the index or specified tree.
 
 'git checkout' [<branch>]::
 'git checkout' -b|-B <new_branch> [<start point>]::
 
-	This form switches branches by updating the index, working
-	tree, and HEAD to reflect the specified branch.
+	This form switches branches by changing `HEAD` and updating the
+	tracked files to the specified branch.  'git checkout' will
+	stop without doing anything if local changes overlap with
+	changes to the tracked files.  (Any local changes that do not
+	overlap with changes from `HEAD` to the specified branch will
+	be preserved.)
 +
 If `-b` is given, a new branch is created as if linkgit:git-branch[1]
 were called and then checked out; in this case you can
-- 
1.7.4.rc1