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

["Michal Suchánek" <msuchanek@suse.de>]

On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:
> 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,

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

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/