@matheusbsbs / matheus-bagliano / commits / 21a5f9442e

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 <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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Julia Evans committed Sep 10, 2025 at 19:14 UTC 21a5f9442e3a9640c46d3bc28b41a7238bb4ee9c

1 file changed +6 -4

Documentation/git-checkout.adoc

+6 -4

@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]

21 DESCRIPTION

22 -----------

23 -Updates files in the working tree to match the version in the index

24 -or the specified tree. If no pathspec was given, `git checkout` will

25 -also update `HEAD` to set the specified branch as the current

26 -branch.

23 +

24 +`git checkout` has two main modes:

25 +

26 +1. **Switch branches**, with `git checkout <branch>`

27 +2. **Restore a different version of a file**, for example with

28 + `git checkout <commit> <filename>` or `git checkout <filename>`

30 `git checkout [<branch>]`::

31 To prepare for working on _<branch>_, switch to it by updating