From: "Junio C Hamano" <gits...@pobox.com>
Sent: Sunday, August 26, 2012 7:38 PM
乙酸鋰 <ch3co...@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.
--
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
