Re: [PATCH 1/3] checkout: provide hint when failing due to another worktree

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 17, 2025, 14:17 UTC
Message-ID: <xmqqms6tgo33.fsf@gitster.g>
In-Reply-To: <0dfe3e31-5486-446e-8af5-20669c06ea64@inria.fr>

Gabriel Scherer <gabriel.scherer@inria.fr> writes:

Show 9 quoted lines

> To my defense, this is the hint wording that is already in the git codebase:
>
>   $ git switch HEAD~3
>   fatal: a branch is expected, got commit 'HEAD~3'
>   hint: If you want to detach HEAD at the commit, try again with the
>   --detach option.
>
> I am happy to improve this wording as well if we can converge to
> concrete recommendations.

This looks like a typical apples-and-oranges comparison to me.

I do not see any need to improve the above. In this case, it is clear that the user did want to detach but they just forgot that the "switch" comand wants an explicit "--detach" [*] when switching into a detached HEAD state. There is nothing inherently risky in the act of detaching HEAD that makes it something to be discouraged.

    Side note: This was deliberately made to behave differently from
    the "checkout" command, which intelligently did the right thing
    without being told, i.e. HEAD~3 cannot be a branch name, hence
    it took the command line "git checkout HEAD~3" as an obvious
    request to detach HEAD at that commit.  So if the user came from
    knowing "checkout", it is an easy mistake to make when they
    switch to "switch".  No pun intended.

This is vastly different from trying to checkout a branch and then it turns out that the branch is already in use in somewhere else. We strongly and actively discourage a branch from being used in two different places, in order to avoid an update to it from one place breaking the other place. Unlike detaching HEAD, this one is something the user needs to think twice before doing so.

And in such a request, there is no indication that the user even knew that the branch was already in use elsewhere. It is plausible that the user may not even have tried to check it out if they knew it is checked out elsewhere beforehand (if simply because such a request would be rejected by the safety mechanism); if they only wanted to peek, and if they knew there is already a checkout, they may have just cd'ed there to peek, for example.

Depending on what they wanted to do by having a checkout of that branch, a suitable and safe course of action would be different, and hints would want to help them make right decisions among various possibilities.

Show 9 quoted lines

>> I think the message should help the readers eventually realize the
>> following things to make intelligent decisions.  Making them short
>> to fit in the "hint:" messages is left as an exercise ;-)
>
> Hints make advanced features self-discoverable -- otherwise we find
> them out by reading the entire doc of a command when we are stuck
>
> After reading the hint, users can read the documentation in a more
> targeted way to understand the implications.

Sure. I phrased the above paragraph is somewhat awkwardly, but the point I wanted to convey was that the message would never be able to teach everything they need to know---rather it should give a good starting point and pointers to lead them in the right directions to find out what the best course of action for their situation.

> Would referring the user to the documentation be acceptable?

So, yes. I think risks need to be told in the message to make them realize that blindly proceeding with a hammer without understanding consequence is not a good idea, but we do not need to be exhausive in listing what tools other than the hammer are available, and the hint message would not have enough room to be a manual. So a loud warning of risks, and a couple of pointers into the documentation, would be very much appropriate, I would think.

Thanks.