From: Philip Oakley <philipoakley@iee.org>
Date: Mon, 27 Aug 2012 23:09:44 GMT
Subject: Re: git checkout -t -B
Message-ID: <10B409063A944B298250064D2DB0BAB7@PhilipOakley>
In-Reply-To: <7v8vd1v6q2.fsf@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Sunday, August 26, 2012 7:38 PM
> 乙酸鋰 <ch3cooli@gmail.com> writes:
>
>> git checkout -t -B origin/abcde
>> works
>>
>> but
>> git checkout -B -t origin/abcde
>> does not.
>>
>> Could you document the order of parameters or fix the behaviour?
>
> It is crystal clear that -b/-B/--orphan must be followed by the name
> of the branch you are creating from the SYNOPSIS section of the
> documentation.
>
>    NAME
>    ----
>    git-checkout - Checkout a branch or paths to the working tree
>
>    SYNOPSIS
>    --------
>    [verse]
>    ...
>    'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>]
> [<st..
>    ...

I didn't find it immediately obvious, but with 6/6 hindsight it is 
clearly indicated.

However the -t option isn't listed within the synopsis, and does 
immediately follow the -b & -B in the options list which could confuse 
some readers who would stick it after the -b ;-)

Should the -t and -l options be shown in the synopsis?

>
> However, the option description can use some improvement.  It
> currently reads:
>
>    -b::
>            Create a new branch named <new_branch> and start it at
>            <start_point>; see linkgit:git-branch[1] for details.
>
> as if it and <new_branch> are freestanding arguments.
>
> I think we should describe the option like this:
>
>    -b <new_branch>::
>            Create a new branch named <new_branch> and start it at
>            <start_point>; see linkgit:git-branch[1] for details.
>
> The description for "-B" and "--orphan" options share the same
> issue.
>
> I suspect that documentation for other commands may share this
> issue.  It would be good if somebody can check the option
> description section and make sure there is no discrepancy like this
> by comparing it to the SYNOPSIS section (or "git cmd -h") for all
> manual pages.
>
> I'll patch only "git-checkout.txt" myself for now; hint, hint.

I searched for all occurrences of '[[' which would indicate a double 
optional argument within the synopsis and only found git-read-tree.

I don't think it has the same problem but I wasn't sure of the priority 
order between the '[]' and '|' selectors in the multi-choice cases.

I haven't seen anything definitive on how one should read the synopsis. 
I thought the order of some option could be exchanged, as rev-parse says 
that they can be combined (for the right commands).

>
> Thanks.
> --