Re: [PATCH] Clarification for the command "git checkout <branch>"
Markus Elfring <Markus.Elfring@web.de> writes:
Show 7 quoted lines
>> 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
-------------
Junio C Hamano <gitster@pobox.com>