Re: git clone tag shallow

Hi Junio,

On Mon, Feb 18, 2013 at 10:22 AM, Junio C Hamano [off-list ref] wrote:

Thibault Kruse [off-list ref] writes:

quoted

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?

As in my example, git clone --branch <branch> does not accept all of (3).

I now see that indeed the options section for git clone --branch has
been changed to inlude the information that tags are also allowed, so that's
in order.

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.

That's fair enough, I guess, I am not sure either. If I understand you
right, the Synopsis and
description are supposed to explain the non-hackish usage of commands,
whereas documentation after the OPTIONS headline is supposed to be
more of a complete description. Hence e.g. the synopsis of git-checkout
does not mention the --t,--track,--no-track options, and takes a liberal
approach to option syntaxes (listing '[-p|--patch]', but only '-m',
but not '[-m|--merge]'),
similar git-clone help does not mention the '--branch' option in the synopsis
for that reason, I guess. Do I get this right?

Does this also extend to the (bash) tab completion?
E.g. hitting tab after "git clone --", offers me (Ubuntu precise, git 1.7.9.5):
--bare           --local          --no-checkout    --origin
--reference      --template=
--depth          --mirror         --no-hardlinks   --quiet
--shared         --upload-pack

missing:
---recursive --recurse-submodules (--[no-]single-branch)
--separate-git-dir --verbose --progress --branch

Is this also intentional?

cheers,
  Thibault