Re: git checkout -t -B

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 26, 2012, 18:38 UTC
Message-ID: <7v8vd1v6q2.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAHtLG6QgnvG6eYEChojY_jB25QWqxis6brbst2ff5FixFLAXAw@mail.gmail.com>

乙酸鋰 <ch3cooli@gmail.com> writes:

Show 8 quoted lines

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

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.

Thanks.