checkout.txt: document a common case that ignores ambiguation rules
Normally we err on the safe side: if something can be seen as both an SHA1 and a pathspec, we stop and scream. In checkout, there is one exception added in 859fdab (git-checkout: improve error messages, detect ambiguities. - 2008-07-23), to allow the common case "git checkout branch". Let's document this exception. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Nguyễn Thái Ngọc Duy committed
Sep 7, 2016 at 18:19 UTC
19e5656345cb308ab689932d64af0858a3a92400
1 file changed
+12
Documentation/git-checkout.txt
+12
@@ -419,6 +419,18 @@ $ git reflog -2 HEAD # or
419
$ git log -g -2 HEAD
420
------------
421
422
+ARGUMENT DISAMBIGUATION
423
+-----------------------
424
+
425
+When there is only one argument given and it is not `--` (e.g. "git
426
+checkout abc"), and when the argument is both a valid `<tree-ish>`
427
+(e.g. a branch "abc" exists) and a valid `<pathspec>` (e.g. a file
428
+or a directory whose name is "abc" exists), Git would usually ask
429
+you to disambiguate. Because checking out a branch is so common an
430
+operation, however, "git checkout abc" takes "abc" as a `<tree-ish>`
431
+in such a situation. Use `git checkout -- <pathspec>` if you want
432
+to checkout these paths out of the index.
433
+
434
EXAMPLES
435
--------
436