From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 08 Sep 2016 20:03:03 GMT
Subject: Re: [PATCH 2/3] checkout.txt: document a common case that ignores ambiguation rules
Message-ID: <xmqq7famgnwo.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160907111941.2342-3-pclouds@gmail.com>

Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:

> 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.

Good idea, but...

> +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.

... this is far from reasonable.  I'd read "but Git will assume the
argument is a tree-ish" to mean "git checkout Makefile" would
attempt to checkout the Makefile branch and fail.

    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 situation.  Use `git checkout -- <pathspec>` if you want to
    checkout these paths out of the index.

or something like that?