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

[Junio C Hamano <gitster@pobox.com>]

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

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

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