{"thread":{"id":"64656","subject":"[PATCH] worktree: clarify --expire applies to missing worktrees","startedAt":"2025-12-19T15:00:12Z","lastAt":"2026-01-30T00:30:07Z","messageCount":14,"participants":["Sam Bostock via GitGitGadget","Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"532554","messageId":"pull.2135.git.git.1766156407442.gitgitgadget@gmail.com","threadId":"64656","inReplyTo":null,"subject":"[PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Sam Bostock via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T15:00:07Z","receivedAt":"2025-12-19T15:00:12Z","isPatch":true,"sender":{"key":"sam.bostock@shopify.com","avatar":"https://avatars.githubusercontent.com/u/8219340?v=4"},"body":"From: Sam Bostock <sam.bostock@shopify.com>\n\nThe `--expire` option for `git worktree list` and `git worktree prune`\nonly affects worktrees whose working directory path no longer exists.\nThe help text did not make this clear, and the documentation\ninconsistently used \"unused\" for prune but \"missing\" for list.\n\nThis updates the help text and documentation to consistently describe\nthese as \"missing worktrees\".\n\nSigned-off-by: Sam Bostock <sam@sambostock.ca>\n---\n    worktree: clarify --expire applies to missing worktrees\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v1\nPull-Request: https://github.com/git/git/pull/2135\n\n Documentation/git-worktree.adoc | 2 +-\n builtin/worktree.c              | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex f272f79783..402d363064 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -271,7 +271,7 @@ mismatch, even if the links are correct.\n With `list`, output additional information about worktrees (see below).\n \n `--expire <time>`::\n-\tWith `prune`, only expire unused worktrees older than _<time>_.\n+\tWith `prune`, only expire missing worktrees older than _<time>_.\n +\n With `list`, annotate missing worktrees as prunable if they are older than\n _<time>_.\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..82fcbfeccf 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n \t\tOPT__DRY_RUN(&show_only, N_(\"do not remove, show only\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"expire working trees older than <time>\")),\n+\t\t\t\tN_(\"expire missing working trees older than <time>\")),\n \t\tOPT_END()\n \t};\n \n@@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,\n \t\tOPT_BOOL(0, \"porcelain\", &porcelain, N_(\"machine-readable output\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"show extended annotations and reasons, if available\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"add 'prunable' annotation to worktrees older than <time>\")),\n+\t\t\t\tN_(\"add 'prunable' annotation to missing worktrees older than <time>\")),\n \t\tOPT_SET_INT('z', NULL, &line_terminator,\n \t\t\t    N_(\"terminate records with a NUL character\"), '\\0'),\n \t\tOPT_END()\n\nbase-commit: c4a0c8845e2426375ad257b6c221a3a7d92ecfda\n-- \ngitgitgadget\n"},{"id":"532556","messageId":"CAPig+cTC8ROsf-cOhUcxovUOcQ47As496SAm7FcEFnzGChhLww@mail.gmail.com","threadId":"64656","inReplyTo":"pull.2135.git.git.1766156407442.gitgitgadget@gmail.com","subject":"Re: [PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-12-19T15:11:36Z","receivedAt":"2025-12-19T15:11:48Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> The `--expire` option for `git worktree list` and `git worktree prune`\n> only affects worktrees whose working directory path no longer exists.\n> The help text did not make this clear, and the documentation\n> inconsistently used \"unused\" for prune but \"missing\" for list.\n>\n> This updates the help text and documentation to consistently describe\n> these as \"missing worktrees\".\n>\n> Signed-off-by: Sam Bostock <sam@sambostock.ca>\n> ---\n\nThis change makes sense to me; it certainly helps clarify the meaning.\nOne or two comments (below)...\n\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> @@ -271,7 +271,7 @@ mismatch, even if the links are correct.\n>  `--expire <time>`::\n> -       With `prune`, only expire unused worktrees older than _<time>_.\n> +       With `prune`, only expire missing worktrees older than _<time>_.\n\nRather than saying that this \"expires\", I wonder if it would be even\nclearer to say that it prunes or removes information about missing\nworktrees. Something like:\n\n    With `prune`, only prune missing worktrees if older than _<time>_.\n\n> diff --git a/builtin/worktree.c b/builtin/worktree.c\n> @@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n>                 OPT_EXPIRY_DATE(0, \"expire\", &expire,\n> -                               N_(\"expire working trees older than <time>\")),\n> +                               N_(\"expire missing working trees older than <time>\")),\n\nSame comment:\n\n    N_(\"prune missing working trees older than <time>\")),\n\n> @@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,\n>                 OPT_EXPIRY_DATE(0, \"expire\", &expire,\n> -                               N_(\"add 'prunable' annotation to worktrees older than <time>\")),\n> +                               N_(\"add 'prunable' annotation to missing worktrees older than <time>\")),\n\nThis one is fine as-is (with your change applied).\n"},{"id":"532561","messageId":"pull.2135.v2.git.git.1766168169.gitgitgadget@gmail.com","threadId":"64656","inReplyTo":"pull.2135.git.git.1766156407442.gitgitgadget@gmail.com","subject":"[PATCH v2 0/2] worktree: clarify --expire applies to missing worktrees","fromName":"Sam Bostock via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:16:07Z","receivedAt":"2025-12-19T18:16:11Z","isPatch":true,"sender":{"key":"sam.bostock@shopify.com","avatar":"https://avatars.githubusercontent.com/u/8219340?v=4"},"body":"Changes from v1:\n\n * Use 'prune' instead of 'expire' when describing the --expire option's\n   effect on missing worktrees, since the terminology is clearer.\n\nSam Bostock (2):\n  worktree: clarify --expire applies to missing worktrees\n  worktree: use 'prune' instead of 'expire' in help text\n\n Documentation/git-worktree.adoc | 2 +-\n builtin/worktree.c              | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\n\nbase-commit: c4a0c8845e2426375ad257b6c221a3a7d92ecfda\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v2\nPull-Request: https://github.com/git/git/pull/2135\n\nRange-diff vs v1:\n\n 1:  ddd4191ecb = 1:  ddd4191ecb worktree: clarify --expire applies to missing worktrees\n -:  ---------- > 2:  ff4732b72a worktree: use 'prune' instead of 'expire' in help text\n\n-- \ngitgitgadget\n"},{"id":"532562","messageId":"ddd4191ecb391e10bf4b123f699384a3d609b4a8.1766168169.git.gitgitgadget@gmail.com","threadId":"64656","inReplyTo":"pull.2135.v2.git.git.1766168169.gitgitgadget@gmail.com","subject":"[PATCH v2 1/2] worktree: clarify --expire applies to missing worktrees","fromName":"Sam Bostock via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:16:08Z","receivedAt":"2025-12-19T18:16:12Z","isPatch":true,"sender":{"key":"sam.bostock@shopify.com","avatar":"https://avatars.githubusercontent.com/u/8219340?v=4"},"body":"From: Sam Bostock <sam.bostock@shopify.com>\n\nThe `--expire` option for `git worktree list` and `git worktree prune`\nonly affects worktrees whose working directory path no longer exists.\nThe help text did not make this clear, and the documentation\ninconsistently used \"unused\" for prune but \"missing\" for list.\n\nThis updates the help text and documentation to consistently describe\nthese as \"missing worktrees\".\n\nSigned-off-by: Sam Bostock <sam@sambostock.ca>\n---\n Documentation/git-worktree.adoc | 2 +-\n builtin/worktree.c              | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex f272f79783..402d363064 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -271,7 +271,7 @@ mismatch, even if the links are correct.\n With `list`, output additional information about worktrees (see below).\n \n `--expire <time>`::\n-\tWith `prune`, only expire unused worktrees older than _<time>_.\n+\tWith `prune`, only expire missing worktrees older than _<time>_.\n +\n With `list`, annotate missing worktrees as prunable if they are older than\n _<time>_.\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..82fcbfeccf 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n \t\tOPT__DRY_RUN(&show_only, N_(\"do not remove, show only\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"expire working trees older than <time>\")),\n+\t\t\t\tN_(\"expire missing working trees older than <time>\")),\n \t\tOPT_END()\n \t};\n \n@@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,\n \t\tOPT_BOOL(0, \"porcelain\", &porcelain, N_(\"machine-readable output\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"show extended annotations and reasons, if available\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"add 'prunable' annotation to worktrees older than <time>\")),\n+\t\t\t\tN_(\"add 'prunable' annotation to missing worktrees older than <time>\")),\n \t\tOPT_SET_INT('z', NULL, &line_terminator,\n \t\t\t    N_(\"terminate records with a NUL character\"), '\\0'),\n \t\tOPT_END()\n-- \ngitgitgadget\n\n"},{"id":"532563","messageId":"ff4732b72a0d8c97c668167308039918362ffb9c.1766168169.git.gitgitgadget@gmail.com","threadId":"64656","inReplyTo":"pull.2135.v2.git.git.1766168169.gitgitgadget@gmail.com","subject":"[PATCH v2 2/2] worktree: use 'prune' instead of 'expire' in help text","fromName":"Sam Bostock via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:16:09Z","receivedAt":"2025-12-19T18:16:14Z","isPatch":true,"sender":{"key":"sam.bostock@shopify.com","avatar":"https://avatars.githubusercontent.com/u/8219340?v=4"},"body":"From: Sam Bostock <sam.bostock@shopify.com>\n\nUse 'prune' instead of 'expire' when describing the --expire option's\neffect on missing worktrees, since the terminology is clearer.\n\nSigned-off-by: Sam Bostock <sam@sambostock.ca>\n---\n Documentation/git-worktree.adoc | 2 +-\n builtin/worktree.c              | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 402d363064..29b43925f3 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -271,7 +271,7 @@ mismatch, even if the links are correct.\n With `list`, output additional information about worktrees (see below).\n \n `--expire <time>`::\n-\tWith `prune`, only expire missing worktrees older than _<time>_.\n+\tWith `prune`, only prune missing worktrees if older than _<time>_.\n +\n With `list`, annotate missing worktrees as prunable if they are older than\n _<time>_.\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 82fcbfeccf..3d6547c23b 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n \t\tOPT__DRY_RUN(&show_only, N_(\"do not remove, show only\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"expire missing working trees older than <time>\")),\n+\t\t\t\tN_(\"prune missing working trees older than <time>\")),\n \t\tOPT_END()\n \t};\n \n-- \ngitgitgadget\n"},{"id":"532573","messageId":"xmqq4iplvhao.fsf@gitster.g","threadId":"64656","inReplyTo":"CAPig+cTC8ROsf-cOhUcxovUOcQ47As496SAm7FcEFnzGChhLww@mail.gmail.com","subject":"Re: [PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-20T05:44:15Z","receivedAt":"2025-12-20T05:44:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine <sunshine@sunshineco.com> writes:\n\n> On Fri, Dec 19, 2025 at 10:01 AM Sam Bostock via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>> The `--expire` option for `git worktree list` and `git worktree prune`\n>> only affects worktrees whose working directory path no longer exists.\n>> The help text did not make this clear, and the documentation\n>> inconsistently used \"unused\" for prune but \"missing\" for list.\n>>\n>> This updates the help text and documentation to consistently describe\n>> these as \"missing worktrees\".\n>>\n>> Signed-off-by: Sam Bostock <sam@sambostock.ca>\n>> ---\n>\n> This change makes sense to me; it certainly helps clarify the meaning.\n> One or two comments (below)...\n>\n>> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n>> @@ -271,7 +271,7 @@ mismatch, even if the links are correct.\n>>  `--expire <time>`::\n>> -       With `prune`, only expire unused worktrees older than _<time>_.\n>> +       With `prune`, only expire missing worktrees older than _<time>_.\n>\n> Rather than saying that this \"expires\", I wonder if it would be even\n> clearer to say that it prunes or removes information about missing\n> worktrees. Something like:\n>\n>     With `prune`, only prune missing worktrees if older than _<time>_.\n\nYup, and a very related tangent.\n\nThe entry for 'prune' itself reads like this:\n\n        `prune`::\n        Prune worktree information in `$GIT_DIR/worktrees`.\n\nIn general (see recent topics by Julia, for example), it is risky to\nexplain option DOSOMETHING in terms of the same verb dosomething.\nIt may serve as a memory aid, but at the same time, if the verb\ndosomething is not in everyday lingo, can mean different things, or\nwe use it a bit differently from the common uses, explaining the\noption using a more familiar verb may be helpful, especially to non\nnative audiences.\n\nIn the context of *removing* a worktree, there are potentially three\nsituations.\n\n (1) the user has both the working tree and the control info\n     healthy, and they no longer needs it (i.e., \"git worktree\n     remove\")\n\n (2) the user still has the working tree, but somehow lost the\n     control info.  Git does not have a direct way to remove the\n     working tree and we expect the user to do \"rm -rf\" the\n     remaining working tree.\n\n (3) the user somehow has lost the working tree but the control info\n     remains, and they want to remove the useless entry from \"git\n     worktree list\".  This is what \"git worktree prune\" is about.\n\nIt would have been nice if we could arrange the situation (2) and\n(3) to be impossible to get into, but running \"rm -rf\" on random\ndirectories is not a privileged operation on most systems, so the\nusers can easily get into them, especially (3).  It would be very\nnice if we can find a better wording than \"Prune worktree info\" to\nexplain the 'prune' operation.\n\nI wonder if this would work better.\n\n\t`prune`::\n\t\tRemove worktree information in `$GIT_DIR/worktrees`\n\t\tonly, without touching the working tree.  This is\n\t\toften needed when the working tree is lost (e.g.,\n\t\tthe user manually removed it) and the worktree\n\t\tinformation has become dangling.\n\n"},{"id":"532575","messageId":"xmqqqzspu1nn.fsf@gitster.g","threadId":"64656","inReplyTo":"ddd4191ecb391e10bf4b123f699384a3d609b4a8.1766168169.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/2] worktree: clarify --expire applies to missing worktrees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-20T06:07:24Z","receivedAt":"2025-12-20T06:07:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Sam Bostock via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Sam Bostock <sam.bostock@shopify.com>\n>\n> The `--expire` option for `git worktree list` and `git worktree prune`\n> only affects worktrees whose working directory path no longer exists.\n> The help text did not make this clear, and the documentation\n> inconsistently used \"unused\" for prune but \"missing\" for list.\n\nWell analyzed and described.\n\n> This updates the help text and documentation to consistently describe\n> these as \"missing worktrees\".\n\nWe phrase it more like \"Update the help text and documentation to\n...\", as if you are asking somebody sitting on the keyboard to make\nthat change.\n\n> diff --git a/builtin/worktree.c b/builtin/worktree.c\n> index fbdaf2eb2e..82fcbfeccf 100644\n> --- a/builtin/worktree.c\n> +++ b/builtin/worktree.c\n> @@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n>  \t\tOPT__DRY_RUN(&show_only, N_(\"do not remove, show only\")),\n>  \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n>  \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n> -\t\t\t\tN_(\"expire working trees older than <time>\")),\n> +\t\t\t\tN_(\"expire missing working trees older than <time>\")),\n\n\"expire\" -> \"prune\" or \"remove\".  As the user already said \"prune\"\nwhen they run \"git worktree prune -h\", using a different and more\ncommon verb \"remove\" to explain the action might be more helpful\nthan saying \"prune\".\n\nThanks.\n"},{"id":"532576","messageId":"xmqqms3du1he.fsf@gitster.g","threadId":"64656","inReplyTo":"ff4732b72a0d8c97c668167308039918362ffb9c.1766168169.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/2] worktree: use 'prune' instead of 'expire' in help text","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-20T06:11:09Z","receivedAt":"2025-12-20T06:11:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Sam Bostock via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Sam Bostock <sam.bostock@shopify.com>\n>\n> Use 'prune' instead of 'expire' when describing the --expire option's\n> effect on missing worktrees, since the terminology is clearer.\n>\n> Signed-off-by: Sam Bostock <sam@sambostock.ca>\n> ---\n>  Documentation/git-worktree.adoc | 2 +-\n>  builtin/worktree.c              | 2 +-\n>  2 files changed, 2 insertions(+), 2 deletions(-)\n\nDoes this v2 use exactly the same commit from v1 as [1/2] and add\nthis [2/2] as if you are saying \"oops, the previous one missed\nsomething we should have updated but forgot/failed to do so; here is\nan improvement?\"\n\nDon't.  Unless the change you deliberately made as a follow-up\nimprovement is logically separate and significant, that is.\n\nThanks.\n"},{"id":"532577","messageId":"CAPig+cTsKgzLvz_BJxTLqRfc5A7CK_FNo_L6TDOGPVGG9eXDCw@mail.gmail.com","threadId":"64656","inReplyTo":"xmqq4iplvhao.fsf@gitster.g","subject":"Re: [PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-12-20T07:14:15Z","receivedAt":"2025-12-20T07:14:27Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <gitster@pobox.com> wrote:\n> I wonder if this would work better.\n>\n>         `prune`::\n>                 Remove worktree information in `$GIT_DIR/worktrees`\n>                 only, without touching the working tree.  This is\n>                 often needed when the working tree is lost (e.g.,\n>                 the user manually removed it) and the worktree\n>                 information has become dangling.\n\nYes, this is a useful improvement, although one part confuses me (and\nI would omit it). In particular, if the working tree is lost, thus the\n`$GIT_DIR/worktrees` is dangling ought to be removed, then I'm not\nsure why you would say \"without touching the working tree\" (which is\nalready lost).\n"},{"id":"532578","messageId":"xmqqfr95txrz.fsf@gitster.g","threadId":"64656","inReplyTo":"CAPig+cTsKgzLvz_BJxTLqRfc5A7CK_FNo_L6TDOGPVGG9eXDCw@mail.gmail.com","subject":"Re: [PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-20T07:31:12Z","receivedAt":"2025-12-20T07:31:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine <sunshine@sunshineco.com> writes:\n\n> On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <gitster@pobox.com> wrote:\n>> I wonder if this would work better.\n>>\n>>         `prune`::\n>>                 Remove worktree information in `$GIT_DIR/worktrees`\n>>                 only, without touching the working tree.  This is\n>>                 often needed when the working tree is lost (e.g.,\n>>                 the user manually removed it) and the worktree\n>>                 information has become dangling.\n>\n> Yes, this is a useful improvement, although one part confuses me (and\n> I would omit it). In particular, if the working tree is lost, thus the\n> `$GIT_DIR/worktrees` is dangling ought to be removed, then I'm not\n> sure why you would say \"without touching the working tree\" (which is\n> already lost).\n\nAhh, I somehow thought you can say \"git worktree prune <worktree>\"\nto remove only the control information while the working tree is\nstill there, sort of \"orphaning\" the working tree from the main\nrepository.  But things do not work that way.\n\nYou're right that \"without touching the working tree\" part is\nmisleading and redundant.  And it is not \"this is often needed\"; it\nis the _only_ scenario the operation makes sense.\n\n\t`prune`::\n\t\tRemove worktree information in `$GIT_DIR/worktrees`\n\t\tfor worktrees whose working trees are missing.\n\t\tUseful after manually removing a working tree that\n\t\tis no longer needed (but use \"git worktree remove\"\n\t\tnext time you want to do so).  Also if you _moved_ a\n\t\tworking tree elsewhere to cause the worktree\n\t\tinformation dangling, see \"git worktree repair\" to\n\t\treconnect the worktree to the new working tree\n\t\tlocation.\n\nperhaps?\n\n"},{"id":"532579","messageId":"CAPig+cRa5EsN-=WcjEhSPpTLu=R=7uLwHL9OKLdAhwuxmsA6Og@mail.gmail.com","threadId":"64656","inReplyTo":"xmqqfr95txrz.fsf@gitster.g","subject":"Re: [PATCH] worktree: clarify --expire applies to missing worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-12-20T08:23:01Z","receivedAt":"2025-12-20T08:23:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Dec 20, 2025 at 2:31 AM Junio C Hamano <gitster@pobox.com> wrote:\n> Eric Sunshine <sunshine@sunshineco.com> writes:\n> > On Sat, Dec 20, 2025 at 12:44 AM Junio C Hamano <gitster@pobox.com> wrote:\n> >> I wonder if this would work better.\n> >>         `prune`::\n> >>                 Remove worktree information in `$GIT_DIR/worktrees`\n> >>                 only, without touching the working tree.  This is\n> >>                 often needed when the working tree is lost (e.g.,\n> >>                 the user manually removed it) and the worktree\n> >>                 information has become dangling.\n> >\n> > Yes, this is a useful improvement, although one part confuses me (and\n> > I would omit it). In particular, if the working tree is lost, thus the\n> > `$GIT_DIR/worktrees` is dangling ought to be removed, then I'm not\n> > sure why you would say \"without touching the working tree\" (which is\n> > already lost).\n>\n> Ahh, I somehow thought you can say \"git worktree prune <worktree>\"\n> to remove only the control information while the working tree is\n> still there, sort of \"orphaning\" the working tree from the main\n> repository.  But things do not work that way.\n>\n> You're right that \"without touching the working tree\" part is\n> misleading and redundant.  And it is not \"this is often needed\"; it\n> is the _only_ scenario the operation makes sense.\n>\n>         `prune`::\n>                 Remove worktree information in `$GIT_DIR/worktrees`\n>                 for worktrees whose working trees are missing.\n>                 Useful after manually removing a working tree that\n>                 is no longer needed (but use \"git worktree remove\"\n>                 next time you want to do so).  Also if you _moved_ a\n>                 working tree elsewhere to cause the worktree\n>                 information dangling, see \"git worktree repair\" to\n>                 reconnect the worktree to the new working tree\n>                 location.\n>\n> perhaps?\n\nYes, this sounds fine. This information is discussed in the\nDESCRIPTION section of the document, but it doesn't hurt to flesh it\nout here, as well.\n"},{"id":"534380","messageId":"xmqqzf66spum.fsf@gitster.g","threadId":"64656","inReplyTo":"pull.2135.v2.git.git.1766168169.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/2] worktree: clarify --expire applies to missing worktrees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-21T19:55:13Z","receivedAt":"2026-01-21T19:55:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Sam Bostock via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Changes from v1:\n>\n>  * Use 'prune' instead of 'expire' when describing the --expire option's\n>    effect on missing worktrees, since the terminology is clearer.\n>\n> Sam Bostock (2):\n>   worktree: clarify --expire applies to missing worktrees\n>   worktree: use 'prune' instead of 'expire' in help text\n>\n>  Documentation/git-worktree.adoc | 2 +-\n>  builtin/worktree.c              | 4 ++--\n>  2 files changed, 3 insertions(+), 3 deletions(-)\n>\n>\n> base-commit: c4a0c8845e2426375ad257b6c221a3a7d92ecfda\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v2\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v2\n> Pull-Request: https://github.com/git/git/pull/2135\n>\n> Range-diff vs v1:\n>\n>  1:  ddd4191ecb = 1:  ddd4191ecb worktree: clarify --expire applies to missing worktrees\n>  -:  ---------- > 2:  ff4732b72a worktree: use 'prune' instead of 'expire' in help text\n\nI think we have been expecting a reroll of this topic.  Any further\nprogress?\n\n"},{"id":"534743","messageId":"pull.2135.v3.git.git.1769578785381.gitgitgadget@gmail.com","threadId":"64656","inReplyTo":"pull.2135.v2.git.git.1766168169.gitgitgadget@gmail.com","subject":"[PATCH v3] worktree: clarify that --expire only affects missing worktrees","fromName":"Sam Bostock via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-01-28T05:39:45Z","receivedAt":"2026-01-28T05:39:48Z","isPatch":true,"sender":{"key":"sam.bostock@shopify.com","avatar":"https://avatars.githubusercontent.com/u/8219340?v=4"},"body":"From: Sam Bostock <sam.bostock@shopify.com>\n\nThe --expire option for \"git worktree list\" and \"git worktree prune\"\nonly affects worktrees whose working directory path no longer exists.\nThe help text did not make this clear, and the documentation\ninconsistently used \"unused\" for prune but \"missing\" for list.\n\nUpdate the help text and documentation to consistently describe these\nas \"missing worktrees\", and use \"prune\" instead of \"expire\" when\ndescribing the effect on missing worktrees since the terminology is\nclearer.\n\nWhile at it, expand the description of the \"prune\" subcommand itself\nto better explain what it does and when to use it, as suggested by\nJunio.\n\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\nHelped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Sam Bostock <sam@sambostock.ca>\n---\n    worktree: clarify --expire applies to missing worktrees\n    \n    Changes from v2:\n    \n     * Squash into a single commit\n     * Expand the prune subcommand description per Junio's suggestion\n    \n    Changes from v1:\n    \n     * Use \"prune\" instead of \"expire\" in help text\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2135%2Fsambostock%2Fexpire-missing-worktrees-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2135/sambostock/expire-missing-worktrees-v3\nPull-Request: https://github.com/git/git/pull/2135\n\nRange-diff vs v2:\n\n 1:  ddd4191ecb ! 1:  a4483d9a20 worktree: clarify --expire applies to missing worktrees\n     @@ Metadata\n      Author: Sam Bostock <sam.bostock@shopify.com>\n      \n       ## Commit message ##\n     -    worktree: clarify --expire applies to missing worktrees\n     +    worktree: clarify that --expire only affects missing worktrees\n      \n     -    The `--expire` option for `git worktree list` and `git worktree prune`\n     +    The --expire option for \"git worktree list\" and \"git worktree prune\"\n          only affects worktrees whose working directory path no longer exists.\n          The help text did not make this clear, and the documentation\n          inconsistently used \"unused\" for prune but \"missing\" for list.\n      \n     -    This updates the help text and documentation to consistently describe\n     -    these as \"missing worktrees\".\n     +    Update the help text and documentation to consistently describe these\n     +    as \"missing worktrees\", and use \"prune\" instead of \"expire\" when\n     +    describing the effect on missing worktrees since the terminology is\n     +    clearer.\n      \n     +    While at it, expand the description of the \"prune\" subcommand itself\n     +    to better explain what it does and when to use it, as suggested by\n     +    Junio.\n     +\n     +    Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n     +    Helped-by: Junio C Hamano <gitster@pobox.com>\n          Signed-off-by: Sam Bostock <sam@sambostock.ca>\n      \n       ## Documentation/git-worktree.adoc ##\n     +@@ Documentation/git-worktree.adoc: with linked worktrees if you move the main worktree manually.)\n     + \n     + `prune`::\n     + \n     +-Prune worktree information in `$GIT_DIR/worktrees`.\n     ++Remove worktree information in `$GIT_DIR/worktrees` for worktrees\n     ++whose working trees are missing.  Useful after manually removing\n     ++a working tree that is no longer needed (but use \"git worktree\n     ++remove\" next time you want to do so).  Also, if you _moved_ a\n     ++working tree elsewhere causing the worktree information to become\n     ++dangling, see \"git worktree repair\" to reconnect the worktree to\n     ++the new working tree location.\n     + \n     + `remove`::\n     + \n      @@ Documentation/git-worktree.adoc: mismatch, even if the links are correct.\n       With `list`, output additional information about worktrees (see below).\n       \n       `--expire <time>`::\n      -\tWith `prune`, only expire unused worktrees older than _<time>_.\n     -+\tWith `prune`, only expire missing worktrees older than _<time>_.\n     ++\tWith `prune`, only prune missing worktrees if older than _<time>_.\n       +\n       With `list`, annotate missing worktrees as prunable if they are older than\n       _<time>_.\n     @@ builtin/worktree.c: static int prune(int ac, const char **av, const char *prefix\n       \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n       \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n      -\t\t\t\tN_(\"expire working trees older than <time>\")),\n     -+\t\t\t\tN_(\"expire missing working trees older than <time>\")),\n     ++\t\t\t\tN_(\"prune missing working trees older than <time>\")),\n       \t\tOPT_END()\n       \t};\n       \n 2:  ff4732b72a < -:  ---------- worktree: use 'prune' instead of 'expire' in help text\n\n\n Documentation/git-worktree.adoc | 10 ++++++++--\n builtin/worktree.c              |  4 ++--\n 2 files changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex f272f79783..22ef37ec02 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -131,7 +131,13 @@ with linked worktrees if you move the main worktree manually.)\n \n `prune`::\n \n-Prune worktree information in `$GIT_DIR/worktrees`.\n+Remove worktree information in `$GIT_DIR/worktrees` for worktrees\n+whose working trees are missing.  Useful after manually removing\n+a working tree that is no longer needed (but use \"git worktree\n+remove\" next time you want to do so).  Also, if you _moved_ a\n+working tree elsewhere causing the worktree information to become\n+dangling, see \"git worktree repair\" to reconnect the worktree to\n+the new working tree location.\n \n `remove`::\n \n@@ -271,7 +277,7 @@ mismatch, even if the links are correct.\n With `list`, output additional information about worktrees (see below).\n \n `--expire <time>`::\n-\tWith `prune`, only expire unused worktrees older than _<time>_.\n+\tWith `prune`, only prune missing worktrees if older than _<time>_.\n +\n With `list`, annotate missing worktrees as prunable if they are older than\n _<time>_.\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex fbdaf2eb2e..3d6547c23b 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -252,7 +252,7 @@ static int prune(int ac, const char **av, const char *prefix,\n \t\tOPT__DRY_RUN(&show_only, N_(\"do not remove, show only\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"report pruned working trees\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"expire working trees older than <time>\")),\n+\t\t\t\tN_(\"prune missing working trees older than <time>\")),\n \t\tOPT_END()\n \t};\n \n@@ -1070,7 +1070,7 @@ static int list(int ac, const char **av, const char *prefix,\n \t\tOPT_BOOL(0, \"porcelain\", &porcelain, N_(\"machine-readable output\")),\n \t\tOPT__VERBOSE(&verbose, N_(\"show extended annotations and reasons, if available\")),\n \t\tOPT_EXPIRY_DATE(0, \"expire\", &expire,\n-\t\t\t\tN_(\"add 'prunable' annotation to worktrees older than <time>\")),\n+\t\t\t\tN_(\"add 'prunable' annotation to missing worktrees older than <time>\")),\n \t\tOPT_SET_INT('z', NULL, &line_terminator,\n \t\t\t    N_(\"terminate records with a NUL character\"), '\\0'),\n \t\tOPT_END()\n\nbase-commit: c4a0c8845e2426375ad257b6c221a3a7d92ecfda\n-- \ngitgitgadget\n"},{"id":"534848","messageId":"CAPig+cQ+HWZDb5ArGBq8PkXu1X6Dwe79w0sVjX9uRm7PcEwyNQ@mail.gmail.com","threadId":"64656","inReplyTo":"pull.2135.v3.git.git.1769578785381.gitgitgadget@gmail.com","subject":"Re: [PATCH v3] worktree: clarify that --expire only affects missing worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2026-01-30T00:29:55Z","receivedAt":"2026-01-30T00:30:07Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Jan 28, 2026 at 12:39 AM Sam Bostock via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> The --expire option for \"git worktree list\" and \"git worktree prune\"\n> only affects worktrees whose working directory path no longer exists.\n> The help text did not make this clear, and the documentation\n> inconsistently used \"unused\" for prune but \"missing\" for list.\n>\n> Update the help text and documentation to consistently describe these\n> as \"missing worktrees\", and use \"prune\" instead of \"expire\" when\n> describing the effect on missing worktrees since the terminology is\n> clearer.\n>\n> While at it, expand the description of the \"prune\" subcommand itself\n> to better explain what it does and when to use it, as suggested by\n> Junio.\n>\n> Signed-off-by: Sam Bostock <sam@sambostock.ca>\n> ---\n>     Changes from v2:\n>      * Squash into a single commit\n>      * Expand the prune subcommand description per Junio's suggestion\n\nThanks for re-rolling this patch. I think this version addresses all\nthe review comments from Junio and myself and is ready to be merged to\n\"next\".\n"}]}