Re: What is the reason behind not hiding git worktrees from git?

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 30, 2025, 15:47 UTC
Message-ID: <xmqqzfac3pts.fsf@gitster.g>
In-Reply-To: <aNuxUqDMNcZZs68n@kitsune.suse.cz>

Michal Suchánek <msuchanek@suse.de> writes:

> On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:
>> I think the best practice is to not add a work tre within the master work tree.
>
> And is that best practice documented somewhere?

I do not think it is documented anywhere.

In fact, I do not think the inventors of the worktree feature ever expected this end-user expectation that checking out multiple worktrees of the repository *INSIDE* a repository's checkout would be any useful without confusing users.

IOW, omission of the documentation is by an assumptionk that nobody would imagine doing in any other way.

We can and should fix it retroactively, if the lack of documentation is not guiding our users in the right direction. Any takers?

> IIRC there are some VCSs for which it is common practice to keep
> checkouts of multiple branches side by side in the repository directory.

I can understand "side-by-side" but not "in". Next to the primary workree (aka "initial clone") would be more common.

> IIRC the repository directory itself is not a checkout in this case.
> Anyway, there is no obvious reason for anyone not familiar with git
> internals to not do this.

Meaning anybody not familiar with the tool would do any random thing outside of the usage pattern that the users of the tool have been establishing over the years? I can certainly understand that. But then, creating a set of worktrees, one per branch, next to the primary worktree that checks out the 'main' branch, would also equally be a likely layout, I would imagine.

Thanks.