From: Jean-Noël AVILA <avila.jn@gmail.com>
Date: Sun, 05 Oct 2025 20:52:51 GMT
Subject: Re: [PATCH 1/2] doc: git-worktree: Link to examples
Message-ID: <6043158.DvuYhMxLoT@cayenne>
In-Reply-To: <a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de>

On Thursday, 2 October 2025 17:51:34 CEST 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>>

Please use the form <<EXAMPLES,EXAMPLES>> in order to let the translators also 
change the cross-link text in their language.

Also, the <path> placeholder should be formatted as _<path>_. For your 
information, I'm right in the middle of pushing the conversion of git-
worktree.adoc to the new synopsis style. 

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

As noted by others, please put the block anchors on a dedicated line, out of 
the translation scope.

Thank you.