Re: git clone tag shallow

Thibault Kruse [off-list ref] 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?

And there is (4) that is not in your list.

A name that is not a local branch name (i.e. no refs/heads/$name)
and that there is only one ref that matches refs/remotes/*/$name,
such a name is special-cased in "git checkout $name".  But I do not
know it is worth giving a name to such a narrow concept that is only
used for a single hacky special case.  Whatever word you invent and
call such a name (perhaps "remote branch name"?), you would need to
repeat the first three lines of this paragraph in the description to
define that word anyway.

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.
It needs to be done with care to avoid making the resulting text
harder to approach for beginners.