From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 18 Feb 2013 21:49:24 GMT
Subject: Re: git clone tag shallow
Message-ID: <7vobfh9tsr.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAByu6UVfArRXGLTKgM=nw0fzij1urcVdzxx6xdoHihODD-LtRA@mail.gmail.com>

Thibault Kruse <tibokruse@googlemail.com> 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.