[PATCH v4 1/7] doc: git-checkout: clarify intro sentence

From: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date: Sep 10, 2025, 19:14 UTC
Message-ID: <4b52ffd4970d8a33065cc8dcd915623acf716b5a.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: in the first paragraph, 5 users reported not understanding the terms "pathspec" and 1 user reported not understanding the term "HEAD". Of the users who said they didn't know what "pathspec" means, 3 said they couldn't understand what the paragraph was trying to communicate as a result.

One user also commented that "If no pathspec was given..." makes `git checkout <branch>` sounds like a special edge case, instead of being one of the most common ways to use this core Git command.

It looks like the goal of this paragraph is to communicate that `git checkout` has two different modes: one where you switch branches and one where you just update your working directory files/index. So say that directly, and use more familiar language (including examples) to say it.

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

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..9733c73450 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
-Updates files in the working tree to match the version in the index
-or the specified tree.  If no pathspec was given, `git checkout` will
-also update `HEAD` to set the specified branch as the current
-branch.
+
+`git checkout` has two main modes:
+
+1. **Switch branches**, with `git checkout <branch>`
+2. **Restore a different version of a file**, for example with
+   `git checkout <commit> <filename>` or `git checkout <filename>`
 
 `git checkout [<branch>]`::
 	To prepare for working on _<branch>_, switch to it by updating

-- 
gitgitgadget