Thibault Kruse <tibokruse@xxxxxxxxxxxxxx> writes:
>> 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).
That is a prime example of outside "checkout" we give a white lie to
show the most common <branch> to help beginners, I think.
> 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.
It would go more like
SYNOPSIS
git foo <branch>
DESCRIPTION
"git foo" distims doshes in <branch>.
ARGUMENTS
* <branch>: the branch to distim doshes in.
While it is most common to name a branch, you
can give any <committ-ish> to it.
if and only if use is <branch> is the most common and using
arbitrary commit is a rare case. In other cases, we would be better
to say <committish> on the SYNOPSIS part. That commonness/rareness
is a case-by-case matter, I would think.
--
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