git checkout error

git checkout error

[Angelo Borsotti]

Hello,

the man page of git checkout in the synopsis does not mention the
--track and --no-track options.
However, in the description below, it states that they are allowed.
It does not say that there is a specific ordering in which they must
be specified.

If they are specified after -b, the command seems to behave as if -b
was not specified, e.g.:

$ git checkout -b --no-track topic remotes/origin/master
fatal: git checkout: updating paths is incompatible with switching branches.

while if they are specified before -b the command behaves properly, e.g.

$ git checkout --no-track -b topic remotes/origin/master
Switched to a new branch 'topic'

If this is the intended syntax, the synopsis should replace:

     git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]

by;

     git checkout [-q] [-f] [-m] [[--orphan] <new_branch>] [<start_point>]
     git checkout [-q] [-f] [-m] [ [--track|--no-track](-b|-B)
<new_branch>] [<start_point>]

-Angelo

Re: git checkout error

[Andreas Schwab]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> If they are specified after -b, the command seems to behave as if -b
> was not specified, e.g.:
>
> $ git checkout -b --no-track topic remotes/origin/master

-b requires an argument <new_branch>, which you specify as --no-track
here.  <start_point> is topic, and the rest is interpreted as <paths>.

> fatal: git checkout: updating paths is incompatible with switching branches.

This error is detected before validating <new_branch>.

> while if they are specified before -b the command behaves properly, e.g.
>
> $ git checkout --no-track -b topic remotes/origin/master
> Switched to a new branch 'topic'

You can also specify --no-track after -b (and its argument):

$ git checkout -b topic --no-track remotes/origin/master

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: git checkout error

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
>> If they are specified after -b, the command seems to behave as if -b
>> was not specified, e.g.:
>>
>> $ git checkout -b --no-track topic remotes/origin/master
>
> -b requires an argument <new_branch>, which you specify as --no-track
> here.  <start_point> is topic, and the rest is interpreted as <paths>.
>
>> fatal: git checkout: updating paths is incompatible with switching branches.
>
> This error is detected before validating <new_branch>.
>
>> while if they are specified before -b the command behaves properly, e.g.
>>
>> $ git checkout --no-track -b topic remotes/origin/master
>> Switched to a new branch 'topic'
>
> You can also specify --no-track after -b (and its argument):
>
> $ git checkout -b topic --no-track remotes/origin/master

Isn't this "asked and answered" recently with this thread?

    http://thread.gmane.org/gmane.comp.version-control.git/204397

Re: git checkout error

[Angelo Borsotti]

Hi Andreas,

>
> -b requires an argument <new_branch>, which you specify as --no-track
> here.  <start_point> is topic, and the rest is interpreted as <paths>.
>
The man page describes --track and --no-track as "options". This is why a
reader thinks that they can be specified in any order.
It is also very counter-intuitive to think that --no-track is <new_branch> and
<start_point> is topic. This is certainly not what the command does with
these data because it creates a new branch whose name is <new_branch> and not
--no-track.

I proposed a small change that clarifies the syntax, but if you prefer
to keep it obscure ...

-Angelo

Re: git checkout error

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> The man page describes --track and --no-track as "options". 

But the problem you observed is *not* about --track or --no-track.
It is about the "-b <branchname>" option.

You used the -b option that requires an argument, and as that
argument, you gave a string "--no-track", as if you wanted to create
a branch whose name is "--no-track".  After these words on the
command line are understood, there are two other arguments left on
the command line, which is an syntax error as far as "git checkout"
is concerned.

Again, this is asked-and-answered recently, and 

    http://thread.gmane.org/gmane.comp.version-control.git/204397

has resulted in a leading to b6312c2 (checkout: reorder option
handling, 2012-08-30), which is in v1.8.0-rc0 and onwards.  You
should get an error message that is a lot less confusing:

    $ git checkout -b --no-track topic remotes/origin/master
    fatal: '--no-track' is not a valid branch name.

Re: git checkout error

[Angelo Borsotti]

Junio,

giving the user a better error message is certainly an improvement.
But would not be another improvement to describe better the command syntax
so as to help the user write the command right in the first place?
After all, what is the syntax section in commands for?
If I had seen in the syntax:

     git checkout [-q] [-f] [-m] [ [--track|--no-track](-b|-B)
<new_branch>] [<start_point>]

I would have written the command correctly, and not even stumbled on a
misleading
error message.
Note that the above syntax is exactly what the command must look like.
The syntax is mostly a description of the form of command for the
user. Internally, the
implementer can use it or can even use a different one (e.g. a more
lenient one and
detect errors at the semantic level instead). But here what matters is
not how the
command is implemented, but how the user has to form it.
Why it is so difficult to convince people to make documentation better?

-Angelo

Re: git checkout error

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> Why it is so difficult to convince people to make documentation better?

It is not difficult.  The discussion on this list is usually done
via patches, and without one, constant talking is buried in other
noise and often go unnoticed.

There is however an issue about documentation consistency.  Do we
use elsewhere ( A | B | C ... ) to denote "You must write one (and
only one) among A, B, C, ..." consistently in the documentation?

An ancient discussion $gmane/72243 might be of interest to kickstart
such a documentation clean-up effort.

Re: git checkout error

[Angelo Borsotti]

Hi Junio

> It is not difficult.  The discussion on this list is usually done
> via patches, and without one, constant talking is buried in other
> noise and often go unnoticed.

Could you accept for very small changes also the simple indication of
the change itself instead of a patch?

>
> There is however an issue about documentation consistency.  Do we
> use elsewhere ( A | B | C ... ) to denote "You must write one (and
> only one) among A, B, C, ..." consistently in the documentation?

There is no standard for it. Posix provides a standard for commands:

     http://pubs.opengroup.org/onlinepubs/9699919799/

but does not mention (normal) parentheses to indicate choice.
There is one applicable standard for this, though, the ISO 14977:

     http://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf

which gives parentheses "()" the meaning of grouping (and then with "|"
inside them, the meaning of choice).
Parentheses are used in:

    - git branch
    - git commit
    - git reset
    - git remote
    - git submodule
    - git bisect
    - git grep
    - git am
    - git apply
    - git format-patch
    - git cat-file
    - git commit-tree
    - git rev-list
    - git update-index

I did not find in the documentation an explanation of the use of
parentheses, but
to me they seem to have been used consistently.

-Angelo