maintainers: remove email for amuckstot30 (#360059)
[NixPkgs.git] / doc / functions / nix-gitignore.section.md
blob8532ab68ac047503dc20c3899e72064048178d75
1 # pkgs.nix-gitignore {#sec-pkgs-nix-gitignore}
3 `pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format.
5 ## Usage {#sec-pkgs-nix-gitignore-usage}
7 `pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
9 ```nix
10 { pkgs ? import <nixpkgs> {} }: {
12  src = nix-gitignore.gitignoreSource [] ./source;
13      # Simplest version
15  src = nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source;
16      # This one reads the ./source/.gitignore and concats the auxiliary ignores
18  src = nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source;
19      # Use this string as gitignore, don't read ./source/.gitignore.
21  src = nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n" ~/.gitignore] ./source;
22      # It also accepts a list (of strings and paths) that will be concatenated
23      # once the paths are turned to strings via readFile.
25 ```
27 These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
29 ```nix
31   gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
32   gitignoreSource = gitignoreFilterSource (_: _: true);
34 ```
36 Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.
38 If you want to make your own filter from scratch, you may use
40 ```nix
42   gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
44 ```
46 ## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
48 If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
50 ```nix
52   # gitignoreFilterRecursiveSource = filter: patterns: root:
53   # OR
54   gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
56 ```