doc/functions/nix-gitignore.section.md

   1 # pkgs.nix-gitignore {#sec-pkgs-nix-gitignore}
   2
   3 `pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format.
   4
   5 ## Usage {#sec-pkgs-nix-gitignore-usage}
   6
   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.
   8
   9 ```nix
  10 { pkgs ? import <nixpkgs> {} }: {
  11
  12  src = nix-gitignore.gitignoreSource [] ./source;
  13      # Simplest version
  14
  15  src = nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source;
  16      # This one reads the ./source/.gitignore and concats the auxiliary ignores
  17
  18  src = nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source;
  19      # Use this string as gitignore, don't read ./source/.gitignore.
  20
  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.
  24 }
  25 ```
  26
  27 These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
  28
  29 ```nix
  30 {
  31   gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
  32   gitignoreSource = gitignoreFilterSource (_: _: true);
  33 }
  34 ```
  35
  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.
  37
  38 If you want to make your own filter from scratch, you may use
  39
  40 ```nix
  41 {
  42   gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
  43 }
  44 ```
  45
  46 ## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
  47
  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:
  49
  50 ```nix
  51 {
  52   # gitignoreFilterRecursiveSource = filter: patterns: root:
  53   # OR
  54   gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
  55 }
  56 ```