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 <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: pclouds

Documentation/git-checkout.txt

@@ -419,6 +419,18 @@ $ git reflog -2 HEAD # or
 $ 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.
+
 EXAMPLES
 --------