From: Julia Evans via GitGitGadget Date: Wed, 10 Sep 2025 19:14:24 GMT Subject: [PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION Message-ID: <08f0a5efab9d5dd57e1a49d00664e9453b6413f5.1757531669.git.gitgitgadget@gmail.com> In-Reply-To: From: Julia Evans 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 --- Documentation/git-checkout.adoc | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 9733c73450..d6f4044a09 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -27,6 +27,8 @@ DESCRIPTION 2. **Restore a different version of a file**, for example with `git checkout ` or `git checkout ` +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. + `git checkout []`:: To prepare for working on __, 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 __ -(e.g. a branch `abc` exists) and a valid __ (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 __ -in such a situation. Use `git checkout -- ` if you want -to checkout these paths out of the index. +When you run `git checkout `, Git tries to guess whether +`` 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 `` 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 -------- -- gitgitgadget