git checkout error

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

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

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

This error is detected before validating <new_branch>.

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> writes:

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

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

Hi Andreas,

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

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

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.

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

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

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.

Hi Junio

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

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