Re: git clone tag shallow

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 18, 2013, 21:49 UTC
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.

Show 5 quoted lines

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