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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 1, 2025, 21:29 UTC
Message-ID: <CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com>
In-Reply-To: <xmqqa52a1h6x.fsf@gitster.g>

On Wed, Oct 1, 2025 at 4:49 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 15 quoted lines

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