On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:

On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek [off-list ref] wrote:

quoted

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,

So it's not documented to start with. I did not read the whole text,
only focused on the problem with adding worktrees in problematic places.

That sounds like more general update of the file is needed, also for
the prevoius patch.

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

quoted

Signed-off-by: Michal Suchanek <redacted>
---

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.

That creates a mess. First part is not creating the directory to contain
the worktrees related to the repository. Second is creating the
worktrees inside the bare repository, contrary to any reasonabe usage
advice.

Thanks

Michal

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