depot/third_party/nixpkgs/doc/functions/nix-gitignore.section.md

pkgs.nix-gitignore

pkgs.nix-gitignore is a function that acts similarly to builtins.filterSource but also allows filtering with the help of the gitignore format.

Usage

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.

{ pkgs ? import <nixpkgs> {} }: {

 src = nix-gitignore.gitignoreSource [] ./source;
     # Simplest version

 src = nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source;
     # This one reads the ./source/.gitignore and concats the auxiliary ignores

 src = nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source;
     # Use this string as gitignore, don't read ./source/.gitignore.

 src = nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n" ~/.gitignore] ./source;
     # It also accepts a list (of strings and paths) that will be concatenated
     # once the paths are turned to strings via readFile.
}

These functions are derived from the Filter functions by setting the first filter argument to (_: _: true):

{
  gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
  gitignoreSource = gitignoreFilterSource (_: _: true);
}

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.

If you want to make your own filter from scratch, you may use

{
  gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
}

gitignore files in subdirectories

If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:

{
  # gitignoreFilterRecursiveSource = filter: patterns: root:
  # OR
  gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
}