doc: git-checkout: clarify ARGUMENT DISAMBIGUATION
There's no need to use the terms "pathspec" or "tree-ish" in the ARGUMENT DISAMBIGUATION section, which are terms that (from user feedback on this page) many users do not understand. "tree-ish" is actually not accurate here: `git checkout` in this case takes a commit-ish, not a tree-ish. So we can say "branch or commit" instead of "tree-ish" which is both more accurate and uses more familiar terms. And now that the intro to the man pages mentions that `git checkout` has "two main modes", it makes sense to refer to this disambiguation section to understand how Git decides which one to use when there's an overlap in syntax. 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
ea03d5ae5cf7b256eca80634b424d3555da2cb8f
1 file changed
+14
-8
Documentation/git-checkout.adoc
+14
-8
@@ -27,6 +27,8 @@ DESCRIPTION
27
2. **Restore a different version of a file**, for example with
28
`git checkout <commit> <filename>` or `git checkout <filename>`
29
30
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
31
+
32
`git checkout [<branch>]`::
33
To prepare for working on _<branch>_, switch to it by updating
34
the index and the files in the working tree, and by pointing
@@ -513,14 +515,18 @@ $ git log -g -2 HEAD
515
ARGUMENT DISAMBIGUATION
516
-----------------------
517
516
-When there is only one argument given and it is not `--` (e.g. `git
517
-checkout abc`), and when the argument is both a valid _<tree-ish>_
518
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
519
-or a directory whose name is "abc" exists), Git would usually ask
520
-you to disambiguate. Because checking out a branch is so common an
521
-operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
522
-in such a situation. Use `git checkout -- <pathspec>` if you want
523
-to checkout these paths out of the index.
518
+When you run `git checkout <something>`, Git tries to guess whether
519
+`<something>` is intended to be a branch, a commit, or a set of file(s),
520
+and then either switches to that branch or commit, or restores the
521
+specified files.
522
+
523
+If there's any ambiguity, Git will treat `<something>` as a branch or
524
+commit, but you can use the double dash `--` to force Git to treat the
525
+parameter as a list of files and/or directories, like this:
526
+
527
+----------
528
+git checkout -- file.txt
529
+----------
530
531
EXAMPLES
532
--------