What is the reason behind not hiding git worktrees from git?

> "Jakub T. Jankiewicz" <jcubic@jcubic.pl> writes:
> 
> > Why git work trees are are not automatically ignored by git?
> 
> Because there is no reason to ignore them, and ignoring them would
> be annoyingly inconvenient.  Worktrees are not special and treated
> the same way as an ordinary Git working tree with embedded .git
> directory.

> > It does not not show its own .git directory as untracked files
> > 
> > That can be seen as inconsistent.
> 
> Well, I see your point. Since the .git directory is from a git repo, the directory is ignored by git. Therefore, you want git to also ignore other items derived from the repo, including work trees.
> 
> However, this is a minor improvement and I suspect your proposed feature may have an unknown impact.

> Le 30 sept. 2025 à 06:41, Michal Suchánek <msuchanek@suse.de> a écrit :
> 
> On Sat, Sep 27, 2025 at 09:08:44PM +0000, Jason Cho wrote:
>>> It does not not show its own .git directory as untracked files
>>> 
>>> That can be seen as inconsistent.
>> 
>> Well, I see your point. Since the .git directory is from a git repo, the directory is ignored by git. Therefore, you want git to also ignore other items derived from the repo, including work trees.
>> 
>> However, this is a minor improvement and I suspect your proposed feature may have an unknown impact.
> 
> The impact is that the list of worktrees would have to be read to get
> status. As status is not particularly cheap operation in any case I
> would expect the problem to be minor.

>> The impact is that the list of worktrees would have to be read to get
>> status. As status is not particularly cheap operation in any case I
>> would expect the problem to be minor.
>
> I believe status information is used for the shell prompt info, so
> performance hits there have a cost.

> Ben Knoble <ben.knoble@gmail.com> writes:
>
>>> The impact is that the list of worktrees would have to be read to get
>>> status. As status is not particularly cheap operation in any case I
>>> would expect the problem to be minor.
>>
>> I believe status information is used for the shell prompt info, so
>> performance hits there have a cost.
>
> Sure, but an embedded git-controlled working tree _should_ be
> flagged as an untracked entity, _unless_ it is ignore'd, no?
>
> That is how you would add a new submodule to your project after all.
> So, if you want to ignore them, just add them to .git/info/exclude
> or something, perhaps?
>
> Why do people even want to have such a layout, unless they want to
> make it a submodule (or deliberate subdirectory that is unrelated)?
>
>  -+- README.md (your own branch, probably on main)
>   |
>   +-+ worktree-foo (worktree checkout of branch foo)
>   | |
>   | +-- README.md (a slight variant of the file in foo)
>   |
>   +-+ worktree-bar (worktree checkout of branch bar)
>   | |
>   | +-- README.md (a slight variant of the file in bar)
>   |
>   +-+ worktree-baz (worktree checkout of branch baz)
>   | |
>   | +-- README.md (a slight variant of the file in baz)
>
> Wouldn't it be easier to manage if you had this instead?
>
>  -+
>   |
>   +-+ my-project (the primary worktree, probably on main)
>   | |
>   | +-- README.md (the file from branch main)
>   |
>   +-+ worktree-foo (worktree checkout of branch foo)
>   | |
>   | +-- README.md (a slight variant of the file in foo)
>   |
>   +-+ worktree-bar (worktree checkout of branch bar)
>   | |
>   | +-- README.md (a slight variant of the file in bar)
>   |
>   +-+ worktree-baz (worktree checkout of branch baz)
>   | |
>   | +-- README.md (a slight variant of the file in baz)
>
> That way, you can go up to the umbrella directory and ...
>
>     $ cd ..
>     $ ls
>     my-project worktree-foo worktree-bar worktree-baz
>     $ grep -e HowTo */README.md
>
> ... do things you would do collectively to these worktrees with the
> primary worktree included as well.

> Also, I'm almost sure that the first thing almost every worktree novice
> does (I did), quite naturally, is:
>
> $ git wotktree add <branch>
>
> that happily succeeds /anywhere/ inside primary worktree without any
> warning for me. It probably should either have created $top/../<branch>
> instead, or refuse to proceed without confirmation in the first place.

> Sergey Organov <sorganov@gmail.com> writes:
> 
> > Also, I'm almost sure that the first thing almost every worktree novice
> > does (I did), quite naturally, is:
> >
> > $ git wotktree add <branch>
> >
> > that happily succeeds /anywhere/ inside primary worktree without any
> > warning for me. It probably should either have created $top/../<branch>
> > instead, or refuse to proceed without confirmation in the first place.  
> 
> Yeah, I almost never type 'git worktree add <directory>' without
> "../" at the beginning of the directory, and every time I do so, I
> do wonder if this is a UI pitfall that we should warn the users
> about.  Perhaps we should start from documentation updates and
> possibly a new warning or two?

> Sergey Organov <sorganov@gmail.com> writes:
> > Also, I'm almost sure that the first thing almost every worktree novice
> > does (I did), quite naturally, is:
> >
> > $ git wotktree add <branch>
> >
> > that happily succeeds /anywhere/ inside primary worktree without any
> > warning for me. It probably should either have created $top/../<branch>
> > instead, or refuse to proceed without confirmation in the first place.
>
> Yeah, I almost never type 'git worktree add <directory>' without
> "../" at the beginning of the directory, and every time I do so, I
> do wonder if this is a UI pitfall that we should warn the users
> about.  Perhaps we should start from documentation updates and
> possibly a new warning or two?

> It just didn't occur to me, that you suppose to have them out outside the
> root directory. The way I think about git is:
>
> directory/
>          .git
>          and all the stuff that belong that repo

> skip over them when scanning the output. Moreover, I think this is the
> first time that we have (on the list, at least) heard a complaint
> about the "noise", which may suggest that this is a non-issue for most
> people, and that a warning telling people to avoid the practice would
> be unwelcome.

> Le 1 oct. 2025 à 14:54, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> Ben Knoble <ben.knoble@gmail.com> writes:
> 
>>> The impact is that the list of worktrees would have to be read to get
>>> status. As status is not particularly cheap operation in any case I
>>> would expect the problem to be minor.
>> 
>> I believe status information is used for the shell prompt info, so
>> performance hits there have a cost.
> 
> Sure, but an embedded git-controlled working tree _should_ be
> flagged as an untracked entity, _unless_ it is ignore'd, no?

> That is how you would add a new submodule to your project after all.
> So, if you want to ignore them, just add them to .git/info/exclude
> or something, perhaps?
> 
> Why do people even want to have such a layout, unless they want to
> make it a submodule (or deliberate subdirectory that is unrelated)?

> Eric Sunshine <sunshine@sunshineco.com> writes:
> 
> > skip over them when scanning the output. Moreover, I think this is the
> > first time that we have (on the list, at least) heard a complaint
> > about the "noise", which may suggest that this is a non-issue for most
> > people, and that a warning telling people to avoid the practice would
> > be unwelcome.
> 
> Ah, different people guess different reasons out of the same
> observation.  My interpretation of this is the first time about the
> complaint on "noise" was because everybody else would not even have
> additional worktree in-tree.

> > Aside: It might be valuable to extend the documentation to add a
> > discussion about hanging worktrees off of a bare repository. People do
> > use such a workflow, and git-worktree officially supports it, but I
> > don't think there is any in-project documentation which mentions it.
> 
> Oh, that is an obvious thing to do, too, to attach "additional"
> worktrees to a bare repository (which does not have the primary
> worktree).  I do not think anybody sane would add these worktrees
> in-tree if the repository is bare, though.

> On Wed, Oct 01, 2025 at 03:27:03PM -0700, Junio C Hamano wrote:
>> Eric Sunshine <sunshine@sunshineco.com> writes:
>> 
>> > skip over them when scanning the output. Moreover, I think this is the
>> > first time that we have (on the list, at least) heard a complaint
>> > about the "noise", which may suggest that this is a non-issue for most
>> > people, and that a warning telling people to avoid the practice would
>> > be unwelcome.
>> 
>> Ah, different people guess different reasons out of the same
>> observation.  My interpretation of this is the first time about the
>> complaint on "noise" was because everybody else would not even have
>> additional worktree in-tree.
>
> I suppose a suggestion about not adding worktree in-tree in the add
> command description would be helpful to avoid the problem.
>
> That's the part I would read if I wanted to learn about adding
> worktrees, and it has none of those examples you mention.

> Also add advice to put new worktrees outside of existing ones.
>
> Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> ---
>  Documentation/git-worktree.adoc | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> index 389e669ac0..ec31863aec 100644
> --- a/Documentation/git-worktree.adoc
> +++ b/Documentation/git-worktree.adoc
> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
>  $ git worktree add --track -b <branch> <path> <remote>/<branch>
>  ------------
>  +
> +For best results it is advised to specify <path> outside of the repository and
> +existing worktrees - see <<EXAMPLES>>

>
> ++
>  If the branch exists in multiple remotes and one of them is named by
>  the `checkout.defaultRemote` configuration variable, we'll use that
>  one for the purposes of disambiguation, even if the `<branch>` isn't
> @@ -502,8 +505,8 @@ locked "reason\nwhy is locked"
>  ...
>  ------------
>
> -EXAMPLES
> ---------
> +[[EXAMPLES]]EXAMPLES
> +--------------------

>  You are in the middle of a refactoring session and your boss comes in and
>  demands that you fix something immediately. You might typically use
>  linkgit:git-stash[1] to store your changes away temporarily, however, your
> --
> 2.51.0

> Also add advice to put new worktrees outside of existing ones.
>
> Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> ---
>  Documentation/git-worktree.adoc | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> index 389e669ac0..ec31863aec 100644
> --- a/Documentation/git-worktree.adoc
> +++ b/Documentation/git-worktree.adoc
> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
>  $ git worktree add --track -b <branch> <path> <remote>/<branch>
>  ------------
>  +
> +For best results it is advised to specify <path> outside of the repository and
> +existing worktrees - see <<EXAMPLES>>
> ++

>  If the branch exists in multiple remotes and one of them is named by
>  the `checkout.defaultRemote` configuration variable, we'll use that
>  one for the purposes of disambiguation, even if the `<branch>` isn't
> @@ -502,8 +505,8 @@ locked "reason\nwhy is locked"
>  ...
>  ------------
>  
> -EXAMPLES
> ---------
> +[[EXAMPLES]]EXAMPLES
> +--------------------

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

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

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

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

> 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

> On Thu, Oct 2, 2025, at 17:51, Michal Suchanek wrote:
> > Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> 
> I think this could do with more setup and motivation.
> 
> I’ve seen a lot of questions on worktrees where they introduce the
> problem with “I use a bare repository with worktrees”.  And I was
> puzzled that they kept using bare repositories all the time.  I’ve
> forgotten some of those details but I do seem to remember that they were
> motivated to go all-in on making a ton of worktrees, and using the the
> “project root” to do it.
> 
> Is that what the bare-setup is getting at? ;)

> > ---
> >  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
> > +------------
> 
> This works for me.  But why not this?
> 
>     git clone --bare <repo> some-repository
>     cd some-repository
>     git worktree add some-branch
>     git worktree add another-branch

> This works for me.  But why not this?
>
>     git clone --bare <repo> some-repository
>     cd some-repository
>     git worktree add some-branch
>     git worktree add another-branch

> Michal Suchanek <msuchanek@suse.de> writes:
> 
> > Also add advice to put new worktrees outside of existing ones.
> >
> > Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> > ---
> >  Documentation/git-worktree.adoc | 7 +++++--
> >  1 file changed, 5 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> > index 389e669ac0..ec31863aec 100644
> > --- a/Documentation/git-worktree.adoc
> > +++ b/Documentation/git-worktree.adoc
> > @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
> >  $ git worktree add --track -b <branch> <path> <remote>/<branch>
> >  ------------
> >  +
> > +For best results it is advised to specify <path> outside of the repository and
> > +existing worktrees - see <<EXAMPLES>>
> > ++
> 
> I am wondering if we cram more information in "For best results", by
> adding the "otherwise...".  Here is my (failed) attempt.
> 
>     Use <path> outside of your working tree and existing worktrees
>     (see <<EXAMPLES>>); otherwise your new worktree will appear as
>     an untracked directory.
> 
> I say "failed" as the above phrasing makes it sound as if that
> untracked-ness is the only downside, and also by omitting "advised",
> it makes it sound as if there is no upside (other than inertia) in
> doing so.
> 
> So, I'll (atleast tentatively) queue yours as-is.

> >  If the branch exists in multiple remotes and one of them is named by
> >  the `checkout.defaultRemote` configuration variable, we'll use that
> >  one for the purposes of disambiguation, even if the `<branch>` isn't
> > @@ -502,8 +505,8 @@ locked "reason\nwhy is locked"
> >  ...
> >  ------------
> >  
> > -EXAMPLES
> > ---------
> > +[[EXAMPLES]]EXAMPLES
> > +--------------------
> 
> cf. https://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/
> 
> IOW, we probably should write this more like ...
> 
>         +[[EXAMPLES]]
>          EXAMPLES
>          --------

> Also add advice to put new worktrees outside of existing ones.
> 
> Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> ---
>  Documentation/git-worktree.adoc | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-

> index 389e669ac0..ec31863aec 100644
> --- a/Documentation/git-worktree.adoc
> +++ b/Documentation/git-worktree.adoc
> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
>  $ git worktree add --track -b <branch> <path> <remote>/<branch>
>  ------------
>  +
> +For best results it is advised to specify <path> outside of the repository 

> ++
>  If the branch exists in multiple remotes and one of them is named by
>  the `checkout.defaultRemote` configuration variable, we'll use that
>  one for the purposes of disambiguation, even if the `<branch>` isn't
> @@ -502,8 +505,8 @@ locked "reason\nwhy is locked"
>  ...
>  ------------
> 
> -EXAMPLES
> ---------
> +[[EXAMPLES]]EXAMPLES
> +--------------------

> On Thursday, 2 October 2025 17:51:34 CEST Michal Suchanek wrote:
> > Also add advice to put new worktrees outside of existing ones.
> > 
> > Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> > ---
> >  Documentation/git-worktree.adoc | 7 +++++--
> >  1 file changed, 5 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-
> worktree.adoc
> > index 389e669ac0..ec31863aec 100644
> > --- a/Documentation/git-worktree.adoc
> > +++ b/Documentation/git-worktree.adoc
> > @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
> >  $ git worktree add --track -b <branch> <path> <remote>/<branch>
> >  ------------
> >  +
> > +For best results it is advised to specify <path> outside of the repository 
> and
> > +existing worktrees - see <<EXAMPLES>>
> 
> Please use the form <<EXAMPLES,EXAMPLES>> in order to let the translators also 
> change the cross-link text in their language.
> 
> Also, the <path> placeholder should be formatted as _<path>_. For your 
> information, I'm right in the middle of pushing the conversion of git-
> worktree.adoc to the new synopsis style. 

> 
> > ++
> >  If the branch exists in multiple remotes and one of them is named by
> >  the `checkout.defaultRemote` configuration variable, we'll use that
> >  one for the purposes of disambiguation, even if the `<branch>` isn't
> > @@ -502,8 +505,8 @@ locked "reason\nwhy is locked"
> >  ...
> >  ------------
> > 
> > -EXAMPLES
> > ---------
> > +[[EXAMPLES]]EXAMPLES
> > +--------------------
> 
> As noted by others, please put the block anchors on a dedicated line, out of 
> the translation scope.
> 
> Thank you.
> 
> 

> Signed-off-by: Michal Suchanek <msuchanek@suse.de>
> ---
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
> +For best results it is advised to specify _<path>_ outside of the repository
> +and existing worktrees - see <<EXAMPLES,EXAMPLES>>

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

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

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

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

> [...] There are plenty of people who already locate worktrees as
> subdirectories of the main worktree[*] and do so without problem, and
> for whom it is a preferred workflow, so I don't see why we would want to
> penalize them by warning against doing so, especially since there is no
> technical reason to avoid the practice (i.e. Git handles it just fine).
> [...]
>
> FOOTNOTES
> 
> [*]: There have been numerous emails on the list showing that placing
> worktrees as subdirectories of the main worktree is common enough
> practice. And, as far as "experienced users" are concerned (not just
> novices picking up the practice from blogs or tutorials), I recall an
> email discussion in which Dscho has said that he locates worktrees as
> subdirectories of the main worktree, as well. I, too, have done so on
> occasion.

> that main worktree after verifying with `git status` that there was no
> unfinished business to take care of before deleting the repository.
> Because that secondary worktree (which did contain unfinished business,
> including a carefully crafted series of commits) was now obviously no
> longer a worktree but only a tree without a working `.git`.

> On Fri, Oct 24, 2025 at 6:15 AM Michal Suchánek <msuchanek@suse.de> wrote:
> > On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:
> > > 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.
> 
> Sorry, I mistyped that. What I meant was:
> 
>     $ git -C myproj.git worktree add ../feature-a
> 
> which makes the worktrees siblings of the bare repository.

> On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:
> > Sorry, I mistyped that. What I meant was:
> >
> >     $ git -C myproj.git worktree add ../feature-a
> >
> > which makes the worktrees siblings of the bare repository.
>
> and requires the mental gymnastics of adjusting the paths passed to the
> command based on -C argument. Does not sound like a good example how to
> use the command.

> Michal Suchánek <msuchanek@suse.de> writes:
> 
> > On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:
> >> I think the best practice is to not add a work tre within the master work tree.
> >
> > And is that best practice documented somewhere?
> 
> I do not think it is documented anywhere.
> 
> In fact, I do not think the inventors of the worktree feature ever
> expected this end-user expectation that checking out multiple
> worktrees of the repository *INSIDE* a repository's checkout would
> be any useful without confusing users.
> 
> IOW, omission of the documentation is by an assumptionk that nobody
> would imagine doing in any other way.  
> 
> We can and should fix it retroactively, if the lack of documentation
> is not guiding our users in the right direction.  Any takers?
> 
> > IIRC there are some VCSs for which it is common practice to keep
> > checkouts of multiple branches side by side in the repository directory.
> 
> I can understand "side-by-side" but not "in".  Next to the primary
> workree (aka "initial clone") would be more common.
> 
> > IIRC the repository directory itself is not a checkout in this case.
> > Anyway, there is no obvious reason for anyone not familiar with git
> > internals to not do this.
> 
> Meaning anybody not familiar with the tool would do any random thing
> outside of the usage pattern that the users of the tool have been
> establishing over the years?  I can certainly understand that.  But
> then, creating a set of worktrees, one per branch, next to the
> primary worktree that checks out the 'main' branch, would also equally
> be a likely layout, I would imagine.

> On Tue, Nov 18, 2025 at 7:01 AM Michal Suchánek <msuchanek@suse.de> wrote:
>> On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:
>> > Sorry, I mistyped that. What I meant was:
>> >
>> >     $ git -C myproj.git worktree add ../feature-a
>> >
>> > which makes the worktrees siblings of the bare repository.
>>
>> and requires the mental gymnastics of adjusting the paths passed to the
>> command based on -C argument. Does not sound like a good example how to
>> use the command.
>
> Fair enough. I happen to find the above easy to reason about, but I
> get your point, as well.
>
> So the remaining actionable bit from the review[*] regards spelling
> out in prose that hanging worktrees off of a bare repository is an
> explicitly supported mode of operation.
>
> [*]: https://lore.kernel.org/git/CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com/