From 21a5f9442e3a9640c46d3bc28b41a7238bb4ee9c Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 10 Sep 2025 19:14:23 +0000 Subject: [PATCH] doc: git-checkout: clarify intro sentence 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 ` 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 Signed-off-by: Junio C Hamano --- 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 ff1cb29bc1..e0910bb59d 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -20,10 +20,12 @@ git checkout (-p|--patch) [] [--] [...] 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 ` +2. **Restore a different version of a file**, for example with + `git checkout ` or `git checkout ` `git checkout []`:: To prepare for working on __, switch to it by updating -- 2.47.3