Re: [PATCH 7/7] worktree: document `list` verbose and prunable annotations

Eric Sunshine writes:

On Mon, Jan 4, 2021 at 11:22 AM Rafael Silva
[off-list ref] wrote:

quoted

Update the documentation with "git worktree list" verbose mode, prunable
and locked annotations for the default and porcelain format as part of
teaching the command to show prunable working trees and verbose mode.

Signed-off-by: Rafael Silva <redacted>
---

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt

@@ -226,9 +227,12 @@ This can also be set up as the default behaviour by using the
 -v::
 --verbose::
        With `prune`, report all removals.
+       With `list`, output additional information for working trees.

This leaves the reader wondering what additional information is output
for `list`. Perhaps a small tweak will help:

    With `list`, output additional information about worktrees (see below).

Make sense.

quoted

 --expire <time>::
        With `prune`, only expire unused working trees older than `<time>`.
+       With `list`, annotate unused working trees older than `<time>` as prunable
+       candidates that will be remove by `prune` command if the same option is used.

Perhaps just minimal:

    With `list`, annotate missing worktrees as prunable if they
    are older than `<time>`.

Sounds reasonable.

quoted

@@ -367,13 +371,48 @@ $ git worktree list
+The command also shows annotations for each working tree, according to its state.
+These annotations are:
+
+ * "locked", if any working tree is locked
+ * "prunable", if any working tree can be pruned via "git worktree prune".

s/any/the/g

We might want to use backticks around these annotations rather than
double quotes, and we certainly do want to use backticks around the
`git worktree prune` command to ensure it is styled consistently with
other commands in this document.

Yes, good catch. It make sense to have backticks here.

quoted

+Note that, the annotation is only moved to the next line only if the
+additional text is available, otherwise the text is kept on the same.

Drop the comma between "that, the". Also, too many "only"s in this
sentence. You can actually drop both of them and the sentence will
still read fine:

   Note that the annotation is moved to the next line if the
   additional information is available, otherwise it stays on
   the same line as the worktree itself.

or something.

Thanks for the alternative suggestion. It reads better like this will
add change the patch message to something more close to your suggestion.

quoted

 Porcelain Format
 ~~~~~~~~~~~~~~~~
 The porcelain format has a line per attribute.  Attributes are listed with a
 label and value separated by a single space.  Boolean attributes (like `bare`
 and `detached`) are listed as a label only, and are present only
 if the value is true.  The first attribute of a working tree is always
-`worktree`, an empty line indicates the end of the record.  For example:
+`worktree`, an empty line indicates the end of the record.
++
+In case any of the working trees are locked or is a candidate for pruning
+(See DESCRIPTION above) the labels "locked" and "prunable" is also shown
+followed by a reason, if available, otherwise only the labels are listed.
+For example:

s/(See/(see/
s/is also/are also/

Let's also use backticks rather than double quotes around `locked` and
`prunable` to ensure consistent formatting with the other porcelain
labels `bare` and `detached` which are already in backticks.

Nice catch. 

Also, the unnecessary `+` line (seen as `++` in the diff) makes this
render incorrectly. It renders as:

    +In case any...

To fix it, just leave the line blank between paragraphs.

(If possible, install `asciidoc` and `xmlto` and then run `make html`
to render the documentation yourself, and open
Documentation/git-worktree.html in your browser to check the output.)

Sure thing. thanks for the suggestion. I should have rendered the
documentation before sending. Apologize for that.

-- 
Thanks
Rafael