Re: git checkout -t -B

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



From: "Junio C Hamano" <gitster@xxxxxxxxx>
Sent: Sunday, August 26, 2012 7:38 PM
乙酸鋰 <ch3cooli@xxxxxxxxx> 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]