On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget
<[email protected]> wrote:
> The `--expire` option for `git worktree list` and `git worktree prune`
> only affects worktrees whose working directory path no longer exists.
> The help text did not make this clear, and the documentation
> inconsistently used "unused" for prune but "missing" for list.
>
> This updates the help text and documentation to consistently describe
> these as "missing worktrees".
>
> Signed-off-by: Sam Bostock <[email protected]>
> ---

This change makes sense to me; it certainly helps clarify the meaning.
One or two comments (below)...

> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> @@ -271,7 +271,7 @@ mismatch, even if the links are correct.
>  `--expire <time>`::
> -       With `prune`, only expire unused worktrees older than _<time>_.
> +       With `prune`, only expire missing worktrees older than _<time>_.

Rather than saying that this "expires", I wonder if it would be even
clearer to say that it prunes or removes information about missing
worktrees. Something like:

    With `prune`, only prune missing worktrees if older than _<time>_.

> diff --git a/builtin/worktree.c b/builtin/worktree.c
> @@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,
>                 OPT_EXPIRY_DATE(0, "expire", &expire,
> -                               N_("expire working trees older than <time>")),
> +                               N_("expire missing working trees older than <time>")),

Same comment:

    N_("prune missing working trees older than <time>")),

> @@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,
>                 OPT_EXPIRY_DATE(0, "expire", &expire,
> -                               N_("add 'prunable' annotation to worktrees older than <time>")),
> +                               N_("add 'prunable' annotation to missing worktrees older than <time>")),

This one is fine as-is (with your change applied).

Eric Sunshine <[email protected]> writes:

> On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget
> <[email protected]> wrote:
>> The `--expire` option for `git worktree list` and `git worktree prune`
>> only affects worktrees whose working directory path no longer exists.
>> The help text did not make this clear, and the documentation
>> inconsistently used "unused" for prune but "missing" for list.
>>
>> This updates the help text and documentation to consistently describe
>> these as "missing worktrees".
>>
>> Signed-off-by: Sam Bostock <[email protected]>
>> ---
>
> This change makes sense to me; it certainly helps clarify the meaning.
> One or two comments (below)...
>
>> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
>> @@ -271,7 +271,7 @@ mismatch, even if the links are correct.
>>  `--expire <time>`::
>> -       With `prune`, only expire unused worktrees older than _<time>_.
>> +       With `prune`, only expire missing worktrees older than _<time>_.
>
> Rather than saying that this "expires", I wonder if it would be even
> clearer to say that it prunes or removes information about missing
> worktrees. Something like:
>
>     With `prune`, only prune missing worktrees if older than _<time>_.

Yup, and a very related tangent.

The entry for 'prune' itself reads like this:

        `prune`::
        Prune worktree information in `$GIT_DIR/worktrees`.

In general (see recent topics by Julia, for example), it is risky to
explain option DOSOMETHING in terms of the same verb dosomething.
It may serve as a memory aid, but at the same time, if the verb
dosomething is not in everyday lingo, can mean different things, or
we use it a bit differently from the common uses, explaining the
option using a more familiar verb may be helpful, especially to non
native audiences.

In the context of *removing* a worktree, there are potentially three
situations.

 (1) the user has both the working tree and the control info
     healthy, and they no longer needs it (i.e., "git worktree
     remove")

 (2) the user still has the working tree, but somehow lost the
     control info.  Git does not have a direct way to remove the
     working tree and we expect the user to do "rm -rf" the
     remaining working tree.

 (3) the user somehow has lost the working tree but the control info
     remains, and they want to remove the useless entry from "git
     worktree list".  This is what "git worktree prune" is about.

It would have been nice if we could arrange the situation (2) and
(3) to be impossible to get into, but running "rm -rf" on random
directories is not a privileged operation on most systems, so the
users can easily get into them, especially (3).  It would be very
nice if we can find a better wording than "Prune worktree info" to
explain the 'prune' operation.

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.

On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <[email protected]> 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).

Eric Sunshine <[email protected]> writes:

> On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <[email protected]> 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?

On Sat, Dec 20, 2025 at 2:31 AM Junio C Hamano <[email protected]> wrote:
> Eric Sunshine <[email protected]> writes:
> > On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <[email protected]> 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.