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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 2, 2025, 18:06 UTC
Message-ID: <xmqqcy75w531.fsf@gitster.g>
In-Reply-To: <1d5b41562937d83be261d054989b04db6cb94a86.1759420102.git.msuchanek@suse.de>

Michal Suchanek <msuchanek@suse.de> writes:

Show 22 quoted lines

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

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.

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.

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