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