mirror of
https://github.com/numtide/nix-filter.git
synced 2024-09-11 14:16:38 +03:00
README: improve content
This commit is contained in:
parent
cf06efe613
commit
e720715870
54
README.md
54
README.md
@ -55,9 +55,18 @@ stdenv.mkDerivation {
|
||||
}
|
||||
```
|
||||
|
||||
## How it works
|
||||
# Usage
|
||||
|
||||
nix-filter is a function that takes:
|
||||
Import this folder. Eg:
|
||||
|
||||
```nix
|
||||
let
|
||||
nix-filter = import ./path/to/nix-filter;
|
||||
in
|
||||
# ...
|
||||
```
|
||||
|
||||
The top-level is a functor 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
|
||||
@ -75,10 +84,12 @@ the pattern matches.
|
||||
|
||||
## Builtin matchers
|
||||
|
||||
* `matchExt`: `ext` -> returns a function that matches the given file extension.
|
||||
* `inDirectory`: `directory` -> returns a function that matches a directory and
|
||||
The functor also contains a number of matchers:
|
||||
|
||||
* `nix-filter.matchExt`: `ext` -> returns a function that matches the given file extension.
|
||||
* `nix-filer.inDirectory`: `directory` -> returns a function that matches a directory and
|
||||
any path inside of it.
|
||||
* `isDirectory`: matches all paths that are directories
|
||||
* `nix-filter.isDirectory`: matches all paths that are directories
|
||||
|
||||
## Combining matchers
|
||||
|
||||
@ -87,9 +98,38 @@ the pattern matches.
|
||||
* `or`: `a -> b -> c`
|
||||
combines the result of two matchers into a new matcher.
|
||||
|
||||
## Future development
|
||||
# Design notes
|
||||
|
||||
Solve the above issue. Add more matchers.
|
||||
This solution uses `builtins.path { path, name, filter ? path: type: true }`
|
||||
under the hood, which ships with Nix.
|
||||
|
||||
While traversing the filesystem, starting from `path`, it will call `filter`
|
||||
on each file and folder recursively. If the `filter` returns `false` then the
|
||||
file or folder is ignored. If a folder is ignored, it won't recurse into it
|
||||
anymore.
|
||||
|
||||
Because of that, it makes it difficult to implement recursive glob matchers.
|
||||
Something like `**/*.js` would necessarily have to add every folder, to be
|
||||
able to traverse them. And those empty folders will end-up in the output.
|
||||
|
||||
If we want to control rebuild, it's important to have a fixed set of folders.
|
||||
|
||||
One possibility is to use a two-pass system, where first all the folders are
|
||||
being added, and then the empty ones are being filtered out. But all of this
|
||||
happens at Nix evaluation time. Nix evaluation is already slow enough like
|
||||
that.
|
||||
|
||||
That's why nix-filter is asking the users to explicitly list all the folders
|
||||
that they want to add.
|
||||
|
||||
# Future development
|
||||
|
||||
Add more matchers.
|
||||
|
||||
# Related projects
|
||||
|
||||
* nixpkgs' `lib.cleanSourceWith`.
|
||||
* All the git-based solutions. See https://github.com/hercules-ci/gitignore.nix#comparison
|
||||
|
||||
# License
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user