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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Oct 2, 2025, 17:42 UTC
Message-ID: <8fe29842-eb27-47ea-877b-2bfbb3a03bff@app.fastmail.com>
In-Reply-To: <a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de>

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

Show 17 quoted lines

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

Show 13 quoted lines

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

Show 5 quoted lines

>  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