Merge branch 'nixos-unstable-small' of https://github.com/NixOS/nixpkgs

3 files changed, 60 insertions, 6 deletions

diff --git a/nixpkgs/lib/fileset/default.nix b/nixpkgs/lib/fileset/default.nix
index 15af0813eec7..ca2ab9a35740 100644
--- a/nixpkgs/lib/fileset/default.nix
+++ b/nixpkgs/lib/fileset/default.nix
@@ -1,3 +1,52 @@
+/*
+  <!-- This anchor is here for backwards compatibity -->
+  []{#sec-fileset}
+
+  The [`lib.fileset`](#sec-functions-library-fileset) library allows you to work with _file sets_.
+  A file set is a mathematical set of local files that can be added to the Nix store for use in Nix derivations.
+  File sets are easy and safe to use, providing obvious and composable semantics with good error messages to prevent mistakes.
+
+  See the [function reference](#sec-functions-library-fileset) for function-specific documentation.
+
+  ## Implicit coercion from paths to file sets {#sec-fileset-path-coercion}
+
+  All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments.
+  Such path arguments are implicitly coerced to file sets containing all files under that path:
+  - A path to a file turns into a file set containing that single file.
+  - A path to a directory turns into a file set containing all files _recursively_ in that directory.
+
+  If the path points to a non-existent location, an error is thrown.
+
+  ::: {.note}
+  Just like in Git, file sets cannot represent empty directories.
+  Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files.
+  :::
+
+  :::{.note}
+  File set coercion does _not_ add any of the files under the coerced paths to the store.
+  Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument.
+  This is in contrast to using [paths in string interpolation](https://nixos.org/manual/nix/stable/language/values.html#type-path), which does add the entire referenced path to the store.
+  :::
+
+  ### Example {#sec-fileset-path-coercion-example}
+
+  Assume we are in a local directory with a file hierarchy like this:
+  ```
+  ├─ a/
+  │  ├─ x (file)
+  │  └─ b/
+  │     └─ y (file)
+  └─ c/
+     └─ d/
+  ```
+
+  Here's a listing of which files get included when different path expressions get coerced to file sets:
+  - `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted).
+  - `./a` as a file set contains both `a/x` and `a/b/y`.
+  - `./a/x` as a file set contains only `a/x`.
+  - `./a/b` as a file set contains only `a/b/y`.
+  - `./c` as a file set is empty, since neither `c` nor `c/d` contain any files.
+*/
 { lib }:
 let
 
@@ -263,7 +312,7 @@ in {
           lib.fileset.fromSource: The source origin of the argument is of type ${typeOf path}, but it should be a path instead.''
     else if ! pathExists path then
       throw ''
-        lib.fileset.fromSource: The source origin (${toString path}) of the argument does not exist.''
+        lib.fileset.fromSource: The source origin (${toString path}) of the argument is a path that does not exist.''
     else if isFiltered then
       _fromSourceFilter path source.filter
     else
diff --git a/nixpkgs/lib/fileset/internal.nix b/nixpkgs/lib/fileset/internal.nix
index 0769e654c8fb..23d7b847204c 100644
--- a/nixpkgs/lib/fileset/internal.nix
+++ b/nixpkgs/lib/fileset/internal.nix
@@ -381,7 +381,7 @@ rec {
 
   # Turn a fileset into a source filter function suitable for `builtins.path`
   # Only directories recursively containing at least one files are recursed into
-  # Type: Path -> fileset -> (String -> String -> Bool)
+  # Type: fileset -> (String -> String -> Bool)
   _toSourceFilter = fileset:
     let
       # Simplify the tree, necessary to make sure all empty directories are null
@@ -753,9 +753,9 @@ rec {
 
       resultingTree =
         _differenceTree
-        positive._internalBase
-        positive._internalTree
-        negativeTreeWithPositiveBase;
+          positive._internalBase
+          positive._internalTree
+          negativeTreeWithPositiveBase;
     in
     # If the first file set is empty, we can never have any files in the result
     if positive._internalIsEmptyWithoutBase then
diff --git a/nixpkgs/lib/fileset/tests.sh b/nixpkgs/lib/fileset/tests.sh
index 3c88ebdd0559..06f92f297d88 100755
--- a/nixpkgs/lib/fileset/tests.sh
+++ b/nixpkgs/lib/fileset/tests.sh
@@ -1064,13 +1064,18 @@ rm -rf -- *
 ## lib.fileset.fromSource
 
 # Check error messages
-expectFailure 'fromSource null' 'lib.fileset.fromSource: The source origin of the argument is of type null, but it should be a path instead.'
 
+# String-like values are not supported
 expectFailure 'fromSource (lib.cleanSource "")' 'lib.fileset.fromSource: The source origin of the argument is a string-like value \(""\), but it should be a path instead.
 \s*Sources created from paths in strings cannot be turned into file sets, use `lib.sources` or derivations instead.'
 
+# Wrong type
+expectFailure 'fromSource null' 'lib.fileset.fromSource: The source origin of the argument is of type null, but it should be a path instead.'
 expectFailure 'fromSource (lib.cleanSource null)' 'lib.fileset.fromSource: The source origin of the argument is of type null, but it should be a path instead.'
 
+# fromSource on non-existent paths gives an error
+expectFailure 'fromSource ./a' 'lib.fileset.fromSource: The source origin \('"$work"'/a\) of the argument is a path that does not exist.'
+
 # fromSource on a path works and is the same as coercing that path
 mkdir a
 touch a/b c