Merge branch 'master' into more-pathExists

README.md

@@ -41,7 +41,8 @@ mkDerivation {
 }
 ```
 
-If you need something more specific, that can not be achieved with Nixpkgs' `cleanSourceWith` function, you may want to use [gitignoreFilter](docs/gitignoreFilter.md).
+You can use Nixpkgs' [`cleanSourceWith`](https://github.com/NixOS/nixpkgs/blob/d1bb36d5cb5b78111f799eb26f5f17e5979bc746/lib/sources.nix#L35-L67) to compose with other filters (by logical _and_) or to set a `name`.
+If you need something more exotic, you may want to use [gitignoreFilter](docs/gitignoreFilter.md) directly.
 
 # Features
 
@@ -81,6 +82,13 @@ If you need something more specific, that can not be achieved with Nixpkgs' `cle
 
 Please open a PR if you've found another feature, determined any of the '?' or found an inaccuracy!
 
+# Security
+
+Files not matched by gitignore rules will end up in the Nix store, which is readable by any process.
+
+gitignore.nix does not yet understand `git-crypt`'s metadata, so don't call `gitignoreSource` on directories containing such secrets or their parent directories.
+This applies to any Nix function that uses the `builtins.path` or `builtins.filterSource` functions.
+
 # Contributing
 
 This project isn't perfect (yet) so please submit test cases and fixes as pull requests. Before doing anything drastic, it's a good idea to open an issue first to discuss and optimize the approach.

docs/gitignoreFilter.md

@@ -0,0 +1,27 @@
+
+# `gitignoreFilter`
+
+If you want to use gitignore functionality in new ways, you may use the
+`gitignoreFilter` function directly. For performance, you should keep
+the number of `gitignoreFilter` calls to a minimum. It is a curried
+function for good reason. After applying the first argument, the root
+path of the source, it returns a function that memoizes information
+about the git directory structure. The function must only be invoked
+for paths at or below this root path.
+
+### Usage example
+
+```nix
+let
+  gitignore = (import (import ./nix/sources.nix)."gitignore.nix" { inherit lib; });
+  inherit (gitignore) gitignoreFilter;
+
+  useGitFilesInSomeWay = src:
+    let
+      # IMPORTANT: use a let binding like this to memoize info about the git directories.
+      f = gitignoreFilter src;
+    in
+      somethingUseful (path: type: f path type || false);
+in
+  useGitFilesInSomeWay ./.
+```