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

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