Skip to content

worktree: clarify --expire applies to missing worktrees #2135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sambostock wants to merge 2 commits into
base: master
Choose a base branch
from
+3 −3
Open

worktree: clarify --expire applies to missing worktrees #2135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddd4191
worktree: clarify --expire applies to missing worktrees
sambostock Dec 19, 2025
ff4732b
worktree: use 'prune' instead of 'expire' in help text
sambostock Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Documentation/git-worktree.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ mismatch, even if the links are correct.
With `list`, output additional information about worktrees (see below).
Copy link

@gitgitgadget-git gitgitgadget-git bot Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Sam Bostock via GitGitGadget" <[email protected]> writes:

> From: Sam Bostock <[email protected]>
>
> 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.

Well analyzed and described.

> This updates the help text and documentation to consistently describe
> these as "missing worktrees".

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.

> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index fbdaf2eb2e..82fcbfeccf 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,
>  		OPT__DRY_RUN(&show_only, N_("do not remove, show only")),
>  		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>")),

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

Copy link

@gitgitgadget-git gitgitgadget-git bot Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Sam Bostock via GitGitGadget" <[email protected]> writes:

> From: Sam Bostock <[email protected]>
>
> 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 <[email protected]>
> ---
>  Documentation/git-worktree.adoc | 2 +-
>  builtin/worktree.c              | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)

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.

Copy link

@dhukilabi-lab dhukilabi-lab Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All vpn trel


`--expire <time>`::
With `prune`, only expire unused 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>_.
Expand Down
4 changes: 2 additions & 2 deletions builtin/worktree.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,
OPT__DRY_RUN(&show_only, N_("do not remove, show only")),
OPT__VERBOSE(&verbose, N_("report pruned working trees")),
OPT_EXPIRY_DATE(0, "expire", &expire,
N_("expire working trees older than <time>")),
N_("prune missing working trees older than <time>")),
OPT_END()
};

Expand Down Expand Up @@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,
OPT_BOOL(0, "porcelain", &porcelain, N_("machine-readable output")),
OPT__VERBOSE(&verbose, N_("show extended annotations and reasons, if available")),
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>")),
OPT_SET_INT('z', NULL, &line_terminator,
N_("terminate records with a NUL character"), '\0'),
OPT_END()
Expand Down
Loading