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

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

[Jakub T. Jankiewicz]

Hi,

I use git since 2010, but I've discovered git work trees recently.

Why git work trees are are not automatically ignored by git?

It would kind if silly to add the whole project on different branch to the
main repo.

This is an example:

git worktree add base
git status


On branch master
Your branch is up to date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        base/

nothing added to commit but untracked files present (use "git add" to track)

What is the rationale for this. Why base/ is not automatically ignored and
you need to add it to the .gitignore by hand?

I use git 2.51.0 from Fedora default repo.

--
Jakub T. Jankiewicz, Senior Front-End Developer
https://jakub.jankiewicz.org
https://lips.js.org
https://koduj.org

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

[Junio C Hamano]

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

That is, if you "git clone" somebody else's project into your
current directory, when you are in the working tree of you git
repository, that working tree of the cloned repository would appear
as an untracked content from the point of view of the containing
repository of yours.  It is up to you to add it as a subproject, or
leave it as an untracked directory.

If you do not want to see a new worktree as an untracked directory
in another repository, do not do

    $ git worktree add base

in the first place.  You are creating the new worktree _inside_ an
existing repository's working tree, and it is no surprise that the
new directory appears as an untracked directory.

In other words, if it hurts, don't do it.

Instead, you can create your additional worktree outside the working
tree you are using.  For example, I keep a handful of worktrees just
next to my primary working tree, by doing something like

    $ git worktree add --detach ../git.maint maint
    $ git worktree add --detach ../git.next next
    $ git worktree add --detach ../git.seen seen

when I am in my primary working tree.  Then I can leave some work in
progress in my primary working tree and then context switch out to

    $ cd ../git.next && git reset --hard next
    $ do stuff on next

any one of these additional worktrees.

Hope this helps.

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

[Michal Suchánek]

On Sat, Sep 27, 2025 at 09:52:56AM -0700, Junio C Hamano wrote:
> "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.

Sure, that's another repository.

It does not not show its own .git directory as untracked files although
it is in the main worktree, though.

So why another worktree of the same repository is shown?

That can be seen as inconsistent.

Thanks

Michal

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

[Jason Cho]

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

Anyway, what's your real use case? Do you really add hundreds of work trees within the same repo directory so that you hate to see them in git status?

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

[Jason Cho]

I think the best practice is to not add a work tre within the master work tree.

Suppose a repo is at the master branch, and you export a work tree in the directory f.

Then, you check out the main repo to another branch which so happens to have a file named f. In this case, the check-out will fail due to the name collision.

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

[Michal Suchánek]

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?

IIRC there are some VCSs for which it is common practice to keep
checkouts of multiple branches side by side in the repository directory.
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.

> Suppose a repo is at the master branch, and you export a work tree in the directory f.
> 
> Then, you check out the main repo to another branch which so happens to have a file named f. In this case, the check-out will fail due to the name collision.

That would not happen in this work style, each branch has a separate
checkout. If you want to checkout a branch you create a worktree for it.

Thanks

Michal

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

[Michal Suchánek]

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.

> Anyway, what's your real use case? Do you really add hundreds of work trees within the same repo directory so that you hate to see them in git status?

What is the abstraction you are trying to propose here?

Or do you suggest to eschew any intelligible abstraction in favor of
(probably minor) implementation convenience?

Thanks

Michal

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

[Junio C Hamano]

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.

Thanks.

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

[Ben Knoble]

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

I believe status information is used for the shell prompt info, so performance hits there have a cost.

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

[Junio C Hamano]

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.

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

[Sergey Organov]

Junio C Hamano <gitster@pobox.com> writes:

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

I suspect people rather expect support for repository with multiple
equal worktrees (no "primary" one), like this:

myproject / .git
          / worktree-foo
          / worktree-bar


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

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

[Junio C Hamano]

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?

Thanks.

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

[Jakub T. Jankiewicz]

On Wed, 01 Oct 2025 13:48:54 -0700
Junio C Hamano <gitster@pobox.com> wrote:

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

I discovered work trees recently, even that they are supported for years.
And I though that the only way you use them is:

git worktree add branch

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

You don't create submodules outside of your root directory. Didn't you?

--
Jakub T. Jankiewicz, Senior Front-End Developer
https://jakub.jankiewicz.org
https://lips.js.org
https://koduj.org

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

[Eric Sunshine]

On Wed, Oct 1, 2025 at 4:49 PM Junio C Hamano <gitster@pobox.com> wrote:
> 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?

Every example in the git-worktree documentation which mentions a
literal path (as opposed to generic <path>) already uses the "../"
prefix (and has from inception), including the example in the
introductory paragraphs:

    For instance, `git worktree add ../hotfix` creates new branch hotfix
    and checks it out at path `../hotfix`.

and the "real" Example block toward the end of the man page:

    $ git worktree add -b emergency-fix ../temp master
    $ pushd ../temp
    # ... hack hack hack ...
    $ git commit -a -m 'emergency fix for boss'
    $ popd
    $ git worktree remove ../temp

There are exactly zero examples in the man page lacking the "../" prefix.

It would be possible, of course, to add a "best practices" section to
the introductory paragraphs advising against creating worktrees as
subdirectories of the "main" worktree (assuming people even agree that
a best practice is to place worktrees elsewhere). However, considering
that the existing examples using "../" have been ignored (in a
fashion), one wonders how much a "best practices" discussion would
help (assuming people aren't really reading the documentation anyhow,
and may very well be cargo-culting git-worktree commands from blogs or
external tutorials).

Regarding issuing warnings: I'm not fond of the idea. 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). The only minor
downside of the practice (if one considers it a downside) is an
aesthetic one: having to update ".gitignore" or ".git/info/exclude",
or to simply consider them "visual noise" in git-status output and
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.

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.

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.

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

[Junio C Hamano]

"Jakub T. Jankiewicz" <jcubic@jcubic.pl> writes:

> 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

But the point of additional worktrees is to have the stuff
additionally appear outside your normal working area, so that you
can continue working inside your primary checkout without getting
affected by those extra directories.  When you _do_ want to have
them _outside_ your primary working tree, you use them.  That is the
whole point of having additional worktrees that lets you make the
contents of other branches materialize on the filesystem.

> You don't create submodules outside of your root directory. Didn't you?

Sorry, but I do not get that question.

Submodule is attached to your superproject as part of it.  A
worktree is an additional and separate instantiation of the project
itself, which is quite a different thing.  They are apples and
oranges, as far as I can see.

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

[Junio C Hamano]

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.

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

[Ben Knoble]

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

Sorry, I’m not disagreeing with that here? Merely pointing out if that proposed changes affect git-status performance for the worse I will be disappointed :)

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

[snip: a better way]

Yep, I agree that’s easier, but I shouldn’t judge other’s workflows (I do it all the time 😅).

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

[Michal Suchánek]

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.

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

That's exactly the part that is obvious only to people familiar with git
internals, not people reading the documentation. And it's what is needed
to create the side-by-side layout for people that want to use that.

Thanks

Michal

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

[Junio C Hamano]

Michal Suchánek <msuchanek@suse.de> writes:

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

Yeah, care to throw a patch or two at the documentation to help our
users and us?

Thanks.

[PATCH 1/2] doc: git-worktree: Link to examples

[Michal Suchanek]

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

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

[Michal Suchanek]

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
+------------
+
 BUGS
 ----
 Multiple checkout in general is still experimental, and the support
-- 
2.51.0

Re: [PATCH 1/2] doc: git-worktree: Link to examples

[Kristoffer Haugsbakk]

> doc: git-worktree: Link to examples

The initial word after the colon should be lowercase unless it’s a
proper noun.

On Thu, Oct 2, 2025, at 17:51, 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>>

This is definitely an improvement.  The current doc forces you to infer
that you shouldn’t put worktrees inside the repository... or just think
too much.

It might also be nice to have a clause which hints at why?  Maybe just
one or a few reasons, e.g. that you would have gitignore the worktree
directory.

> +existing worktrees - see <<EXAMPLES>>

I was about to recommend a `--` for en-dash but now I see that that
produces an em-dash instead.. :)

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

Apparently an anchor on the same line should not be used.

https://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/#:~:text=Please%20do%20not%20put%20anchors

>  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

Re: [PATCH 1/2] doc: git-worktree: Link to examples

[Junio C Hamano]

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

Thanks.

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

[Kristoffer Haugsbakk]

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

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

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

[Junio C Hamano]

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

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

[Michal Suchánek]

On Thu, Oct 02, 2025 at 11:06:58AM -0700, Junio C Hamano wrote:
> 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?).

git status
fatal: this operation must be run in a work tree

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

That also works.

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

Yes, that's a possible use case. Also git worktree add
/dev/shm/do-some-testing

However, that's not the intended use here. Rather it's one worktree per
branch, no branch switching as a result. I recall some VCSes had this
as default or only way to work with different branches, and not
switching branches all the time certainly has its advantages.

Thanks

Michal

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

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

[Michal Suchánek]

On Thu, Oct 02, 2025 at 07:51:20PM +0200, Kristoffer Haugsbakk wrote:
> 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? ;)

It shows one way how to make a ton of worktrees without having them step
on each other, hopefully avoiding this pitfall at least in some cases.

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

I would certainly not recommend that. There is great potential for
conflicting with git internal structures of the bare repository.

Thanks

Michal

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> 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

Do you mean "some-repository/config" is the local configuration
file, next to it there are "some-branch" and "another-branch"
directories, and you have to have some way to tell that, among
direct subdirectories of "some-repository/", "some-branch/" is a
worktree while refs/ is not?

No thanks ;-).

Re: [PATCH 1/2] doc: git-worktree: Link to examples

[Michal Suchánek]

On Thu, Oct 02, 2025 at 10:44:06AM -0700, Junio C Hamano wrote:
> 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.

Yes, I did not want to make this explanation too long. Spelling out all
the details would take multiple paragraphs but it's probably not worth
being that verbose.

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

That could use correcting in the the asciidoc documentation. The
examples there put the anchor on the same line.

That's probably where the repeated problem of this formatting is coming
from.

The other thing is that if you used sections you would get anchors
automatically for free avoiding this problem altogether.

Thanks

Michal

Re: [PATCH 1/2] doc: git-worktree: Link to examples

[Jean-Noël AVILA]

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.

[PATCH v2 1/2] doc: git-worktree: Link to examples

[Michal Suchanek]

Also add advice to put new worktrees outside of existing ones.

Signed-off-by: Michal Suchanek <msuchanek@suse.de>
---
v2: Improve formatting
---
 Documentation/git-worktree.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index 389e669ac0..a580f4c072 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,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,6 +505,7 @@ locked "reason\nwhy is locked"
 ...
 ------------
 
+[[EXAMPLES]]
 EXAMPLES
 --------
 You are in the middle of a refactoring session and your boss comes in and
-- 
2.51.0

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

[Michal Suchanek]

Signed-off-by: Michal Suchanek <msuchanek@suse.de>
---
v2: Do not make the checked out repository hidden
---
 Documentation/git-worktree.adoc | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index a580f4c072..e7bf0ea8e0 100644
--- 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
+------------
+
 BUGS
 ----
 Multiple checkout in general is still experimental, and the support
-- 
2.51.0

Re: [PATCH 1/2] doc: git-worktree: Link to examples

[Michal Suchánek]

Hello,

On Sun, Oct 05, 2025 at 10:52:51PM +0200, Jean-Noël AVILA wrote:
> 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. 

Seems it would not conflict too badly, at least if your series is
applied first.

Thanks

Michal

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

Re: [PATCH v2 1/2] doc: git-worktree: Link to examples

[Eric Sunshine]

On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek <msuchanek@suse.de> wrote:
> doc: git-worktree: Link to examples
>
> Also add advice to put new worktrees outside of existing ones.

The subject and body of the commit message are backward. The really
important change made by this patch is that it is adding a new
recommendation; linking to the examples is just a handy byproduct of
that change. Hence, the subject of the patch should mention the new
recommendation, not the link to the examples. In fact, if you frame it
that way, then the commit message doesn't even need to talk about the
link to examples.

Also, a reviewer of v1 mentioned that the subject should use lowercase
"link" rather than "Link".

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

I'm quite negative toward this documentation change for the same
reason[*] that I was very much against adding a warning message
(reproduced here):

    Regarding issuing warnings: I'm not fond of the idea. 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). The only minor downside of the practice (if one considers
    it a downside) is an aesthetic one: having to update ".gitignore"
    or ".git/info/exclude", or to simply consider them "visual noise"
    in git-status output and skip over them when scanning the output.

The big problem I have with this change is that the newly-added advice
is not backed up by concrete reasoning -- worse, it gives *no* reasons
at all -- thus it leaves the reader hanging. As mentioned above, there
is no technical reason to avoid creating new worktrees in the main
worktree, which means that whatever reasons you might have for
recommending against the practice must be subjective, but the reader
has no way of guessing what those reasons might be.

I *might* be a little less negative toward this documentation change
if you presented the new recommendation accompanied by a list of pros
and cons which, although subjective, are nevertheless somehow
convincing to the reader. However, aside from the very minor aesthetic
inconvenience of seeing a linked worktree shown as untracked, I
personally can't come up with any list of pros and cons. Unless you or
someone else can do better, I think this patch should be dropped
altogether.

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

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

[Eric Sunshine]

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.

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

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

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

This message by Eric was with many good points, including the above.

Should I be expecting an update of these patches, hopefully bringing
them closer to the finish line?  I'll tentatively mark the topic in
my "What's cooking" draft as expecting a reroll.

Thanks.

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

[Michal Suchánek]

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/

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

[Eric Sunshine]

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.

As for first creating a directory to contain the repository and the
worktrees, I purposely omitted that step in the example since I
assume/hope that we don't need to hand-hold the user to that extent.

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

[Johannes Schindelin]

Hi Eric,

On Wed, 1 Oct 2025, Eric Sunshine wrote:

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

And indeed I do, and continue to do so because the counter arguments in
that email discussion looked quite weak to me.

In the one instance where I heeded that well-meant advice to create
worktrees outside of my main worktree, I lost work when I had cleaned up
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`.

Ciao,
Johannes

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

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

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

Ouch, that is a tough one.  It is very hard to interfere and stop
your "rm -fr" based on what Git could find (in other words, your
"rm" lacks the "pre-something" hook).

Of course, an argument can be made that you should have also asked
`git worktree list` if there are other worktrees, in addition to
asking `git status`, but I wonder if it would have helped to have
the information in the `git status` output so that we can always
trust that it is sufficient to ask a single command without doing
anything else?  As "separate worktrees" is a feature to allow users
to more or less independently work in each separate worktree,
without having to worry about what they are doing in the other
worktrees, cramming too much into `git status` would degrade the
end-user experience and it takes a fine balance.

I think that one of the reasons why the "outside the working tree"
layout is recommended is to prevent us from "git add ." (or other
overly wide pathspec) to accidentally add these embedded worktrees
to the main project, but such a mistake is at least not as
destructive as "rm -fr".

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

[Michal Suchánek]

On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:
> 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.

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.

> As for first creating a directory to contain the repository and the
> worktrees, I purposely omitted that step in the example since I
> assume/hope that we don't need to hand-hold the user to that extent.

Its much easier to reove superluous parts from the example than adding
patrs that were omitted.

Thanks

Michal

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

[Eric Sunshine]

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/

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

[Michal Suchánek]

On Tue, Sep 30, 2025 at 08:47:11AM -0700, Junio C Hamano wrote:
> 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.

And that's what the existing example shows.

Thanks

Michal