[PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>`

From: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date: Sep 10, 2025, 19:14 UTC
Message-ID: <551e56dea6c5a6381f5f2e9fd81882f8104ef233.1757531669.git.gitgitgadget@gmail.com>
In-Reply-To: <pull.1962.v4.git.1757531669.gitgitgadget@gmail.com>

From: Julia Evans <julia@jvns.ca>

From user feedback: several users commented that "Local modifications to the files in the working tree are kept, so that they can be committed to the <branch>." didn't seem accurate to them, since `git checkout <branch>` will often fail.

One user also thought that "... and by pointing HEAD at the branch" was something that _they_ had to do somehow ("How do I point HEAD at a branch?") rather than a description of what the `git checkout` operation is doing for them.

Explain when `git checkout <branch>` will fail and clarify that "pointing HEAD at the branch" is part of what the command does.

6 users commented that the "You could omit <branch>..." section is extremely confusing. Explain this in a much more direct way.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index d6f4044a09..0db32b098e 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -30,11 +30,11 @@ DESCRIPTION
 See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
 
 `git checkout [<branch>]`::
-	To prepare for working on _<branch>_, switch to it by updating
-	the index and the files in the working tree, and by pointing
-	`HEAD` at the branch. Local modifications to the files in the
-	working tree are kept, so that they can be committed to the
-	_<branch>_.
+	Switch to _<branch>_. This sets the current branch to _<branch>_ and
+	updates the files in your working directory. The checkout will fail
+	if there are uncommitted changes to any files where _<branch>_ and
+	your current commit have different content. Uncommitted changes will
+	otherwise be kept.
 +
 If _<branch>_ is not found but there does exist a tracking branch in
 exactly one remote (call it _<remote>_) with a matching name and
@@ -44,10 +44,8 @@ exactly one remote (call it _<remote>_) with a matching name and
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
 +
-You could omit _<branch>_, in which case the command degenerates to
-"check out the current branch", which is a glorified no-op with
-rather expensive side-effects to show only the tracking information,
-if it exists, for the current branch.
+Running `git checkout` without specifying a branch has no effect except
+to print out the tracking information for the current branch.
 
 `git checkout (-b|-B) <new-branch> [<start-point>]`::

-- 
gitgitgadget