git checkout -t -B

Dear Sir,

I want to make current branch abcde a remote tracking branch with origin/abcde. Since I am working on current branch abcde, I have to use the force option. So I run

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?

Thanks, ch3cooli

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

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.

On Mon, Aug 27, 2012 at 1:38 AM, Junio C Hamano <gitster@pobox.com> wrote:

Yet it's not very clear from the error message:

    fatal: git checkout: updating paths is incompatible with switching branches.
    Did you intend to checkout 'origin/abcde' which can not be
resolved as commit?

I wonder if we should reject -t as a value of -[Bb] by adding new parseopt flag to reject values starting with '-'. In this case, branch names can't start with '-'. There may be cases where we accept option value starting with '-', but I suspect the other way is dominant.

Nguyen Thai Ngoc Duy <pclouds@gmail.com> writes:

You should be able to cope with other invalid branch names in the same codepath, but your approach would not help at all if the user said "git checkout -B q..f origin/abcde". Futzing with parseopt is not a reasonable answer to this one.

Ideally you would want

	fatal: "-t" is not an acceptable name for a branch

in this case; if it is cumbersome to arrange, at the very least, 

	updating paths is incompatible with checking out the branch "-t".

would be clearer.

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Sunday, August 26, 2012 7:38 PM

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?

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

"Philip Oakley" <philipoakley@iee.org> writes:

Double-optional?  That is not an issue.

If an option always takes a parameter, we would have

	git cmd [--option parameter]

instead of one of

	git cmd [--option]
	git cmd [--option] parameter
	git cmd [--option] parameter...

and if we had

	--option::
        	This option distims the parameter ...

that needs to be updated to

	--option parameter::
        	This option distims the parameter ...

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Tuesday, August 28, 2012 12:22 AM

For clarification, I was picking out the particular case that I saw in the git checkout syntax of an option (which necessarily starts with a first `[` ) which is actually then a multi-choice option, so has a second '[' for that, and then has the required parameter after the closing ']' of the multi-choice, then another ']' after the parameter - hence my 'double optional argument' statement.

It was the multi-choice option, with parameter case that I was looking for, as that multi-choice part would be easy to confuse with the normal list of many options.

Agreed.

Philip

While the synopsis section makes it clear that the new branch name is the parameter to these flags, the option description did not.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-checkout.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)