Commit 228df50f authored by Silvan Mosberger's avatar Silvan Mosberger
Browse files

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!
parent d24767aa

doc/functions.md

+0 −1
Original line number Diff line number Diff line
@@ -8,5 +8,4 @@ functions/generators.section.md 
functions/debug.section.md

functions/prefer-remote-fetch.section.md

functions/nix-gitignore.section.md

functions/fileset.section.md

```

doc/functions/fileset.section.md

deleted100644 → 0
+0 −48
Original line number Diff line number Diff line 
<!-- 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.

lib/fileset/default.nix

+49 −0
Original line number Diff line number Diff line 
/*

  <!-- 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