Eric Sunshine writes: > On Mon, Jan 4, 2021 at 11:22 AM Rafael Silva > <rafaeloliveira.cs@xxxxxxxxx> wrote: >> 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 <rafaeloliveira.cs@xxxxxxxxx> >> --- >> 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. >> --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. >> @@ -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. >> +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. >> 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
