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

From: Gabriel Scherer <gabriel.scherer@inria.fr>
Date: Sep 15, 2025, 19:52 UTC
Message-ID: <0dfe3e31-5486-446e-8af5-20669c06ea64@inria.fr>
In-Reply-To: <xmqqikhkhzbm.fsf@gitster.g>

Thanks for the detailed comments!

On 15/09/2025 10:53, Junio C Hamano wrote:

Show 34 quoted lines

> Gabriel Scherer <gabriel.scherer@inria.fr> writes:
> 
>> In my in-progress version of the patch, the reworded advice is as follows:
>>
>> fatal: 'foo' is already used by worktree at '/home/gasche/Prog/foo'
>> hint: If you want to proceed anyway, try again with
>> --ignore-other-worktrees.
>> hint: Changes to the branch will also impact the other worktrees.
>> hint:
>> hint: If you want to detach HEAD at that branch, try again with the
>> --detach option.
> 
> To those who _need_ these hint messages (in other words, those who
> cannot choose the right way to do what they wanted to do without
> getting hints), I suspect think "if you want to proceed anyway",
> "impact" and "if you want to" are not concrete enough to help them
> make the right choices.
> 
> "If you want to proceed anyway"---of course they all do, because
> they do not know what risks they are taking, and this message does
> not tell them about.  So that isn't very helpful message.
> 
> Changes to the branch would not change the index or any files in the
> working tree of other worktree, leading these users to think that
> they safely live in two separte isolated worlds in these two
> separate worktrees.  Is it clear to them that the "impact" you are
> talking about is exactly the fact that these changes are *NOT*
> propagated to other worktree?
> 
> Then you have "if you want to" without telling the readers why they
> should "want to" (or not) detach.  Which is not all that helpful.
> Why should I go into the scary sounding "detached HEAD" mode?  For
> what for?  If a user can answer that question themselves, they do
> not even need that hint.

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.

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

Would referring the user to the documentation be acceptable?

For 'detach' hints, there is a detailed section DETACHED HEAD in the 'checkout' documentation, which the hint could refer to. For example (imaginary output):

   $ git checkout HEAD~3fatal: a branch is expected, got commit 'HEAD~3'
   hint: If you want to detach HEAD at the commit, try again with the 
--detach option.
   hint: See the "DETACHED HEAD" section in the 'git checkout' 
documentation.

On the other hand for --ignore-other-worktrees there is no user-friendly documentation of these questions currently (I looked at the 'worktree' documentation, in particular for the --force option, and at the --ignore-other-worktrees documentation for 'checkout').

If you agree in principle, I can update my patchset with a documentation commit that explains the justification for the worktree restriction, what happens if we ignore this restriction, and what is the recommended way to respect it.

Show 10 quoted lines

>   - 'foo' is already in use and in which worktree.  Your message
>     "fatal:" is very clear and is good.
> 
>   - if you checkout 'foo' here and start growing or otherwise
>     updating the history of 'foo' in this worktree, the index and the
>     working tree files of other worktree(s) will go out of sync with
>     the tip of 'foo'.  if they 'git commit' from that state, for
>     example, it is very likely that they will record a change that
>     reverts your changes from the history of 'foo', and you do not
>     want that.

(This gets me to wonder if a desirable behavior could be to 'detach' the other worktrees that had the same branch checked out, instead of failing on checkout. Users starting to use the other worktree again would possibly notice more quickly that something is amiss.)

For me this situation is not a big deal: if they commit the removal of 'foo', presumably they will notice that the diff/changes in their commit is not what they expect, and they can come back to the previous state.

I agree that this is surprising and I understand why the project decided to discourage this by default ('fatal error' is plenty discouraging), but there is no data loss or anything of the sort, only recoverable surprises.

>   - if you want to grow history of 'foo' in potentially different
>     direction from what the other worktree with 'foo' is working on,
>     you are better off creating a separte branch 'foo2', with
>     anticipation that you'll eventually merge them together.

Use-case examples:

1. my colleague has a long-lived feature branch called 'super-feature'
2. last year I did a lot of review work on their branch in a separate 
worktree which is still somewhere on my filesystem, but which I am not 
actively working on anymore (and maybe never will)
3. I am in the middle of a bugfix session in another worktree, and 
suddenly I want to check if the bug also occurs in 'super-feature'; I 
stash my current stuff, checkout 'super-feature', and run 'git pull' to 
update it to match my colleague's remote to get the most recent version 
and test it against this bug.

In this scenario, I don't want my current work in (3) to be interrupted by the fact that an old worktree (2) exists that also tracks super-feature, and in fact I do want to update my local 'super-feature' branch to the most recent version. Maybe later on I will come back to my old super-feature worktree (but maybe in another year), and I will start with a 'git pull' or some other command, and I will quickly realize that its index is out of date and fix it.

Show 12 quoted lines

>   - if you only want to browse the files or build but have no
>     intention to change the files or make commits, then you can have
>     the HEAD of this working tree detached at the commit at the tip
>     of 'foo'.  An advantage of this approach is that it will keep you
>     honest, if you know that you are *not* on 'foo', but not on any
>     branch, it would discourage you from making commits and
>     disturbing the other working tree.  Another advantage is that
>     when you do need to make commits (perhaps while you are browsing
>     the files, you may find small typos you want to fix), you can at
>     that time run "git checkout -b foo-typofix" to create a new
>     branch and commit, without disturbing the other worktree that
>     have 'foo' checked out.

I agree that detached-head is a reasonable point in the design space in some cases, so I think that it is reasonable to hint about both options. I am happy to put the detach advice first if this has your preference.

(Note: In the earlier mailing-list thread I discarded detached HEAD because its default rendering in the git bash prompt is unpleasant, it shows the commit and does not mention the detached branch name anymore, which is disorienting. I have since realized that there is a non-default setting GIT_PS1_DESCRIBE_STYLE=branch that can be used to see say "((trunk))" in that case (when we are detached on top of a "trunk" branch, which makes it much more pleasant to use.)