From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 02 Oct 2025 17:44:06 GMT
Subject: Re: [PATCH 1/2] doc: git-worktree: Link to examples
Message-ID: <xmqqo6qpw655.fsf@gitster.g>
In-Reply-To: <a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de>

Michal Suchanek <msuchanek@suse.de> writes:

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

I am wondering if we cram more information in "For best results", by
adding the "otherwise...".  Here is my (failed) attempt.

    Use <path> outside of your working tree and existing worktrees
    (see <<EXAMPLES>>); otherwise your new worktree will appear as
    an untracked directory.

I say "failed" as the above phrasing makes it sound as if that
untracked-ness is the only downside, and also by omitting "advised",
it makes it sound as if there is no upside (other than inertia) in
doing so.

So, I'll (atleast tentatively) queue yours as-is.

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

cf. https://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/

IOW, we probably should write this more like ...

        +[[EXAMPLES]]
         EXAMPLES
         --------

Thanks.