guix gc: Add '--list-roots'.

* guix/scripts/gc.scm (show-help, %options): Add '--list-roots'.
(guix-gc)[list-roots]: New procedure.
Handle '--list-roots'.
* tests/guix-gc.sh: Test it.
* doc/guix.texi (Invoking guix gc): Document it.

1 files changed, 5 insertions, 1 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 2f9fcbe3bf8..2345617b2e8 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3385,7 +3385,7 @@ deleted.  The set of garbage collector roots (``GC roots'' for short)
 includes default user profiles; by default, the symlinks under
 @file{/var/guix/gcroots} represent these GC roots.  New GC roots can be
 added with @command{guix build --root}, for example (@pxref{Invoking
-guix build}).
+guix build}).  The @command{guix gc --list-roots} command lists them.
 
 Prior to running @code{guix gc --collect-garbage} to make space, it is
 often useful to remove old generations from user profiles; that way, old
@@ -3451,6 +3451,10 @@ This prints nothing unless the daemon was started with
 @option{--cache-failures} (@pxref{Invoking guix-daemon,
 @option{--cache-failures}}).
 
+@item --list-roots
+List the GC roots owned by the user; when run as root, list @emph{all} the GC
+roots.
+
 @item --clear-failures
 Remove the specified store items from the failed-build cache.