lib/fileset/default.nix

   1 /**
   2   <!-- This anchor is here for backwards compatibility -->
   3   []{#sec-fileset}
   4
   5   The [`lib.fileset`](#sec-functions-library-fileset) library allows you to work with _file sets_.
   6   A file set is a (mathematical) set of local files that can be added to the Nix store for use in Nix derivations.
   7   File sets are easy and safe to use, providing obvious and composable semantics with good error messages to prevent mistakes.
   8
   9   # Overview {#sec-fileset-overview}
  10
  11   Basics:
  12   - [Implicit coercion from paths to file sets](#sec-fileset-path-coercion)
  13
  14   - [`lib.fileset.maybeMissing`](#function-library-lib.fileset.maybeMissing):
  15
  16     Create a file set from a path that may be missing.
  17
  18   - [`lib.fileset.trace`](#function-library-lib.fileset.trace)/[`lib.fileset.traceVal`](#function-library-lib.fileset.trace):
  19
  20     Pretty-print file sets for debugging.
  21
  22   - [`lib.fileset.toSource`](#function-library-lib.fileset.toSource):
  23
  24     Add files in file sets to the store to use as derivation sources.
  25
  26   - [`lib.fileset.toList`](#function-library-lib.fileset.toList):
  27
  28     The list of files contained in a file set.
  29
  30   Combinators:
  31   - [`lib.fileset.union`](#function-library-lib.fileset.union)/[`lib.fileset.unions`](#function-library-lib.fileset.unions):
  32
  33     Create a larger file set from all the files in multiple file sets.
  34
  35   - [`lib.fileset.intersection`](#function-library-lib.fileset.intersection):
  36
  37     Create a smaller file set from only the files in both file sets.
  38
  39   - [`lib.fileset.difference`](#function-library-lib.fileset.difference):
  40
  41     Create a smaller file set containing all files that are in one file set, but not another one.
  42
  43   Filtering:
  44   - [`lib.fileset.fileFilter`](#function-library-lib.fileset.fileFilter):
  45
  46     Create a file set from all files that satisisfy a predicate in a directory.
  47
  48   Utilities:
  49   - [`lib.fileset.fromSource`](#function-library-lib.fileset.fromSource):
  50
  51     Create a file set from a `lib.sources`-based value.
  52
  53   - [`lib.fileset.gitTracked`](#function-library-lib.fileset.gitTracked)/[`lib.fileset.gitTrackedWith`](#function-library-lib.fileset.gitTrackedWith):
  54
  55     Create a file set from all tracked files in a local Git repository.
  56
  57   If you need more file set functions,
  58   see [this issue](https://github.com/NixOS/nixpkgs/issues/266356) to request it.
  59
  60   # Implicit coercion from paths to file sets {#sec-fileset-path-coercion}
  61
  62   All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments.
  63   Such path arguments are implicitly coerced to file sets containing all files under that path:
  64   - A path to a file turns into a file set containing that single file.
  65   - A path to a directory turns into a file set containing all files _recursively_ in that directory.
  66
  67   If the path points to a non-existent location, an error is thrown.
  68
  69   ::: {.note}
  70   Just like in Git, file sets cannot represent empty directories.
  71   Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files.
  72   :::
  73
  74   :::{.note}
  75   File set coercion does _not_ add any of the files under the coerced paths to the store.
  76   Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument.
  77   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.
  78   :::
  79
  80   ## Example {#sec-fileset-path-coercion-example}
  81
  82   Assume we are in a local directory with a file hierarchy like this:
  83   ```
  84   ├─ a/
  85   │  ├─ x (file)
  86   │  └─ b/
  87   │     └─ y (file)
  88   └─ c/
  89      └─ d/
  90   ```
  91
  92   Here's a listing of which files get included when different path expressions get coerced to file sets:
  93   - `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted).
  94   - `./a` as a file set contains both `a/x` and `a/b/y`.
  95   - `./a/x` as a file set contains only `a/x`.
  96   - `./a/b` as a file set contains only `a/b/y`.
  97   - `./c` as a file set is empty, since neither `c` nor `c/d` contain any files.
  98 */
  99 { lib }:
 100 let
 101
 102   inherit (import ./internal.nix { inherit lib; })
 103     _coerce
 104     _singleton
 105     _coerceMany
 106     _toSourceFilter
 107     _fromSourceFilter
 108     _toList
 109     _unionMany
 110     _fileFilter
 111     _printFileset
 112     _intersection
 113     _difference
 114     _fromFetchGit
 115     _fetchGitSubmodulesMinver
 116     _emptyWithoutBase
 117     ;
 118
 119   inherit (builtins)
 120     isBool
 121     isList
 122     isPath
 123     pathExists
 124     seq
 125     typeOf
 126     nixVersion
 127     ;
 128
 129   inherit (lib.lists)
 130     elemAt
 131     imap0
 132     ;
 133
 134   inherit (lib.path)
 135     hasPrefix
 136     splitRoot
 137     ;
 138
 139   inherit (lib.strings)
 140     isStringLike
 141     versionOlder
 142     ;
 143
 144   inherit (lib.filesystem)
 145     pathType
 146     ;
 147
 148   inherit (lib.sources)
 149     cleanSourceWith
 150     ;
 151
 152   inherit (lib.trivial)
 153     isFunction
 154     pipe
 155     ;
 156
 157 in
 158 {
 159
 160   /**
 161     Create a file set from a path that may or may not exist:
 162     - If the path does exist, the path is [coerced to a file set](#sec-fileset-path-coercion).
 163     - If the path does not exist, a file set containing no files is returned.
 164
 165     # Inputs
 166
 167     `path`
 168
 169     : 1\. Function argument
 170
 171     # Type
 172
 173     ```
 174     maybeMissing :: Path -> FileSet
 175     ```
 176
 177     # Examples
 178     :::{.example}
 179     ## `lib.fileset.maybeMissing` usage example
 180
 181     ```nix
 182     # All files in the current directory, but excluding main.o if it exists
 183     difference ./. (maybeMissing ./main.o)
 184     ```
 185
 186     :::
 187   */
 188   maybeMissing =
 189     path:
 190     if !isPath path then
 191       if isStringLike path then
 192         throw ''lib.fileset.maybeMissing: Argument ("${toString path}") is a string-like value, but it should be a path instead.''
 193       else
 194         throw ''lib.fileset.maybeMissing: Argument is of type ${typeOf path}, but it should be a path instead.''
 195     else if !pathExists path then
 196       _emptyWithoutBase
 197     else
 198       _singleton path;
 199
 200   /**
 201     Incrementally evaluate and trace a file set in a pretty way.
 202     This function is only intended for debugging purposes.
 203     The exact tracing format is unspecified and may change.
 204
 205     This function takes a final argument to return.
 206     In comparison, [`traceVal`](#function-library-lib.fileset.traceVal) returns
 207     the given file set argument.
 208
 209     This variant is useful for tracing file sets in the Nix repl.
 210
 211     # Inputs
 212
 213     `fileset`
 214
 215     : The file set to trace.
 216
 217       This argument can also be a path,
 218       which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 219
 220     `val`
 221
 222     : The value to return.
 223
 224     # Type
 225
 226     ```
 227     trace :: FileSet -> Any -> Any
 228     ```
 229
 230     # Examples
 231     :::{.example}
 232     ## `lib.fileset.trace` usage example
 233
 234     ```nix
 235     trace (unions [ ./Makefile ./src ./tests/run.sh ]) null
 236     =>
 237     trace: /home/user/src/myProject
 238     trace: - Makefile (regular)
 239     trace: - src (all files in directory)
 240     trace: - tests
 241     trace:   - run.sh (regular)
 242     null
 243     ```
 244
 245     :::
 246   */
 247   trace =
 248     fileset:
 249     let
 250       # "fileset" would be a better name, but that would clash with the argument name,
 251       # and we cannot change that because of https://github.com/nix-community/nixdoc/issues/76
 252       actualFileset = _coerce "lib.fileset.trace: Argument" fileset;
 253     in
 254     seq (_printFileset actualFileset) (x: x);
 255
 256   /**
 257     Incrementally evaluate and trace a file set in a pretty way.
 258     This function is only intended for debugging purposes.
 259     The exact tracing format is unspecified and may change.
 260
 261     This function returns the given file set.
 262     In comparison, [`trace`](#function-library-lib.fileset.trace) takes another argument to return.
 263
 264     This variant is useful for tracing file sets passed as arguments to other functions.
 265
 266     # Inputs
 267
 268     `fileset`
 269
 270     : The file set to trace and return.
 271
 272       This argument can also be a path,
 273       which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 274
 275     # Type
 276
 277     ```
 278     traceVal :: FileSet -> FileSet
 279     ```
 280
 281     # Examples
 282     :::{.example}
 283     ## `lib.fileset.traceVal` usage example
 284
 285     ```nix
 286     toSource {
 287       root = ./.;
 288       fileset = traceVal (unions [
 289         ./Makefile
 290         ./src
 291         ./tests/run.sh
 292       ]);
 293     }
 294     =>
 295     trace: /home/user/src/myProject
 296     trace: - Makefile (regular)
 297     trace: - src (all files in directory)
 298     trace: - tests
 299     trace:   - run.sh (regular)
 300     "/nix/store/...-source"
 301     ```
 302
 303     :::
 304   */
 305   traceVal =
 306     fileset:
 307     let
 308       # "fileset" would be a better name, but that would clash with the argument name,
 309       # and we cannot change that because of https://github.com/nix-community/nixdoc/issues/76
 310       actualFileset = _coerce "lib.fileset.traceVal: Argument" fileset;
 311     in
 312     seq (_printFileset actualFileset)
 313       # We could also return the original fileset argument here,
 314       # but that would then duplicate work for consumers of the fileset, because then they have to coerce it again
 315       actualFileset;
 316
 317   /**
 318     Add the local files contained in `fileset` to the store as a single [store path](https://nixos.org/manual/nix/stable/glossary#gloss-store-path) rooted at `root`.
 319
 320     The result is the store path as a string-like value, making it usable e.g. as the `src` of a derivation, or in string interpolation:
 321     ```nix
 322     stdenv.mkDerivation {
 323       src = lib.fileset.toSource { ... };
 324       # ...
 325     }
 326     ```
 327
 328     The name of the store path is always `source`.
 329
 330     # Inputs
 331
 332     Takes an attribute set with the following attributes
 333
 334     `root` (Path; _required_)
 335
 336     : The local directory [path](https://nixos.org/manual/nix/stable/language/values.html#type-path) that will correspond to the root of the resulting store path.
 337       Paths in [strings](https://nixos.org/manual/nix/stable/language/values.html#type-string), including Nix store paths, cannot be passed as `root`.
 338       `root` has to be a directory.
 339
 340       :::{.note}
 341       Changing `root` only affects the directory structure of the resulting store path, it does not change which files are added to the store.
 342       The only way to change which files get added to the store is by changing the `fileset` attribute.
 343       :::
 344
 345     `fileset` (FileSet; _required_)
 346
 347     : The file set whose files to import into the store.
 348       File sets can be created using other functions in this library.
 349       This argument can also be a path,
 350       which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 351
 352       :::{.note}
 353       If a directory does not recursively contain any file, it is omitted from the store path contents.
 354       :::
 355
 356     # Type
 357
 358     ```
 359     toSource :: {
 360       root :: Path,
 361       fileset :: FileSet,
 362     } -> SourceLike
 363     ```
 364
 365     # Examples
 366     :::{.example}
 367     ## `lib.fileset.toSource` usage example
 368
 369     ```nix
 370     # Import the current directory into the store
 371     # but only include files under ./src
 372     toSource {
 373       root = ./.;
 374       fileset = ./src;
 375     }
 376     => "/nix/store/...-source"
 377
 378     # Import the current directory into the store
 379     # but only include ./Makefile and all files under ./src
 380     toSource {
 381       root = ./.;
 382       fileset = union
 383         ./Makefile
 384         ./src;
 385     }
 386     => "/nix/store/...-source"
 387
 388     # Trying to include a file outside the root will fail
 389     toSource {
 390       root = ./.;
 391       fileset = unions [
 392         ./Makefile
 393         ./src
 394         ../LICENSE
 395       ];
 396     }
 397     => <error>
 398
 399     # The root needs to point to a directory that contains all the files
 400     toSource {
 401       root = ../.;
 402       fileset = unions [
 403         ./Makefile
 404         ./src
 405         ../LICENSE
 406       ];
 407     }
 408     => "/nix/store/...-source"
 409
 410     # The root has to be a local filesystem path
 411     toSource {
 412       root = "/nix/store/...-source";
 413       fileset = ./.;
 414     }
 415     => <error>
 416     ```
 417
 418     :::
 419   */
 420   toSource =
 421     {
 422       root,
 423       fileset,
 424     }:
 425     let
 426       # We cannot rename matched attribute arguments, so let's work around it with an extra `let in` statement
 427       filesetArg = fileset;
 428     in
 429     let
 430       fileset = _coerce "lib.fileset.toSource: `fileset`" filesetArg;
 431       rootFilesystemRoot = (splitRoot root).root;
 432       filesetFilesystemRoot = (splitRoot fileset._internalBase).root;
 433       sourceFilter = _toSourceFilter fileset;
 434     in
 435     if !isPath root then
 436       if root ? _isLibCleanSourceWith then
 437         throw ''
 438           lib.fileset.toSource: `root` is a `lib.sources`-based value, but it should be a path instead.
 439               To use a `lib.sources`-based value, convert it to a file set using `lib.fileset.fromSource` and pass it as `fileset`.
 440               Note that this only works for sources created from paths.''
 441       else if isStringLike root then
 442         throw ''
 443           lib.fileset.toSource: `root` (${toString root}) is a string-like value, but it should be a path instead.
 444               Paths in strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.''
 445       else
 446         throw ''lib.fileset.toSource: `root` is of type ${typeOf root}, but it should be a path instead.''
 447     # Currently all Nix paths have the same filesystem root, but this could change in the future.
 448     # See also ../path/README.md
 449     else if !fileset._internalIsEmptyWithoutBase && rootFilesystemRoot != filesetFilesystemRoot then
 450       throw ''
 451         lib.fileset.toSource: Filesystem roots are not the same for `fileset` and `root` (${toString root}):
 452             `root`: Filesystem root is "${toString rootFilesystemRoot}"
 453             `fileset`: Filesystem root is "${toString filesetFilesystemRoot}"
 454             Different filesystem roots are not supported.''
 455     else if !pathExists root then
 456       throw ''lib.fileset.toSource: `root` (${toString root}) is a path that does not exist.''
 457     else if pathType root != "directory" then
 458       throw ''
 459         lib.fileset.toSource: `root` (${toString root}) is a file, but it should be a directory instead. Potential solutions:
 460             - If you want to import the file into the store _without_ a containing directory, use string interpolation or `builtins.path` instead of this function.
 461             - If you want to import the file into the store _with_ a containing directory, set `root` to the containing directory, such as ${toString (dirOf root)}, and set `fileset` to the file path.''
 462     else if !fileset._internalIsEmptyWithoutBase && !hasPrefix root fileset._internalBase then
 463       throw ''
 464         lib.fileset.toSource: `fileset` could contain files in ${toString fileset._internalBase}, which is not under the `root` (${toString root}). Potential solutions:
 465             - Set `root` to ${toString fileset._internalBase} or any directory higher up. This changes the layout of the resulting store path.
 466             - Set `fileset` to a file set that cannot contain files outside the `root` (${toString root}). This could change the files included in the result.''
 467     else
 468       seq sourceFilter cleanSourceWith {
 469         name = "source";
 470         src = root;
 471         filter = sourceFilter;
 472       };
 473
 474   /**
 475     The list of file paths contained in the given file set.
 476
 477     :::{.note}
 478     This function is strict in the entire file set.
 479     This is in contrast with combinators [`lib.fileset.union`](#function-library-lib.fileset.union),
 480     [`lib.fileset.intersection`](#function-library-lib.fileset.intersection) and [`lib.fileset.difference`](#function-library-lib.fileset.difference).
 481
 482     Thus it is recommended to call `toList` on file sets created using the combinators,
 483     instead of doing list processing on the result of `toList`.
 484     :::
 485
 486     The resulting list of files can be turned back into a file set using [`lib.fileset.unions`](#function-library-lib.fileset.unions).
 487
 488     # Inputs
 489
 490     `fileset`
 491
 492     : The file set whose file paths to return. This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 493
 494     # Type
 495
 496     ```
 497     toList :: FileSet -> [ Path ]
 498     ```
 499
 500     # Examples
 501     :::{.example}
 502     ## `lib.fileset.toList` usage example
 503
 504     ```nix
 505     toList ./.
 506     [ ./README.md ./Makefile ./src/main.c ./src/main.h ]
 507
 508     toList (difference ./. ./src)
 509     [ ./README.md ./Makefile ]
 510     ```
 511
 512     :::
 513   */
 514   toList = fileset: _toList (_coerce "lib.fileset.toList: Argument" fileset);
 515
 516   /**
 517     The file set containing all files that are in either of two given file sets.
 518     This is the same as [`unions`](#function-library-lib.fileset.unions),
 519     but takes just two file sets instead of a list.
 520     See also [Union (set theory)](https://en.wikipedia.org/wiki/Union_(set_theory)).
 521
 522     The given file sets are evaluated as lazily as possible,
 523     with the first argument being evaluated first if needed.
 524
 525     # Inputs
 526
 527     `fileset1`
 528
 529     : The first file set. This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 530
 531     `fileset2`
 532
 533     : The second file set. This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 534
 535     # Type
 536
 537     ```
 538     union :: FileSet -> FileSet -> FileSet
 539     ```
 540
 541     # Examples
 542     :::{.example}
 543     ## `lib.fileset.union` usage example
 544
 545     ```nix
 546     # Create a file set containing the file `Makefile`
 547     # and all files recursively in the `src` directory
 548     union ./Makefile ./src
 549
 550     # Create a file set containing the file `Makefile`
 551     # and the LICENSE file from the parent directory
 552     union ./Makefile ../LICENSE
 553     ```
 554
 555     :::
 556   */
 557   union =
 558     fileset1: fileset2:
 559     _unionMany (
 560       _coerceMany "lib.fileset.union" [
 561         {
 562           context = "First argument";
 563           value = fileset1;
 564         }
 565         {
 566           context = "Second argument";
 567           value = fileset2;
 568         }
 569       ]
 570     );
 571
 572   /**
 573     The file set containing all files that are in any of the given file sets.
 574     This is the same as [`union`](#function-library-lib.fileset.unions),
 575     but takes a list of file sets instead of just two.
 576     See also [Union (set theory)](https://en.wikipedia.org/wiki/Union_(set_theory)).
 577
 578     The given file sets are evaluated as lazily as possible,
 579     with earlier elements being evaluated first if needed.
 580
 581     # Inputs
 582
 583     `filesets`
 584
 585     : A list of file sets. The elements can also be paths, which get [implicitly coerced to file sets](#sec-fileset-path-coercion).
 586
 587     # Type
 588
 589     ```
 590     unions :: [ FileSet ] -> FileSet
 591     ```
 592
 593     # Examples
 594     :::{.example}
 595     ## `lib.fileset.unions` usage example
 596
 597     ```nix
 598     # Create a file set containing selected files
 599     unions [
 600       # Include the single file `Makefile` in the current directory
 601       # This errors if the file doesn't exist
 602       ./Makefile
 603
 604       # Recursively include all files in the `src/code` directory
 605       # If this directory is empty this has no effect
 606       ./src/code
 607
 608       # Include the files `run.sh` and `unit.c` from the `tests` directory
 609       ./tests/run.sh
 610       ./tests/unit.c
 611
 612       # Include the `LICENSE` file from the parent directory
 613       ../LICENSE
 614     ]
 615     ```
 616
 617     :::
 618   */
 619   unions =
 620     filesets:
 621     if !isList filesets then
 622       throw ''lib.fileset.unions: Argument is of type ${typeOf filesets}, but it should be a list instead.''
 623     else
 624       pipe filesets [
 625         # Annotate the elements with context, used by _coerceMany for better errors
 626         (imap0 (
 627           i: el: {
 628             context = "Element ${toString i}";
 629             value = el;
 630           }
 631         ))
 632         (_coerceMany "lib.fileset.unions")
 633         _unionMany
 634       ];
 635
 636   /**
 637     The file set containing all files that are in both of two given file sets.
 638     See also [Intersection (set theory)](https://en.wikipedia.org/wiki/Intersection_(set_theory)).
 639
 640     The given file sets are evaluated as lazily as possible,
 641     with the first argument being evaluated first if needed.
 642
 643     # Inputs
 644
 645     `fileset1`
 646
 647     : The first file set. This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 648
 649     `fileset2`
 650
 651     : The second file set. This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 652
 653     # Type
 654
 655     ```
 656     intersection :: FileSet -> FileSet -> FileSet
 657     ```
 658
 659     # Examples
 660     :::{.example}
 661     ## `lib.fileset.intersection` usage example
 662
 663     ```nix
 664     # Limit the selected files to the ones in ./., so only ./src and ./Makefile
 665     intersection ./. (unions [ ../LICENSE ./src ./Makefile ])
 666     ```
 667
 668     :::
 669   */
 670   intersection =
 671     fileset1: fileset2:
 672     let
 673       filesets = _coerceMany "lib.fileset.intersection" [
 674         {
 675           context = "First argument";
 676           value = fileset1;
 677         }
 678         {
 679           context = "Second argument";
 680           value = fileset2;
 681         }
 682       ];
 683     in
 684     _intersection (elemAt filesets 0) (elemAt filesets 1);
 685
 686   /**
 687     The file set containing all files from the first file set that are not in the second file set.
 688     See also [Difference (set theory)](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement).
 689
 690     The given file sets are evaluated as lazily as possible,
 691     with the first argument being evaluated first if needed.
 692
 693     # Inputs
 694
 695     `positive`
 696
 697     : The positive file set. The result can only contain files that are also in this file set.  This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 698
 699     `negative`
 700
 701     : The negative file set. The result will never contain files that are also in this file set.  This argument can also be a path, which gets [implicitly coerced to a file set](#sec-fileset-path-coercion).
 702
 703     # Type
 704
 705     ```
 706     union :: FileSet -> FileSet -> FileSet
 707     ```
 708
 709     # Examples
 710     :::{.example}
 711     ## `lib.fileset.difference` usage example
 712
 713     ```nix
 714     # Create a file set containing all files from the current directory,
 715     # except ones under ./tests
 716     difference ./. ./tests
 717
 718     let
 719       # A set of Nix-related files
 720       nixFiles = unions [ ./default.nix ./nix ./tests/default.nix ];
 721     in
 722     # Create a file set containing all files under ./tests, except ones in `nixFiles`,
 723     # meaning only without ./tests/default.nix
 724     difference ./tests nixFiles
 725     ```
 726
 727     :::
 728   */
 729   difference =
 730     positive: negative:
 731     let
 732       filesets = _coerceMany "lib.fileset.difference" [
 733         {
 734           context = "First argument (positive set)";
 735           value = positive;
 736         }
 737         {
 738           context = "Second argument (negative set)";
 739           value = negative;
 740         }
 741       ];
 742     in
 743     _difference (elemAt filesets 0) (elemAt filesets 1);
 744
 745   /**
 746     Filter a file set to only contain files matching some predicate.
 747
 748     # Inputs
 749
 750     `predicate`
 751
 752     : The predicate function to call on all files contained in given file set.
 753       A file is included in the resulting file set if this function returns true for it.
 754
 755       This function is called with an attribute set containing these attributes:
 756
 757       - `name` (String): The name of the file
 758
 759       - `type` (String, one of `"regular"`, `"symlink"` or `"unknown"`): The type of the file.
 760         This matches result of calling [`builtins.readFileType`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-readFileType) on the file's path.
 761
 762       - `hasExt` (String -> Bool): Whether the file has a certain file extension.
 763         `hasExt ext` is true only if `hasSuffix ".${ext}" name`.
 764
 765         This also means that e.g. for a file with name `.gitignore`,
 766         `hasExt "gitignore"` is true.
 767
 768       Other attributes may be added in the future.
 769
 770     `path`
 771
 772     : The path whose files to filter
 773
 774     # Type
 775
 776     ```
 777     fileFilter ::
 778       ({
 779         name :: String,
 780         type :: String,
 781         hasExt :: String -> Bool,
 782         ...
 783       } -> Bool)
 784       -> Path
 785       -> FileSet
 786     ```
 787
 788     # Examples
 789     :::{.example}
 790     ## `lib.fileset.fileFilter` usage example
 791
 792     ```nix
 793     # Include all regular `default.nix` files in the current directory
 794     fileFilter (file: file.name == "default.nix") ./.
 795
 796     # Include all non-Nix files from the current directory
 797     fileFilter (file: ! file.hasExt "nix") ./.
 798
 799     # Include all files that start with a "." in the current directory
 800     fileFilter (file: hasPrefix "." file.name) ./.
 801
 802     # Include all regular files (not symlinks or others) in the current directory
 803     fileFilter (file: file.type == "regular") ./.
 804     ```
 805
 806     :::
 807   */
 808   fileFilter =
 809     predicate: path:
 810     if !isFunction predicate then
 811       throw ''lib.fileset.fileFilter: First argument is of type ${typeOf predicate}, but it should be a function instead.''
 812     else if !isPath path then
 813       if path._type or "" == "fileset" then
 814         throw ''
 815           lib.fileset.fileFilter: Second argument is a file set, but it should be a path instead.
 816               If you need to filter files in a file set, use `intersection fileset (fileFilter pred ./.)` instead.''
 817       else
 818         throw ''lib.fileset.fileFilter: Second argument is of type ${typeOf path}, but it should be a path instead.''
 819     else if !pathExists path then
 820       throw ''lib.fileset.fileFilter: Second argument (${toString path}) is a path that does not exist.''
 821     else
 822       _fileFilter predicate path;
 823
 824   /**
 825     Create a file set with the same files as a `lib.sources`-based value.
 826     This does not import any of the files into the store.
 827
 828     This can be used to gradually migrate from `lib.sources`-based filtering to `lib.fileset`.
 829
 830     A file set can be turned back into a source using [`toSource`](#function-library-lib.fileset.toSource).
 831
 832     :::{.note}
 833     File sets cannot represent empty directories.
 834     Turning the result of this function back into a source using `toSource` will therefore not preserve empty directories.
 835     :::
 836
 837     # Inputs
 838
 839     `source`
 840
 841     : 1\. Function argument
 842
 843     # Type
 844
 845     ```
 846     fromSource :: SourceLike -> FileSet
 847     ```
 848
 849     # Examples
 850     :::{.example}
 851     ## `lib.fileset.fromSource` usage example
 852
 853     ```nix
 854     # There's no cleanSource-like function for file sets yet,
 855     # but we can just convert cleanSource to a file set and use it that way
 856     toSource {
 857       root = ./.;
 858       fileset = fromSource (lib.sources.cleanSource ./.);
 859     }
 860
 861     # Keeping a previous sourceByRegex (which could be migrated to `lib.fileset.unions`),
 862     # but removing a subdirectory using file set functions
 863     difference
 864       (fromSource (lib.sources.sourceByRegex ./. [
 865         "^README\.md$"
 866         # This regex includes everything in ./doc
 867         "^doc(/.*)?$"
 868       ])
 869       ./doc/generated
 870
 871     # Use cleanSource, but limit it to only include ./Makefile and files under ./src
 872     intersection
 873       (fromSource (lib.sources.cleanSource ./.))
 874       (unions [
 875         ./Makefile
 876         ./src
 877       ]);
 878     ```
 879
 880     :::
 881   */
 882   fromSource =
 883     source:
 884     let
 885       # This function uses `._isLibCleanSourceWith`, `.origSrc` and `.filter`,
 886       # which are technically internal to lib.sources,
 887       # but we'll allow this since both libraries are in the same code base
 888       # and this function is a bridge between them.
 889       isFiltered = source ? _isLibCleanSourceWith;
 890       path = if isFiltered then source.origSrc else source;
 891     in
 892     # We can only support sources created from paths
 893     if !isPath path then
 894       if isStringLike path then
 895         throw ''
 896           lib.fileset.fromSource: The source origin of the argument is a string-like value ("${toString path}"), but it should be a path instead.
 897               Sources created from paths in strings cannot be turned into file sets, use `lib.sources` or derivations instead.''
 898       else
 899         throw ''lib.fileset.fromSource: The source origin of the argument is of type ${typeOf path}, but it should be a path instead.''
 900     else if !pathExists path then
 901       throw ''lib.fileset.fromSource: The source origin (${toString path}) of the argument is a path that does not exist.''
 902     else if isFiltered then
 903       _fromSourceFilter path source.filter
 904     else
 905       # If there's no filter, no need to run the expensive conversion, all subpaths will be included
 906       _singleton path;
 907
 908   /**
 909     Create a file set containing all [Git-tracked files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) in a repository.
 910
 911     This function behaves like [`gitTrackedWith { }`](#function-library-lib.fileset.gitTrackedWith) - using the defaults.
 912
 913     # Inputs
 914
 915     `path`
 916
 917     : The [path](https://nixos.org/manual/nix/stable/language/values#type-path) to the working directory of a local Git repository.
 918       This directory must contain a `.git` file or subdirectory.
 919
 920     # Type
 921
 922     ```
 923     gitTracked :: Path -> FileSet
 924     ```
 925
 926     # Examples
 927     :::{.example}
 928     ## `lib.fileset.gitTracked` usage example
 929
 930     ```nix
 931     # Include all files tracked by the Git repository in the current directory
 932     gitTracked ./.
 933
 934     # Include only files tracked by the Git repository in the parent directory
 935     # that are also in the current directory
 936     intersection ./. (gitTracked ../.)
 937     ```
 938
 939     :::
 940   */
 941   gitTracked = path: _fromFetchGit "gitTracked" "argument" path { };
 942
 943   /**
 944     Create a file set containing all [Git-tracked files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) in a repository.
 945     The first argument allows configuration with an attribute set,
 946     while the second argument is the path to the Git working tree.
 947
 948     `gitTrackedWith` does not perform any filtering when the path is a [Nix store path](https://nixos.org/manual/nix/stable/store/store-path.html#store-path) and not a repository.
 949     In this way, it accommodates the use case where the expression that makes the `gitTracked` call does not reside in an actual git repository anymore,
 950     and has presumably already been fetched in a way that excludes untracked files.
 951     Fetchers with such equivalent behavior include `builtins.fetchGit`, `builtins.fetchTree` (experimental), and `pkgs.fetchgit` when used without `leaveDotGit`.
 952
 953     If you don't need the configuration,
 954     you can use [`gitTracked`](#function-library-lib.fileset.gitTracked) instead.
 955
 956     This is equivalent to the result of [`unions`](#function-library-lib.fileset.unions) on all files returned by [`git ls-files`](https://git-scm.com/docs/git-ls-files)
 957     (which uses [`--cached`](https://git-scm.com/docs/git-ls-files#Documentation/git-ls-files.txt--c) by default).
 958
 959     :::{.warning}
 960     Currently this function is based on [`builtins.fetchGit`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchGit)
 961     As such, this function causes all Git-tracked files to be unnecessarily added to the Nix store,
 962     without being re-usable by [`toSource`](#function-library-lib.fileset.toSource).
 963
 964     This may change in the future.
 965     :::
 966
 967     # Inputs
 968
 969     `options` (attribute set)
 970     : `recurseSubmodules` (optional, default: `false`)
 971       : Whether to recurse into [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to also include their tracked files.
 972         If `true`, this is equivalent to passing the [--recurse-submodules](https://git-scm.com/docs/git-ls-files#Documentation/git-ls-files.txt---recurse-submodules) flag to `git ls-files`.
 973
 974       `path`
 975       : The [path](https://nixos.org/manual/nix/stable/language/values#type-path) to the working directory of a local Git repository.
 976         This directory must contain a `.git` file or subdirectory.
 977
 978     # Type
 979
 980     ```
 981     gitTrackedWith :: { recurseSubmodules :: Bool ? false } -> Path -> FileSet
 982     ```
 983
 984     # Examples
 985     :::{.example}
 986     ## `lib.fileset.gitTrackedWith` usage example
 987
 988     ```nix
 989     # Include all files tracked by the Git repository in the current directory
 990     # and any submodules under it
 991     gitTracked { recurseSubmodules = true; } ./.
 992     ```
 993
 994     :::
 995   */
 996   gitTrackedWith =
 997     {
 998       recurseSubmodules ? false,
 999     }:
1000     path:
1001     if !isBool recurseSubmodules then
1002       throw "lib.fileset.gitTrackedWith: Expected the attribute `recurseSubmodules` of the first argument to be a boolean, but it's a ${typeOf recurseSubmodules} instead."
1003     else if recurseSubmodules && versionOlder nixVersion _fetchGitSubmodulesMinver then
1004       throw "lib.fileset.gitTrackedWith: Setting the attribute `recurseSubmodules` to `true` is only supported for Nix version ${_fetchGitSubmodulesMinver} and after, but Nix version ${nixVersion} is used."
1005     else
1006       _fromFetchGit "gitTrackedWith" "second argument" path
1007         # This is the only `fetchGit` parameter that makes sense in this context.
1008         # We can't just pass `submodules = recurseSubmodules` here because
1009         # this would fail for Nix versions that don't support `submodules`.
1010         (
1011           lib.optionalAttrs recurseSubmodules {
1012             submodules = true;
1013           }
1014         );
1015 }