| Message ID | 20210104162128.95281-8-rafaeloliveira.cs@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | teach `worktree list` verbose mode and prunable annotations | expand |
On Mon, Jan 4, 2021 at 11:22 AM Rafael Silva <rafaeloliveira.cs@gmail.com> 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@gmail.com> > --- > 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). > --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>`. > @@ -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. > +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. > 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. 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.)
Eric Sunshine writes: > On Mon, Jan 4, 2021 at 11:22 AM Rafael Silva > <rafaeloliveira.cs@gmail.com> 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@gmail.com> >> --- >> 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.
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index af06128cc9..8ce579e2e8 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -97,8 +97,9 @@ list:: List details of each working tree. The main working tree is listed first, followed by each of the linked working trees. The output details include whether the working tree is bare, the revision currently checked out, the -branch currently checked out (or "detached HEAD" if none), and "locked" if -the worktree is locked. +branch currently checked out (or "detached HEAD" if none), "locked" if +the worktree is locked, "prunable" if the worktree can be pruned by `prune` +command. lock:: @@ -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. --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. --reason <string>:: With `lock`, an explanation why the working tree is locked. @@ -367,13 +371,48 @@ $ git worktree list /path/to/other-linked-worktree 1234abc (detached HEAD) ------------ +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". + +------------ +$ git worktree list +/path/to/linked-worktree abcd1234 [master] +/path/to/locked-worktreee acbd5678 (brancha) locked +/path/to/prunable-worktree 5678abc (detached HEAD) prunable +------------ + +For these annotations, a reason might also be available and this can be +seen using the verbose mode. The annotation is then moved to the next line +indented followed by the additional information. + +------------ +$ git worktree list --verbose +/path/to/linked-worktree abcd1234 [master] +/path/to/locked-worktreee acbd5678 (brancha) + locked: working tree path is mounted on a removable device +/path/to/locked-no-reason abcd578 (detached HEAD) locked +/path/to/prunable-worktree 5678abc (detached HEAD) + prunable: gitdir file points to non-existent location +------------ + +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. + 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: ------------ $ git worktree list --porcelain @@ -388,6 +427,20 @@ worktree /path/to/other-linked-worktree HEAD 1234abc1234abc1234abc1234abc1234abc1234a detached +worktree /path/to/linked-worktree-locked +HEAD 5678abc5678abc5678abc5678abc5678abc5678c +branch refs/heads/locked +locked + +worktree /path/to/linked-worktree-locked-with-reason +HEAD 3456def3456def3456def3456def3456def3456b +branch refs/heads/locked-with-reason +locked reason why is locked + +worktree /path/to/linked-worktree-prunable +HEAD 1233def1234def1234def1234def1234def1234b +detached +prunable gitdir file points to non-existent location ------------ EXAMPLES
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@gmail.com> --- Documentation/git-worktree.txt | 59 ++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 3 deletions(-)