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

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

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

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

>  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