commit 228df50ff927e3b715ebfb54992432c4a91bd847 · pyrox.dev/nixpkgs

-1

doc/functions.md

···

       8
        
       functions/debug.section.md

     

       9
        
       functions/prefer-remote-fetch.section.md

     

       10
        
       functions/nix-gitignore.section.md

     

       11
       -
       functions/fileset.section.md

     

       12
        
       ```

···

       8
        
       functions/debug.section.md

     

       9
        
       functions/prefer-remote-fetch.section.md

     

       10
        
       functions/nix-gitignore.section.md

     

       0
        
       
     

       11
        
       ```

-48

doc/functions/fileset.section.md

···

       1
       -
       <!-- TODO: Render this document in front of function documentation in case https://github.com/nix-community/nixdoc/issues/19 is ever supported -->

     

       2
       -
       

     

       3
       -
       # File sets {#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
       -
       See the [function reference](#sec-functions-library-fileset) for function-specific documentation.

     

       10
       -
       

     

       11
       -
       ## Implicit coercion from paths to file sets {#sec-fileset-path-coercion}

     

       12
       -
       

     

       13
       -
       All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments.

     

       14
       -
       Such path arguments are implicitly coerced to file sets containing all files under that path:

     

       15
       -
       - A path to a file turns into a file set containing that single file.

     

       16
       -
       - A path to a directory turns into a file set containing all files _recursively_ in that directory.

     

       17
       -
       

     

       18
       -
       If the path points to a non-existent location, an error is thrown.

     

       19
       -
       

     

       20
       -
       ::: {.note}

     

       21
       -
       Just like in Git, file sets cannot represent empty directories.

     

       22
       -
       Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files.

     

       23
       -
       :::

     

       24
       -
       

     

       25
       -
       :::{.note}

     

       26
       -
       File set coercion does _not_ add any of the files under the coerced paths to the store.

     

       27
       -
       Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument.

     

       28
       -
       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.

     

       29
       -
       :::

     

       30
       -
       

     

       31
       -
       ### Example {#sec-fileset-path-coercion-example}

     

       32
       -
       

     

       33
       -
       Assume we are in a local directory with a file hierarchy like this:

     

       34
       -
       ```

     

       35
       -
       ├─ a/

     

       36
       -
       │  ├─ x (file)

     

       37
       -
       │  └─ b/

     

       38
       -
       │     └─ y (file)

     

       39
       -
       └─ c/

     

       40
       -
          └─ d/

     

       41
       -
       ```

     

       42
       -
       

     

       43
       -
       Here's a listing of which files get included when different path expressions get coerced to file sets:

     

       44
       -
       - `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted).

     

       45
       -
       - `./a` as a file set contains both `a/x` and `a/b/y`.

     

       46
       -
       - `./a/x` as a file set contains only `a/x`.

     

       47
       -
       - `./a/b` as a file set contains only `a/b/y`.

     

       48
       -
       - `./c` as a file set is empty, since neither `c` nor `c/d` contain any files.

+49

lib/fileset/default.nix

···

       1
       +
       /*

     

       2
       +
         <!-- This anchor is here for backwards compatibity -->

     

       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
       +
         See the [function reference](#sec-functions-library-fileset) for function-specific documentation.

     

       10
       +
       

     

       11
       +
         ## Implicit coercion from paths to file sets {#sec-fileset-path-coercion}

     

       12
       +
       

     

       13
       +
         All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments.

     

       14
       +
         Such path arguments are implicitly coerced to file sets containing all files under that path:

     

       15
       +
         - A path to a file turns into a file set containing that single file.

     

       16
       +
         - A path to a directory turns into a file set containing all files _recursively_ in that directory.

     

       17
       +
       

     

       18
       +
         If the path points to a non-existent location, an error is thrown.

     

       19
       +
       

     

       20
       +
         ::: {.note}

     

       21
       +
         Just like in Git, file sets cannot represent empty directories.

     

       22
       +
         Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files.

     

       23
       +
         :::

     

       24
       +
       

     

       25
       +
         :::{.note}

     

       26
       +
         File set coercion does _not_ add any of the files under the coerced paths to the store.

     

       27
       +
         Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument.

     

       28
       +
         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.

     

       29
       +
         :::

     

       30
       +
       

     

       31
       +
         ### Example {#sec-fileset-path-coercion-example}

     

       32
       +
       

     

       33
       +
         Assume we are in a local directory with a file hierarchy like this:

     

       34
       +
         ```

     

       35
       +
         ├─ a/

     

       36
       +
         │  ├─ x (file)

     

       37
       +
         │  └─ b/

     

       38
       +
         │     └─ y (file)

     

       39
       +
         └─ c/

     

       40
       +
            └─ d/

     

       41
       +
         ```

     

       42
       +
       

     

       43
       +
         Here's a listing of which files get included when different path expressions get coerced to file sets:

     

       44
       +
         - `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted).

     

       45
       +
         - `./a` as a file set contains both `a/x` and `a/b/y`.

     

       46
       +
         - `./a/x` as a file set contains only `a/x`.

     

       47
       +
         - `./a/b` as a file set contains only `a/b/y`.

     

       48
       +
         - `./c` as a file set is empty, since neither `c` nor `c/d` contain any files.

     

       49
       +
       */

     

       50
        
       { lib }:

     

       51
        
       let

     

       52