[PATCH v3] worktree: clarify that --expire only affects 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.

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