On Tue, Sep 30, 2025 at 08:47:11AM -0700, Junio C Hamano wrote:

Michal Suchánek [off-list ref] writes:

quoted

On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:

quoted

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?

quoted

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.

quoted

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.

And that's what the existing example shows.

Thanks

Michal