On Wed, Oct 1, 2025 at 4:49 PM Junio C Hamano [off-list ref] wrote:

Sergey Organov [off-list ref] writes:

quoted

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.