From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sat, 20 Dec 2025 08:23:01 GMT
Subject: Re: [PATCH] worktree: clarify --expire applies to missing worktrees
Message-ID: <CAPig+cRa5EsN-=WcjEhSPpTLu=R=7uLwHL9OKLdAhwuxmsA6Og@mail.gmail.com>
In-Reply-To: <xmqqfr95txrz.fsf@gitster.g>

On Sat, Dec 20, 2025 at 2:31 AM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <gitster@pobox.com> wrote:
> >> 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?

Yes, this sounds fine. This information is discussed in the
DESCRIPTION section of the document, but it doesn't hurt to flesh it
out here, as well.