patchworktree: clarify --expire applies to missing worktrees

From: Sam Bostock <sam.bostock@shopify.com>

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>
---
    worktree: clarify --expire applies to missing worktrees

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v1
Pull-Request: https://github.com/git/git/pull/2135

 Documentation/git-worktree.adoc | 2 +-
 builtin/worktree.c              | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget <gitgitgadget@gmail.com> wrote:

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

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

Same comment:

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

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

Eric Sunshine <sunshine@sunshineco.com> writes:

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 <gitster@pobox.com> wrote:

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 <sunshine@sunshineco.com> writes:

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 <gitster@pobox.com> wrote:

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.

Changes from v1:

 * Use 'prune' instead of 'expire' when describing the --expire option's
   effect on missing worktrees, since the terminology is clearer.

Sam Bostock (2):
  worktree: clarify --expire applies to missing worktrees
  worktree: use 'prune' instead of 'expire' in help text

 Documentation/git-worktree.adoc | 2 +-
 builtin/worktree.c              | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

base-commit: c4a0c8845e2426375ad257b6c221a3a7d92ecfda
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v2
Pull-Request: https://github.com/git/git/pull/2135

Range-diff vs v1:

 1:  ddd4191ecb = 1:  ddd4191ecb worktree: clarify --expire applies to missing worktrees
 -:  ---------- > 2:  ff4732b72a worktree: use 'prune' instead of 'expire' in help text

From: Sam Bostock <sam.bostock@shopify.com>

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>
---
 Documentation/git-worktree.adoc | 2 +-
 builtin/worktree.c              | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

"Sam Bostock via GitGitGadget" <gitgitgadget@gmail.com> writes:

Well analyzed and described.

We phrase it more like "Update the help text and documentation to ...", as if you are asking somebody sitting on the keyboard to make that change.

"expire" -> "prune" or "remove". As the user already said "prune" when they run "git worktree prune -h", using a different and more common verb "remove" to explain the action might be more helpful than saying "prune".

Thanks.

From: Sam Bostock <sam.bostock@shopify.com>

Use 'prune' instead of 'expire' when describing the --expire option's effect on missing worktrees, since the terminology is clearer.

Signed-off-by: Sam Bostock <sam@sambostock.ca>
---
 Documentation/git-worktree.adoc | 2 +-
 builtin/worktree.c              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

"Sam Bostock via GitGitGadget" <gitgitgadget@gmail.com> writes:

Does this v2 use exactly the same commit from v1 as [1/2] and add this [2/2] as if you are saying "oops, the previous one missed something we should have updated but forgot/failed to do so; here is an improvement?"

Don't. Unless the change you deliberately made as a follow-up improvement is logically separate and significant, that is.

Thanks.

"Sam Bostock via GitGitGadget" <gitgitgadget@gmail.com> writes:

I think we have been expecting a reroll of this topic. Any further progress?

From: Sam Bostock <sam.bostock@shopify.com>

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.

Update the help text and documentation to consistently describe these as "missing worktrees", and use "prune" instead of "expire" when describing the effect on missing worktrees since the terminology is clearer.

While at it, expand the description of the "prune" subcommand itself to better explain what it does and when to use it, as suggested by Junio.

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Sam Bostock <sam@sambostock.ca>
---
    worktree: clarify --expire applies to missing worktrees
    
    Changes from v2:
    
     * Squash into a single commit
     * Expand the prune subcommand description per Junio's suggestion
    
    Changes from v1:
    
     * Use "prune" instead of "expire" in help text

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v3
Pull-Request: https://github.com/git/git/pull/2135

Range-diff vs v2:

 1:  ddd4191ecb ! 1:  a4483d9a20 worktree: clarify --expire applies to missing worktrees
     @@ Metadata
      Author: Sam Bostock <sam.bostock@shopify.com>
      
       ## Commit message ##
     -    worktree: clarify --expire applies to missing worktrees
     +    worktree: clarify that --expire only affects missing worktrees
      
     -    The `--expire` option for `git worktree list` and `git worktree prune`
     +    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".
     +    Update the help text and documentation to consistently describe these
     +    as "missing worktrees", and use "prune" instead of "expire" when
     +    describing the effect on missing worktrees since the terminology is
     +    clearer.
      
     +    While at it, expand the description of the "prune" subcommand itself
     +    to better explain what it does and when to use it, as suggested by
     +    Junio.
     +
     +    Helped-by: Eric Sunshine <sunshine@sunshineco.com>
     +    Helped-by: Junio C Hamano <gitster@pobox.com>
          Signed-off-by: Sam Bostock <sam@sambostock.ca>
      
       ## Documentation/git-worktree.adoc ##
     +@@ Documentation/git-worktree.adoc: with linked worktrees if you move the main worktree manually.)
     + 
     + `prune`::
     + 
     +-Prune worktree information in `$GIT_DIR/worktrees`.
     ++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 causing the worktree information to become
     ++dangling, see "git worktree repair" to reconnect the worktree to
     ++the new working tree location.
     + 
     + `remove`::
     + 
      @@ Documentation/git-worktree.adoc: mismatch, even if the links are correct.
       With `list`, output additional information about worktrees (see below).
       
       `--expire <time>`::
      -	With `prune`, only expire unused worktrees older than _<time>_.
     -+	With `prune`, only expire missing worktrees older than _<time>_.
     ++	With `prune`, only prune missing worktrees if older than _<time>_.
       +
       With `list`, annotate missing worktrees as prunable if they are older than
       _<time>_.
     @@ builtin/worktree.c: static int prune(int ac, const char **av, const char *prefix
       		OPT__VERBOSE(&verbose, N_("report pruned working trees")),
       		OPT_EXPIRY_DATE(0, "expire", &expire,
      -				N_("expire working trees older than <time>")),
     -+				N_("expire missing working trees older than <time>")),
     ++				N_("prune missing working trees older than <time>")),
       		OPT_END()
       	};
       
 2:  ff4732b72a < -:  ---------- worktree: use 'prune' instead of 'expire' in help text

 Documentation/git-worktree.adoc | 10 ++++++++--
 builtin/worktree.c              |  4 ++--
 2 files changed, 10 insertions(+), 4 deletions(-)

On Wed, Jan 28, 2026 at 12:39 AM Sam Bostock via GitGitGadget <gitgitgadget@gmail.com> wrote:

Thanks for re-rolling this patch. I think this version addresses all the review comments from Junio and myself and is ready to be merged to "next".