From: Eric Sunshine <sunshine@sunshineco.com>
Date: Fri, 19 Dec 2025 15:11:36 GMT
Subject: Re: [PATCH] worktree: clarify --expire applies to missing worktrees
Message-ID: <CAPig+cTC8ROsf-cOhUcxovUOcQ47As496SAm7FcEFnzGChhLww@mail.gmail.com>
In-Reply-To: <pull.2135.git.git.1766156407442.gitgitgadget@gmail.com>

On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget
<gitgitgadget@gmail.com> 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 <sam@sambostock.ca>
> ---

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