diff options
author | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2023-09-02 06:00:55 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-09-02 06:00:55 +0000 |
commit | 45ced9b1f6c281f2d3768c47266165df5d4bd7e0 (patch) | |
tree | 435fddc756ede9b0bdc7dd225bae42835355d94c /doc | |
parent | 14f4a764c52f3ef68808542100c4580765fdd75d (diff) | |
parent | 9a1f3d1b1dc48aec0c7d68cb11703c7f9a7f286d (diff) | |
download | nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar.gz nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar.bz2 nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar.lz nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar.xz nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.tar.zst nixlib-45ced9b1f6c281f2d3768c47266165df5d4bd7e0.zip |
Merge master into staging-next
Diffstat (limited to 'doc')
-rw-r--r-- | doc/default.nix | 1 | ||||
-rw-r--r-- | doc/functions.md | 1 | ||||
-rw-r--r-- | doc/functions/fileset.section.md | 51 |
3 files changed, 53 insertions, 0 deletions
diff --git a/doc/default.nix b/doc/default.nix index 58b945c692fc..18e12c1a8aca 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -19,6 +19,7 @@ let { name = "options"; description = "NixOS / nixpkgs option handling"; } { name = "path"; description = "path functions"; } { name = "filesystem"; description = "filesystem functions"; } + { name = "fileset"; description = "file set functions"; } { name = "sources"; description = "source filtering functions"; } { name = "cli"; description = "command-line serialization functions"; } { name = "gvariant"; description = "GVariant formatted string serialization functions"; } diff --git a/doc/functions.md b/doc/functions.md index 09033c9e3c19..551ba522a904 100644 --- a/doc/functions.md +++ b/doc/functions.md @@ -8,4 +8,5 @@ functions/generators.section.md functions/debug.section.md functions/prefer-remote-fetch.section.md functions/nix-gitignore.section.md +functions/fileset.section.md ``` diff --git a/doc/functions/fileset.section.md b/doc/functions/fileset.section.md new file mode 100644 index 000000000000..b24ebe26cc3b --- /dev/null +++ b/doc/functions/fileset.section.md @@ -0,0 +1,51 @@ +<!-- TODO: Render this document in front of function documentation in case https://github.com/nix-community/nixdoc/issues/19 is ever supported --> + +# File sets {#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. + +These sections apply to the entire library. +See the [function reference](#sec-functions-library-fileset) for function-specific documentation. + +The file set library is currently very limited but is being expanded to include more functions over time. + +## 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. |