git checkout -t -B

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

Re: git checkout -t -B

[Junio C Hamano]

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

[PATCH] doc: "git checkout -b/-B/--orphan" always takes a branch name

[Junio C Hamano]

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

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..e3270cd 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -84,11 +84,11 @@ entries; instead, unmerged entries are ignored.
 	When checking out paths from the index, check out stage #2
 	('ours') or #3 ('theirs') for unmerged paths.
 
--b::
+-b <new_branch>::
 	Create a new branch named <new_branch> and start it at
 	<start_point>; see linkgit:git-branch[1] for details.
 
--B::
+-B <new_branch>::
 	Creates the branch <new_branch> and start it at <start_point>;
 	if it already exists, then reset it to <start_point>. This is
 	equivalent to running "git branch" with "-f"; see
@@ -124,7 +124,7 @@ explicitly give a name with '-b' in such a case.
 	<commit> is not a branch name.  See the "DETACHED HEAD" section
 	below for details.
 
---orphan::
+--orphan <new_branch>::
 	Create a new 'orphan' branch, named <new_branch>, started from
 	<start_point> and switch to it.  The first commit made on this
 	new branch will have no parents and it will be the root of a new
-- 
1.7.12.252.gef4e272

Re: git checkout -t -B

[Nguyen Thai Ngoc Duy]

On Mon, Aug 27, 2012 at 1:38 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 乙酸鋰 <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.

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

Re: git checkout -t -B

[Junio C Hamano]

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

> On Mon, Aug 27, 2012 at 1:38 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> 乙酸鋰 <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.
>
> 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 '-'.

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.

Re: git checkout -t -B

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Sunday, August 26, 2012 7:38 PM
> 乙酸鋰 <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..
>    ...

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

Re: git checkout -t -B

[Junio C Hamano]

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

> I searched for all occurrences of '[[' which would indicate a double 
> optional argument within the synopsis and only found git-read-tree.

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

Re: git checkout -t -B

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Tuesday, August 28, 2012 12:22 AM
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> I searched for all occurrences of '[[' which would indicate a double
>> optional argument within the synopsis and only found git-read-tree.
>
> Double-optional?  That is not an issue.

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.

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

Agreed.

Philip