From 2806f965e60067171f04bab882cd3b1df2c4a713 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 28 Nov 2019 09:19:19 +0100
Subject: [PATCH 1/2] Document gitignoreFilter

---
 README.md               |  3 +++
 docs/gitignoreFilter.md | 27 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 docs/gitignoreFilter.md

diff --git a/README.md b/README.md
index 30323bf..9123fc5 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,9 @@ mkDerivation {
 }
 ```
 
+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
 
  - Reads parent gitignores even if only pointed at a subdirectory
diff --git a/docs/gitignoreFilter.md b/docs/gitignoreFilter.md
new file mode 100644
index 0000000..80217df
--- /dev/null
+++ b/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 ./.
+```

From 60f1454f9af0c0d83ade2195af8723b5bb54805a Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 28 Nov 2019 09:41:05 +0100
Subject: [PATCH 2/2] README.md: Add Security section

---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index 30323bf..4ab8c93 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,13 @@ mkDerivation {
 
 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.