2021-04-23 15:16:23 +03:00
|
|
|
# nix-filter - a small self-container source filtering lib
|
|
|
|
|
|
|
|
**STATUS: unstable**
|
|
|
|
|
|
|
|
A cool way to include only what you need.
|
|
|
|
|
|
|
|
When using nix within a project, developers often use `src = ./.;` for a
|
|
|
|
project like this:
|
|
|
|
|
|
|
|
```nix
|
|
|
|
{ stdenv }:
|
|
|
|
stdenv.mkDerivation {
|
|
|
|
name = "my-project";
|
|
|
|
src = ./.;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
This works but has an issue; on each build, nix will copy the whole project
|
|
|
|
source code into the /nix/store. Including the `.git` folder and any temporary
|
|
|
|
files left over by the editor.
|
|
|
|
|
|
|
|
The main workaround is to use either `builtins.fetchGit ./.` or one of the
|
|
|
|
many gitignore filter projects but this is not precise enough. If the
|
|
|
|
project README changes, it should rebuild the project. If the nix code
|
|
|
|
changes, it shouldn't rebuild the project. That's why this project exists. I
|
|
|
|
want total control.
|
|
|
|
|
|
|
|
## Example usage
|
|
|
|
|
|
|
|
```nix
|
|
|
|
{ stdenv, nix-filter }:
|
|
|
|
stdenv.mkDerivation {
|
|
|
|
name = "my-project";
|
|
|
|
src = nix-filter {
|
2021-04-23 19:53:18 +03:00
|
|
|
path = ./.;
|
2021-04-24 14:43:04 +03:00
|
|
|
include = [
|
2021-04-23 15:16:23 +03:00
|
|
|
"src" # strings are automatically converted to ./src filter
|
|
|
|
./package.json # paths are automatically converted to path filters
|
2021-04-23 20:19:37 +03:00
|
|
|
(nix-filter.matchExt "js") # create your own filters like that
|
2021-04-23 15:16:23 +03:00
|
|
|
];
|
|
|
|
|
2021-04-24 14:43:04 +03:00
|
|
|
exclude = [ ];
|
2021-04-23 15:16:23 +03:00
|
|
|
};
|
|
|
|
}
|
|
|
|
```
|
2021-04-23 20:19:37 +03:00
|
|
|
|
|
|
|
## How it works
|
|
|
|
|
|
|
|
nix-filter is a function that takes:
|
|
|
|
* `path` of type `path`: pointing to the root of the source to add to the
|
|
|
|
/nix/store.
|
|
|
|
* `name` of type `string` (optional): the name of the derivation (defaults to
|
|
|
|
"source")
|
2021-04-24 14:43:04 +03:00
|
|
|
* `include` of type `list(string|path|matcher)` (optional): a list of patterns to
|
2021-04-23 20:19:37 +03:00
|
|
|
include (defaults to all).
|
2021-04-24 14:43:04 +03:00
|
|
|
* `exclude` of type `list(string|path|matcher)` (options): a list of patterns to
|
2021-04-23 20:19:37 +03:00
|
|
|
exclude (defaults to none).
|
|
|
|
|
2021-04-24 14:43:04 +03:00
|
|
|
The `include` and `exclude` take a matcher, and automatically convert the `string`
|
2021-04-23 20:19:37 +03:00
|
|
|
and `path` types to a matcher.
|
|
|
|
|
|
|
|
The matcher is a function that takes a `path` and `type` and returns `true` if
|
|
|
|
the pattern matches.
|
|
|
|
|
|
|
|
## Builtin matchers
|
|
|
|
|
|
|
|
* `matchExt`: `ext` -> returns a function that matches the given file extension.
|
|
|
|
|
|
|
|
## Known limitation
|
|
|
|
|
|
|
|
Because of how Nix works, a file located under a sub-folder will not be
|
|
|
|
included if the folder isn't also matched.
|
|
|
|
|
|
|
|
Eg:
|
|
|
|
|
|
|
|
If the file is `src/frontend/index.js`, a matcher is needed for the `src`
|
|
|
|
folder, the `src/frontend` folder, *and* the `src/frontend/index.js` file.
|
|
|
|
|
|
|
|
## Future development
|
|
|
|
|
|
|
|
A glob matcher would be nice.
|
|
|
|
|
|
|
|
# License
|
|
|
|
|
|
|
|
Copyright (c) 2021 Numtide under the MIT.
|