@@ -0,0 +1,40 @@
1+# cleanGit
2+
3+To filter out just the files in your git index use
4+`haskell-nix.haskellLib.cleanGit { src = ./.; }` where `./.` is the
5+root of your git repo (or a git work tree).
6+
7+First it filters just the files needed to run `git index`, then
8+it uses the results of that to filter your directory. It does not
9+need to parse the `.gitignore` files at all, but we do need to
10+`git add` our files before they will be included.
11+[cleanGit source](https://github.com/input-output-hk/haskell.nix/blob/master/lib/clean-git.nix).
12+
13+In addition haskell.nix (including `cleanGit`) uses a version
14+of [`cleanSourceWith`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/clean-source-with.nix)
15+with a `subdir` argument to filter out just the package it is
16+building. Then it uses the info from the `cabal` file to filter
17+just the source dirs for the component it is building. That way
18+if we modify a test in a package nix will not rebuild the library
19+in that package (or anything that depends on that package's library).
20+
21+There is a downside to this though. If we have a test that depends
22+on something outside the scope of what is described in its entry in
23+the in the `.cabal` file it will not see it. For instance perhaps
24+it needs to run `hlint` or `doctest` on the library source. There
25+are ways to fix this with a module:
26+
27+Use `extraSrcFiles` to add dirs the test needs (this will not result
28+in a change to the `.cabal` file the test will still be built the same).
29+```
30+components.tests.test.extraSrcFiles = [ "subdir-needed-by-test" ];
31+```
32+Or alternatively, override the source with a suitable filter function.
33+```
34+components.tests.test.src = haskell-nix.haskellLib.cleanSourceWith {
35+ inherit src;
36+ subdir = "path-to-package";
37+ filter = ...
38+};
39+```
40+