Re: [PATCH 6/6] worktree: wordsmith worktree-related manpages

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jul 19, 2015, 03:21 UTC
Message-ID: <CAPig+cShJjmDAnwBJ0gzgHb0KwAbNZLLOCfJ2tiGQJZsCQf1gA@mail.gmail.com>
In-Reply-To: <087f0fbeffa8fb30529ba69498e427d11396eddf.1437271363.git.mhagger@alum.mit.edu>

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:

Show 13 quoted lines

> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 7f65dbb..10bc351 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1292,11 +1292,11 @@ gc.pruneExpire::
>         unreachable objects immediately.
>
>  gc.pruneWorktreesExpire::
> -       When 'git gc' is run, it will call
> +       When 'git gc' is run, it calls
>         'git worktree prune --expire 3.months.ago'.

This is a tangent, but I wonder if this config variable should be renamed to gc.worktreePruneExpire to reflect the rename of "prune --wortkrees" to "worktree prune".

Show 24 quoted lines

> -       Override the grace period with this config variable. The value
> -       "now" may be used to disable the grace period and prune
> -       $GIT_DIR/worktrees immediately.
> +       This config variable can be used to set a different grace
> +       period. The value "now" may be used to disable the grace
> +       period and prune $GIT_DIR/worktrees immediately.
>
>  gc.reflogExpire::
>  gc.<pattern>.reflogExpire::
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index d5aeda0..cecb44c 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -138,7 +138,7 @@ EXAMPLES
>  worktrees/<id>/locked::
>         If this file exists, the linked working tree may be on a
> -       portable device and not available. It does not mean that the
> -       linked working tree is gone and `worktrees/<id>` could be
> -       removed. The file's content contains a reason string on why
> -       the repository is locked.
> +       portable device and not available. The presence of this file
> +       prevents `worktrees/<id>` from being pruned by `git worktree
> +       prune`. The file may contain a string explaining why the
> +       repository is locked.

When I read the new text, I kind of get the impression that pruning only happens manually when the user invokes "git worktree prune". I wonder if it can be reworded to mention that pruning can happen automatically too. Or, maybe don't mention "git worktree prune" at all, and instead just say, generally, that it prevents the linked-worktree administrative files from being pruned.