[PATCH 2/3] checkout.txt: document a common case that ignores ambiguation rules

From: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Date: Sep 7, 2016, 11:19 UTC
Message-ID: <20160907111941.2342-3-pclouds@gmail.com>
In-Reply-To: <20160907111941.2342-1-pclouds@gmail.com>

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>
---
 Documentation/git-checkout.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 7a2201b..94eb238 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -419,6 +419,15 @@ $ git reflog -2 HEAD # or
 $ git log -g -2 HEAD
 ------------
 
+ARGUMENT AMBIGUATION
+--------------------
+
+When there is only one argument given and it is not `--` (e.g. "git
+checkout abc"), "abc" could be seen as either a `<tree-ish>` or a
+`<pathspec>`, but Git will assume the argument is a `<tree-ish>`, which is
+a common case for switching branches. Use `git checkout -- <pathspec>`
+form if you mean it to be a pathspec.
+
 EXAMPLES
 --------

-- 
2.8.2.524.g6ff3d78