Re: git clone tag shallow

Thibault Kruse [off-list ref] writes:

quoted

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.