Confusing error message for git switch -d

Confusing error message for git switch -d

[Anselm Schüler]

Hi,

I just ran into a confusing error message when using git switch -d, 
specifically in a clone of the CPython code repository.

I wanted to get the code for CPython 3.12, so I tried running git switch 
-d 3.12, expecting 3.12 to be a tag (which it wasn’t, and it was a 
remote branch).

Git produced this error message:

fatal: '--detach' cannot be used with '-b/-B/--orphan'

This is confusing since I didn’t pass any of these options.

I believe I have determined that this error message occurs when using 
git switch -d to switch to a remote branch that hasn’t yet had a local 
branch that tracks it created for it.

Why is Git producing this error specifically?
It also seems that, whatever the reason, a user probably doesn’t know, 
so a better error message might be a good idea.

To clarify, if I’d known that my assumption of it being a tag was wrong, 
I’d’ve still expected Git to act differently, specifically, it could’ve 
switched to the commit the branch is pointing to in detached HEAD mode 
(as it does when using -d with other branches).

Thanks
Anselm

PS: Are there no mailing list servers that support HTML messages? Why 
are they not allowed, even with plaintext fallback?

Re: Confusing error message for git switch -d

[Junio C Hamano]

Anselm Schüler <mail@anselmschueler.com> writes:

> I wanted to get the code for CPython 3.12, so I tried running git
> switch -d 3.12, expecting 3.12 to be a tag (which it wasn’t, and it
> was a remote branch).
>
> Git produced this error message:
>
> fatal: '--detach' cannot be used with '-b/-B/--orphan'
>
> This is confusing since I didn’t pass any of these options.

True.  FWIW, this is shared between "checkout" and "switch', and I
agree that there is a huge room for improvement.

With (arguably overly aggressive for its own worth) the "--guess"
option being default, giving the name of a unique remote-tracking
branch (that is, "3.12" appears as a remote-tracking branch of only
one remote, among possibly multiple remotes you have defined for the
repository) would behave as if what you said, which is "3.12", is
equivalent to "-b 3.12 --track origin/3.12" (where the "origin"
thing is the "only one" remote for which 3.12 exists as a
remote-tracking branch).  So

    $ git switch --detach 3.12

behaves as if you said

    $ git switch --detach -b 3.12 --track origin/3.12

and the error message is given.

I am merely saying that the mechanism from which this error message
is given can be _explained_.  I do not think it is well designed, as
it does not give a great end-user experience.

Disabling checkout.guess configuration would force you into the
habit of being a bit more explicit.  Even with checkout.guess
configured to false, you can still say

    $ git switch --detach origin/3.12

and because this does not blindly translate to -b/--track, you would
not see such an error.

A more appropriate design for "--guess" would be to notice the
presence of "--detach" and act differently, i.e. not rewriting
blindly 3.12 to "-b 3.12 -t origin/3.12" unconditionally, instead
rewrite "--detacu 3.12" to "--detach origin/3.12" if "--detach" is
there.

Patches welcome ;-)