From 0fe9ad2c52b785b55df4786c6ce0d2a1f433afe1 Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Sat, 28 Dec 2024 22:29:34 +0000
Subject: [PATCH] lib.packagesFromDirectoryRecursive: Add example use of
 `recurseIntoDirectory`

---
 lib/filesystem.nix | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index a9fd19525a16e..55e3e02d8514d 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -394,6 +394,38 @@ in
     `a.nix` cannot directly take as inputs packages defined in a child directory, such as `b1`.
     :::
     ::::
+
+    :::{.example}
+    ## Mark with `recurseIntoAttrs` when recursing into a directory
+    ```nix
+    packagesFromDirectoryRecursive {
+      inherit (pkgs) callPackage;
+      directory = ./my-packages;
+
+      recurseIntoDirectory = processDir: args: lib.recurseIntoAttrs (processDir args);
+    }
+    ```
+    :::
+
+    :::{.example}
+    ## Express custom recursion behaviour with `recurseIntoDirectory`
+    For instance, only mark attrsets produced by `packagesFromDirectoryRecursive` with `recurseForDerivations`
+    if they (transitively) contain derivations.
+
+    ```nix
+    packagesFromDirectoryRecursive {
+      inherit (pkgs) callPackage;
+      directory = ./my-packages;
+
+      recurseIntoDirectory = processDir: args: let
+        result = processDir args;
+      in result // {
+        recurseForDerivations = with lib;
+          any (child: isDerivation child || child.recurseForDerivations or false) result;
+      };
+    }
+    ```
+    :::
   */
   packagesFromDirectoryRecursive =
     let