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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 11, 2025, 05:17 UTC
Message-ID: <CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com>
In-Reply-To: <0e11e6fb394ffa3a1286deea5a8ede5ba3e4bdf4.1760115862.git.msuchanek@suse.de>

On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek <msuchanek@suse.de> wrote:

> doc: git-worktree: Add side by side branch checkout example

Thanks for taking my suggestion[*] regarding a possible git-worktree documentation update and turning it into an actual patch. This is a reasonable beginning, but I think it needs more work.

To begin, the idea was to document that worktrees can be used with bare repositories, but neither the subject of this patch nor the prose added to the documentation itself mentions bare worktrees. Instead, they mention only "side by side branch checkouts", but I'm not even sure what that means. I certainly wouldn't think of "bare repository" when given the phrase "side by side branch checkouts", and I'm pretty sure that phrase is not part of the existing Git lexicon, whereas "bare repository" is, and is well known and well understood. So, I think both the commit message and the prose added to the documentation ought to mention "bare repository" instead.

Next, I think it is quite important that we spell out concretely in prose that worktrees can be used with a bare repository. It is not sufficient to merely infer it by giving an example, especially if the reader is primarily reading the git-worktree.txt introductory material which explains what worktrees are all about. So, for instance, we could expand the "The new worktree is called..." introductory paragraph to instead say something like this:

    This new worktree is called a "linked worktree" as opposed to the
    "main worktree" prepared by git-init(1) or git-clone(1). A
    repository has one main worktree (if it’s not a bare repository)
    and zero or more linked worktrees. Linked worktrees can also be
    used with a bare repository, in which case there is no main
    worktree but *only* linked worktrees (see EXAMPLES).

and also move the "When you are done with..." sentence from that paragraph down to the "If a working tree is deleted..." paragraph, which would become:

    When you are done with a linked worktree, remove it with `git
    worktree remove`. If a working tree is deleted without using `git
    worktree remove`, then its associated administrative files, which
    reside in the repository (see "DETAILS" below)...

Show 16 quoted lines

> Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> ---
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> @@ -526,6 +526,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 some-repository.git
> +git --git-dir=some-repository.git worktree add some-branch
> +git --git-dir=some-repository.git worktree add another-branch
> +------------

Several comments...

First, as mentioned above, rather than using the phrasing "side by side branch checkouts", let's talk about this as being an example of using worktrees with a bare repository.

Second, for consistency, let's follow the lead of the existing example in git-worktree.txt and show the "$" shell prompt preceding the commands. For instance:

    $ mkdir ...
    $ git clone ...

Third, the example seems overly complicated, especially with its use of `--git-dir`, which feels less discoverable (at least to me) than, say `-C`. What I have in mind is an example more like this:

    $ git clone --bare <repository-url> myproj.git
    $ git -C myproj.git worktree add feature-a
    $ git -C myproj.git worktree add feature-b

That should be more than sufficient to get people up and running with associating worktrees to a bare repository.

[*] https://lore.kernel.org/git/CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com/