nixpkgs-suyu/doc/functions/nix-gitignore.xml

<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xml:id="sec-pkgs-nix-gitignore">
 <title>pkgs.nix-gitignore</title>

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

 <section xml:id="sec-pkgs-nix-gitignore-usage">
  <title>Usage</title>

  <para>
   <literal>pkgs.nix-gitignore</literal> exports a number of functions, but
   you'll most likely need either <literal>gitignoreSource</literal> or
   <literal>gitignoreSourcePure</literal>. 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.
  </para>

<programlisting><![CDATA[
{ pkgs ? import <nixpkgs> {} }:

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

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

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

 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.
  ]]></programlisting>

  <para>
   These functions are derived from the <literal>Filter</literal> functions by
   setting the first filter argument to <literal>(_: _: true)</literal>:
  </para>

<programlisting><![CDATA[
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
gitignoreSource = gitignoreFilterSource (_: _: true);
  ]]></programlisting>

  <para>
   Those filter functions accept the same arguments the
   <literal>builtins.filterSource</literal> function would pass to its filters,
   thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be
   extensionally equivalent to <literal>filterSource</literal>. The file is
   blacklisted iff it's blacklisted by either your filter or the
   gitignoreFilter.
  </para>

  <para>
   If you want to make your own filter from scratch, you may use
  </para>

<programlisting><![CDATA[
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
  ]]></programlisting>
 </section>

 <section xml:id="sec-pkgs-nix-gitignore-usage-recursive">
  <title>gitignore files in subdirectories</title>

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

<programlisting><![CDATA[
gitignoreFilterRecursiveSource = filter: patterns: root:
# OR
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
  ]]></programlisting>
 </section>
</section>