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

From

Rafael Silva <rafaeloliveira.cs@gmail.com>

Date

Jan 4, 2021, 16:21 UTC

Message-ID

<20210104162128.95281-8-rafaeloliveira.cs@gmail.com>

In-Reply-To

<20210104162128.95281-1-rafaeloliveira.cs@gmail.com>

Signed-off-by: Rafael Silva <rafaeloliveira.cs@gmail.com>
---
 Documentation/git-worktree.txt | 59 ++++++++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 3 deletions(-)

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

-- 
2.30.0.391.g469bf2a980