Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example

From: Michal Suchánek <msuchanek@suse.de>
Date: Oct 2, 2025, 18:39 UTC
Message-ID: <aN7G7p2LNUCSHlaY@kitsune.suse.cz>
In-Reply-To: <xmqqcy75w531.fsf@gitster.g>

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

Show 34 quoted lines

> Michal Suchanek <msuchanek@suse.de> writes:
> 
> > Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> > ---
> >  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

Show 12 quoted lines

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

Show 20 quoted lines

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

Show 5 quoted lines

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