From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 26 Aug 2012 18:38:45 GMT
Subject: Re: git checkout -t -B
Message-ID: <7v8vd1v6q2.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAHtLG6QgnvG6eYEChojY_jB25QWqxis6brbst2ff5FixFLAXAw@mail.gmail.com>

乙酸鋰 <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..
    ...

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.