populate: add prune

Populate never removes what it delivered for sources that aren't
configured anymore.  For flake and flake-input sources, that keeps their
garbage collector roots, so what they delivered never gets collected.

With prune, populate removes everything from the target directory that
isn't a source, except .populate, after syncing the sources.  It also
removes the roots in .populate/flake-inputs of names that aren't flake or
flake-input sources, and uploads left behind by interrupted runs.
Pruning is opt-in, because the target directory may contain other things
worth keeping, or be shared by deployments with different sources.

writeDeploy, writeTest, and writeCommand pass prune on to populate.

A feature scenario deploys sources, deploys fewer without pruning, then
with pruning, and checks that the removed sources' entries and roots are
gone, while the remaining sources and .populate stay.

1 files changed, 17 insertions, 0 deletions

diff --git a/README.md b/README.md
index 79ace5b..eda8dcd 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,15 @@ Create the sentinel file (`/var/src/.populate`) before syncing the new source.
 
 Specifies which `nixos-rebuild` operation to perform.
 
+### `prune` (optional, defaults to false)
+
+Remove everything from the target directory that isn't a source, except
+`.populate`, after syncing the sources.  This also removes the garbage
+collector roots of the inputs of former `flake` and `flake-input` sources in
+`.populate/flake-inputs/<name>`, so the garbage collector can collect what
+they delivered.  Don't use it if the target directory contains anything else
+worth keeping, or if several deployments with different sources share it.
+
 ### `useNixOutputMonitor` (optional, defaults to `"opportunistic"`)
 
 Specifies when to pipe `nixos-rebuild`'s output to
@@ -190,6 +199,10 @@ below `/var/src`, and executes `NIX_PATH=/var/src nix-build -A system '<nixpkgs/
 
 [see `writeDeploy`](#writeDeploy)
 
+### `prune` (optional, defaults to false)
+
+[see `writeDeploy`](#writeDeploy)
+
 ### `trace` (optional, defaults to false)
 
 run nix-build with `--show-trace`
@@ -227,6 +240,10 @@ pkgs.krops.writeCommand "deploy-with-swap" {
 
 [see `writeDeploy`](#writeDeploy)
 
+### `prune` (optional, defaults to false)
+
+[see `writeDeploy`](#writeDeploy)
+
 ### `allocateTTY` (optional, defaults to false)
 
 whether the ssh session should do a pseudo-terminal allocation.