From 84888f4e20de185e3bd3aaaa63e180dace349b92 Mon Sep 17 00:00:00 2001
From: tv <tv@krebsco.de>
Date: Wed, 11 Nov 2026 16:14:54 +0000
Subject: populate: add flake source type

Deliver a flake, or one of its locked inputs, to the target: archive the
flake locally, copy the selected input together with its own inputs into the
target's store, and link it at the target path, registered as garbage
collector root.  The result can be used in NIX_PATH as well as by flakes
evaluated on the target, without network access.

nix copy runs with a separate ssh wrapper without the control socket, because
Nix waits for its LocalCommand, which may not run over a multiplexed
connection.
---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index d8268e5..84b1671 100644
--- a/README.md
+++ b/README.md
@@ -265,6 +265,53 @@ Supported attributes:
   of rsync. Defaults to `true`.
 
 
+### `flake`
+
+The flake source type delivers a flake, or one of its locked inputs, to the
+target.  The flake gets archived locally using `nix flake archive`, the
+selected input and its own inputs get copied into the target's Nix store using
+`nix copy`, and the target path becomes a symlink to the input's store path,
+registered as garbage collector root.  The input's own inputs get garbage
+collector roots in `.populate/flake-inputs/<name>`, which turns the sentinel
+file into a directory.
+
+Because the target path points at the store path named by the flake's lock
+file, it can be used in `NIX_PATH` as well as by flakes evaluated on the
+target, without network access.
+
+Supported attributes:
+
+* `flake` -
+  flake reference, e.g. the absolute path of a directory containing a
+  `flake.nix`.  Its lock file is used as is; populating fails if the lock
+  file needs to be updated.
+
+* `input` (optional) -
+  name of the input to deliver.  Inputs of inputs are separated by `/`,
+  e.g. `stockholm/nixpkgs`.  If omitted, the flake itself gets delivered,
+  which includes only files tracked by Git.  Use a `file` source for work
+  trees with untracked files.
+
+Instead of an attribute set, the flake reference can be given as a string.
+
+The flake commands run using krops' own Nix, so flakes don't need to be
+enabled on the deploying machine.  The target only needs `nix-store`.
+Because the copied store paths aren't signed, the target user must be allowed
+to import them, i.e. be `root` or a trusted user.  Targets using `sudo` aren't
+supported.
+
+Example:
+
+```nix
+{
+  nixpkgs.flake = {
+    flake = toString ./.;
+    input = "nixpkgs";
+  };
+}
+```
+
+
 ### `git`
 
 Git sources that will be fetched on the target machine.
-- 
cgit v1.3.1