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

From: Junio C Hamano <[email-masked]>
Date: Mon, 15 Sep 2025 01:53:01 -0700

Gabriel Scherer <[email-masked]> 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.

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 ;-)

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

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

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