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