kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

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>
main
Julia Evans 2025-09-10 19:14:24 +00:00 committed by Junio C Hamano
parent 21a5f9442e
commit ea03d5ae5c
1 changed files with 14 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Documentation/git-checkout.adoc
View File

@ -27,6 +27,8 @@ DESCRIPTION
2. **Restore a different version of a file**, for example with
`git checkout <commit> <filename>` or `git checkout <filename>`

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
@ -513,14 +515,18 @@ $ git log -g -2 HEAD
ARGUMENT DISAMBIGUATION
-----------------------

When there is only one argument given and it is not `--` (e.g. `git
checkout abc`), and when the argument is both a valid _<tree-ish>_
(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
or a directory whose name is "abc" exists), Git would usually ask
you to disambiguate. Because checking out a branch is so common an
operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
in such a situation. Use `git checkout -- <pathspec>` if you want
to checkout these paths out of the index.
When you run `git checkout <something>`, Git tries to guess whether
`<something>` is intended to be a branch, a commit, or a set of file(s),
and then either switches to that branch or commit, or restores the
specified files.

If there's any ambiguity, Git will treat `<something>` as a branch or
commit, but you can use the double dash `--` to force Git to treat the
parameter as a list of files and/or directories, like this:

----------
git checkout -- file.txt
----------

EXAMPLES
--------