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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 11, 2025, 04:40 UTC
Message-ID: <CAPig+cQRHp7A=gtSkrVS4_EvZ9PyqBOdGGHcEajfLPE=qU4uDQ@mail.gmail.com>
In-Reply-To: <6477f32e23e732fdcc5a9585cc945db8f13d736e.1760115862.git.msuchanek@suse.de>

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

Show 6 quoted lines

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