worktree: clarify that --expire only affects missing worktrees

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Sam Bostock committed Jan 28, 2026 at 05:39 UTC 6f5ca70580444e61231ad33de0aac81d2420d523
2 files changed +10 -4
Documentation/git-worktree.adoc
+8 -2
@@ -131,7 +131,13 @@ with linked worktrees if you move the main worktree manually.)
131
132 `prune`::
133
134 -Prune worktree information in `$GIT_DIR/worktrees`.
134 +Remove worktree information in `$GIT_DIR/worktrees` for worktrees
135 +whose working trees are missing. Useful after manually removing
136 +a working tree that is no longer needed (but use "git worktree
137 +remove" next time you want to do so). Also, if you _moved_ a
138 +working tree elsewhere causing the worktree information to become
139 +dangling, see "git worktree repair" to reconnect the worktree to
140 +the new working tree location.
141
142 `remove`::
143
@@ -271,7 +277,7 @@ mismatch, even if the links are correct.
277 With `list`, output additional information about worktrees (see below).
278
279 `--expire <time>`::
274 - With `prune`, only expire unused worktrees older than _<time>_.
280 + With `prune`, only prune missing worktrees if older than _<time>_.
281 +
282 With `list`, annotate missing worktrees as prunable if they are older than
283 _<time>_.
builtin/worktree.c
+2 -2
@@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,
252 OPT__DRY_RUN(&show_only, N_("do not remove, show only")),
253 OPT__VERBOSE(&verbose, N_("report pruned working trees")),
254 OPT_EXPIRY_DATE(0, "expire", &expire,
255 - N_("expire working trees older than <time>")),
255 + N_("prune missing working trees older than <time>")),
256 OPT_END()
257 };
258
@@ -1063,7 +1063,7 @@ static int list(int ac, const char **av, const char *prefix,
1063 OPT_BOOL(0, "porcelain", &porcelain, N_("machine-readable output")),
1064 OPT__VERBOSE(&verbose, N_("show extended annotations and reasons, if available")),
1065 OPT_EXPIRY_DATE(0, "expire", &expire,
1066 - N_("add 'prunable' annotation to worktrees older than <time>")),
1066 + N_("add 'prunable' annotation to missing worktrees older than <time>")),
1067 OPT_SET_INT('z', NULL, &line_terminator,
1068 N_("terminate records with a NUL character"), '\0'),
1069 OPT_END()