nix-gitignore: init at v3.0.0 (#46112)

closes siers/nix-gitignore#6

doc/functions.xml

@@ -17,4 +17,5 @@
  <xi:include href="functions/shell.xml" />
  <xi:include href="functions/dockertools.xml" />
  <xi:include href="functions/prefer-remote-fetch.xml" />
+ <xi:include href="functions/nix-gitignore.xml" />
 </chapter>

doc/functions/nix-gitignore.xml

@@ -0,0 +1,78 @@
+<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>