From: Michal Suchánek <msuchanek@suse.de>
Date: Thu, 02 Oct 2025 18:55:42 GMT
Subject: Re: [PATCH 1/2] doc: git-worktree: Link to examples
Message-ID: <aN7KrnF0KohlKtuN@kitsune.suse.cz>
In-Reply-To: <xmqqo6qpw655.fsf@gitster.g>

On Thu, Oct 02, 2025 at 10:44:06AM -0700, Junio C Hamano wrote:
> 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.

Yes, I did not want to make this explanation too long. Spelling out all
the details would take multiple paragraphs but it's probably not worth
being that verbose.

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

That could use correcting in the the asciidoc documentation. The
examples there put the anchor on the same line.

That's probably where the repeated problem of this formatting is coming
from.

The other thing is that if you used sections you would get anchors
automatically for free avoiding this problem altogether.

Thanks

Michal