Re: git clone tag shallow

> Thibault Kruse <tibokruse@googlemail.com> writes:
>
>> Whenever a command description involves "<branch>" this can, depending
>> on the command, refer to
>> 1) a name that, when prepended with "refs/heads/", is a valid ref,
>> 2) a name that, when prepended with "refs/heads/" or "refs/tags", is a
>> valid ref,
>> 3) a name that, when prepended with "refs/[heads|tags]/", or unique in
>> "refs/remotes/*/" is a valid ref
>>
>> Now in the docu I don't see a nice distinction between 1), 2) and 3).
>> I could work on a patch if someone
>> tells me how to clearly distinguish those cases.
>
> It is _very_ true that we do not give strict distinction in many
> cases in the SYNOPSIS section.
>
> It is clear that (1) should use <branch> or even <branch-name>.
> "git checkout master" and "git checkout head/master" mean very
> different things.  The former is the "git checkout <branch-name>"
> case---checkout the named branch and prepare to grow the history of
> that branch.  The latter is "git checkout <committish>"---detach the
> HEAD at that commit, and even when the committish was named using
> the name of an existing branch (e.g. "master^0" or "heads/master"),
> prevent future commits made in that state from affecting the branch.
>
> I am not sure why you meant to treat (2) and (3) differently,
> though.  Care to elaborate?

> Outside "git checkout", we historically deliberately stayed loose in
> an attempt to help beginners by avoiding <committish> or <ref>, when
> most people are expected to feed branch names to the command and
> used <branch>.  I am not sure if it is a good idea to break such a
> white lie just to be technically more correct in the first place.