lib.fileset.maybeMissing: init

1 files changed, 31 insertions, 0 deletions

diff --git a/lib/fileset/default.nix b/lib/fileset/default.nix
index 2cb361ec9ba19..9ccbf0ed7ce74 100644
--- a/lib/fileset/default.nix
+++ b/lib/fileset/default.nix
@@ -11,6 +11,10 @@
   Basics:
   - [Implicit coercion from paths to file sets](#sec-fileset-path-coercion)
 
+  - [`lib.fileset.maybeMissing`](#function-library-lib.fileset.maybeMissing):
+
+    Create a file set from a path that may be missing.
+
   - [`lib.fileset.trace`](#function-library-lib.fileset.trace)/[`lib.fileset.traceVal`](#function-library-lib.fileset.trace):
 
     Pretty-print file sets for debugging.
@@ -105,6 +109,7 @@ let
     _difference
     _mirrorStorePath
     _fetchGitSubmodulesMinver
+    _emptyWithoutBase
     ;
 
   inherit (builtins)
@@ -149,6 +154,32 @@ let
 in {
 
   /*
+    Create a file set from a path that may or may not exist:
+    - If the path does exist, the path is [coerced to a file set](#sec-fileset-path-coercion).
+    - If the path does not exist, a file set containing no files is returned.
+
+    Type:
+      maybeMissing :: Path -> FileSet
+
+    Example:
+      # All files in the current directory, but excluding main.o if it exists
+      difference ./. (maybeMissing ./main.o)
+  */
+  maybeMissing =
+    path:
+    if ! isPath path then
+      if isStringLike path then
+        throw ''
+          lib.fileset.maybeMissing: Argument ("${toString path}") is a string-like value, but it should be a path instead.''
+      else
+        throw ''
+          lib.fileset.maybeMissing: Argument is of type ${typeOf path}, but it should be a path instead.''
+    else if ! pathExists path then
+      _emptyWithoutBase
+    else
+      _singleton path;
+
+  /*
     Incrementally evaluate and trace a file set in a pretty way.
     This function is only intended for debugging purposes.
     The exact tracing format is unspecified and may change.