guix gc: Add '--list-failures' and '--clear-failures'.

Suggested by Mark H Weaver <mhw@netris.org>.

* guix/scripts/gc.scm (show-help, %options): Add --list-failures and
  --clear-failures.
  (guix-gc): Honor them.
* doc/guix.texi (Invoking guix gc): Document them.
  (Invoking guix-daemon): Mention them.

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index afb4108800..6a3765f56a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -814,6 +814,11 @@ builds to other machines (@pxref{Daemon Offload Setup}).
 @item --cache-failures
 Cache build failures.  By default, only successful builds are cached.
 
+When this option is used, @command{guix gc --list-failures} can be used
+to query the set of store items marked as failed; @command{guix gc
+--clear-failures} removes store items from the set of cached failures.
+@xref{Invoking guix gc}.
+
 @item --cores=@var{n}
 @itemx -c @var{n}
 Use @var{n} CPU cores to build each derivation; @code{0} means as many
@@ -1674,6 +1679,19 @@ Attempt to delete all the store files and directories specified as
 arguments.  This fails if some of the files are not in the store, or if
 they are still live.
 
+@item --list-failures
+List store items corresponding to cached build failures.
+
+This prints nothing unless the daemon was started with
+@option{--cache-failures} (@pxref{Invoking guix-daemon,
+@option{--cache-failures}}).
+
+@item --clear-failures
+Remove the specified store items from the failed-build cache.
+
+Again, this option only makes sense when the daemon is started with
+@option{--cache-failures}.  Otherwise, it does nothing.
+
 @item --list-dead
 Show the list of dead files and directories still present in the
 store---i.e., files and directories no longer reachable from any root.