From: Gabriel Scherer <gabriel.scherer@inria•fr>
To: Junio C Hamano <gitster@pobox•com>
Cc: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail•com>,
git@vger•kernel.org, "D. Ben Knoble" <ben.knoble@gmail•com>,
Phillip Wood <phillip.wood@dunelm•org.uk>
Subject: Re: [PATCH 1/3] checkout: provide hint when failing due to another worktree
Date: Mon, 15 Sep 2025 21:52:19 +0200 [thread overview]
Message-ID: <0dfe3e31-5486-446e-8af5-20669c06ea64@inria.fr> (raw)
In-Reply-To: <xmqqikhkhzbm.fsf@gitster.g>
Thanks for the detailed comments!
On 15/09/2025 10:53, Junio C Hamano wrote:
> 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.
> - '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.
> - 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.)
next prev parent reply other threads:[~2025-09-15 19:52 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-13 14:13 [PATCH 0/3] extend --ignore-other-worktrees to 'rebase', add hints Gabriel Scherer
2025-09-13 14:13 ` [PATCH 1/3] checkout: provide hint when failing due to another worktree Gabriel Scherer
2025-09-13 20:55 ` Kristoffer Haugsbakk
2025-09-14 7:50 ` Gabriel Scherer
2025-09-15 8:53 ` Junio C Hamano
2025-09-15 19:52 ` Gabriel Scherer [this message]
2025-09-16 5:32 ` Junio C Hamano
2025-09-17 14:17 ` Junio C Hamano
2025-09-17 15:25 ` Gabriel Scherer
2025-09-19 14:13 ` Phillip Wood
2025-09-14 19:03 ` Ben Knoble
2025-09-14 19:06 ` Ben Knoble
2025-09-14 19:32 ` Kristoffer Haugsbakk
2025-09-13 14:13 ` [PATCH 2/3] rebase: support --ignore-other-worktrees Gabriel Scherer
2025-09-15 10:09 ` Phillip Wood
2025-09-15 16:23 ` Junio C Hamano
2025-09-13 14:13 ` [PATCH 3/3] rebase: hint when failing on branch used by another worktree Gabriel Scherer
2025-09-13 19:30 ` [PATCH 0/3] extend --ignore-other-worktrees to 'rebase', add hints Ben Knoble
2025-09-13 20:02 ` Gabriel Scherer
2025-09-15 10:09 ` Phillip Wood
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0dfe3e31-5486-446e-8af5-20669c06ea64@inria.fr \
--to=gabriel.scherer@inria$(echo .)fr \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=phillip.wood@dunelm$(echo .)org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox