Re: [PATCH 1/2] doc: git-worktree: Link to examples
From: Junio C Hamano <hidden>
Date: 2025-10-02 17:44:09
Michal Suchanek [off-list ref] writes:
quoted hunk
Also add advice to put new worktrees outside of existing ones. Signed-off-by: Michal Suchanek <redacted> --- 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.
quoted hunk
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/ (local) IOW, we probably should write this more like ... +[[EXAMPLES]] EXAMPLES -------- Thanks.