Re: [PATCH] Clarification for the command "git checkout <branch>"

[Junio C Hamano <gitster@pobox.com>]

Markus Elfring <Markus.Elfring@web.de> writes:

>> I find that the discussion is not finished yet. It was not achieved a common
>> conclusion and consensus on all mentioned details so far.
>
> Can we achieve progress for an update of the manual?
>
> Regards,
> Markus

Something like this?

 Documentation/git-checkout.txt |   27 ++++++++++++++++++++++++---
 1 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 37c1810..d443a12 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -16,9 +16,9 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-When <paths> are not given, this command switches branches by
-updating the index, working tree, and HEAD to reflect the specified
-branch.
+When <paths> are not given, this command makes the named branch the
+current branch, so that a further work will be committed on that branch.
+See "Switching Branches" below.
 
 If `-b` is given, a new branch is created and checked out, as if
 linkgit:git-branch[1] were called; in this case you can
@@ -149,6 +149,27 @@ checks out the branch (instead of detaching).  You may also specify
 	the index will be used.
 
 
+Switching Branches
+------------------
+
+While switching to another branch (or more in general, to another commit
+that is not the current commit), the index and the working tree are
+updated to the contents of the new branch, while carrying the uncommitted
+changes you made so far along with you.  People often start making changes
+and then realize that the changes belong to a branch that is different
+from the current one, and it helps these people to carry the changes
+forward upon switching branches.
+
+If the branch you are switching to has one version of a file, and the
+current branch has a different version of it, which you changed in your
+working tree to yet another version, carrying the changes forward is not
+possible without merging.  But you may not be ready to resolve such
+conflicts right now.  By default, the command refuses to switch branches
+to prevent you from losing your local changes due to such conflicts.  In
+such a case, you may want retry the command after recording the local
+changes (1) in a temporary commit on the current branch, or (2) by using
+"git stash".  Alternatively, use "-m" option to force a merge.
+
 
 Detached HEAD
 -------------