Eric Sunshine [off-list ref] writes:

On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano [off-list ref] wrote:

quoted

I wonder if this would work better.

        `prune`::
                Remove worktree information in `$GIT_DIR/worktrees`
                only, without touching the working tree.  This is
                often needed when the working tree is lost (e.g.,
                the user manually removed it) and the worktree
                information has become dangling.

Yes, this is a useful improvement, although one part confuses me (and
I would omit it). In particular, if the working tree is lost, thus the
`$GIT_DIR/worktrees` is dangling ought to be removed, then I'm not
sure why you would say "without touching the working tree" (which is
already lost).

Ahh, I somehow thought you can say "git worktree prune <worktree>"
to remove only the control information while the working tree is
still there, sort of "orphaning" the working tree from the main
repository.  But things do not work that way.

You're right that "without touching the working tree" part is
misleading and redundant.  And it is not "this is often needed"; it
is the _only_ scenario the operation makes sense.

	`prune`::
		Remove worktree information in `$GIT_DIR/worktrees`
		for worktrees whose working trees are missing.
		Useful after manually removing a working tree that
		is no longer needed (but use "git worktree remove"
		next time you want to do so).  Also if you _moved_ a
		working tree elsewhere to cause the worktree
		information dangling, see "git worktree repair" to
		reconnect the worktree to the new working tree
		location.

perhaps?