On Thu, Oct 02, 2025 at 11:06:58AM -0700, Junio C Hamano wrote:

Michal Suchanek [off-list ref] writes:

quoted

Signed-off-by: Michal Suchanek <redacted>
---
 Documentation/git-worktree.adoc | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index ec31863aec..122b191ff9 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc

@@ -525,6 +525,16 @@ $ popd
 $ git worktree remove ../temp
 ------------
 
+Side by side branch checkouts for a repository using multiple worktrees
+
+------------
+mkdir some-repository
+cd some-repository
+git clone --bare gitforge@someforge.example.com:some-org/some-repository .git
+git --git-dir=.git worktree add some-branch
+git --git-dir=.git worktree add another-branch
+------------

It is a good example to have a bare clone and get worktrees attached
to it, but I do not think that it is a great idea to call that bare
clone ".git".  It makes it confusing if that some-repository/
directory that has a ".git" directory is a non-bare clone with no
working tree files, or if it is a directory that Git has no
knowledge about, that happens to have a single bare repository plus
worktrees.  The answer is the latter, but I suspect that Git itself
would probably be confused (i.e. "cd some-repository && git status"
---if you try it, what does it say?).

git status
fatal: this operation must be run in a work tree

Naming it after the project may make it more apparent what is going
on when the user goes into that top-level shell directory, perhaps
like this, if we were working with a "bunny" project:

    mkdir bunny
    cd bunny
    git clone --bare gitforge@someforge.example.com:some-org/bunny bunny.git
    git --git-dir=bunny.git worktree add some-branch
    git --git-dir=bunny.git worktree add another-branch

Then when you "cd bunny && ls", you'd see the bare repository
bunny.git with two checkouts.

That also works.

Having said all that.

I know some folks like such a layout for some (perhaps ideological)
reason (i.e. no checkout is more special than others, everybody is
equal), but I am not absolutely sure if it works better in a larger
workflow in practice than having a primary worktree that is not a
bare repository.  If you do the above with a non-bare repository in
the center, it would look like this:

    mkdir bunny-project
    cd bunny-project
    git clone gitforge@someforge.example.com:some-org/bunny main
    cd main
    git worktree add ../my-topic-1
    git worktree add ../my-topic-2

and have my interaction with the upstream project only from inside
the primary worktree, i.e., "main".  Additional worktrees are more
or less ephemeral, and can go away.

Yes, that's a possible use case. Also git worktree add
/dev/shm/do-some-testing

However, that's not the intended use here. Rather it's one worktree per
branch, no branch switching as a result. I recall some VCSes had this
as default or only way to work with different branches, and not
switching branches all the time certainly has its advantages.

Thanks

Michal

quoted

+
 BUGS
 ----
 Multiple checkout in general is still experimental, and the support