On Mon, Feb 18, 2013 at 10:22 AM, Junio C Hamano <gits...@pobox.com> wrote:
> Thibault Kruse <tibokr...@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?
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
> 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 22.214.171.124):
--bare --local --no-checkout --origin
--depth --mirror --no-hardlinks --quiet
---recursive --recurse-submodules (--[no-]single-branch)
--separate-git-dir --verbose --progress --branch
Is this also intentional?
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html