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

[Eric Sunshine <sunshine@sunshineco.com>]

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/