lib.fileset: Move introduction section above the functions
Previously the introductory section and the function listings were in different places. But now nixdoc supports having them together with https://github.com/nix-community/nixdoc/pull/70!
This commit is contained in:
parent
d24767aa8b
commit
228df50ff9
3 changed files with 49 additions and 49 deletions
|
@ -8,5 +8,4 @@ functions/generators.section.md
|
||||||
functions/debug.section.md
|
functions/debug.section.md
|
||||||
functions/prefer-remote-fetch.section.md
|
functions/prefer-remote-fetch.section.md
|
||||||
functions/nix-gitignore.section.md
|
functions/nix-gitignore.section.md
|
||||||
functions/fileset.section.md
|
|
||||||
```
|
```
|
||||||
|
|
|
@ -1,48 +0,0 @@
|
||||||
<!-- 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.
|
|
||||||
|
|
||||||
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.
|
|
|
@ -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 }:
|
{ lib }:
|
||||||
let
|
let
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue