Hi Junio, On Mon, Feb 18, 2013 at 10:22 AM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Thibault Kruse <tibokruse@xxxxxxxxxxxxxx> 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 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html