pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 xml:id="sec-pkgs-nix-gitignore">
5 <title>pkgs.nix-gitignore</title>
6
7 <para>
8 <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.
9 </para>
10
11 <section xml:id="sec-pkgs-nix-gitignore-usage">
12 <title>Usage</title>
13
14 <para>
15 <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.
16 </para>
17
18<programlisting><![CDATA[
19{ pkgs ? import <nixpkgs> {} }:
20
21 nix-gitignore.gitignoreSource [] ./source
22 # Simplest version
23
24 nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
25 # This one reads the ./source/.gitignore and concats the auxiliary ignores
26
27 nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
28 # Use this string as gitignore, don't read ./source/.gitignore.
29
30 nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source
31 # It also accepts a list (of strings and paths) that will be concatenated
32 # once the paths are turned to strings via readFile.
33 ]]></programlisting>
34
35 <para>
36 These functions are derived from the <literal>Filter</literal> functions by setting the first filter argument to <literal>(_: _: true)</literal>:
37 </para>
38
39<programlisting><![CDATA[
40gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
41gitignoreSource = gitignoreFilterSource (_: _: true);
42 ]]></programlisting>
43
44 <para>
45 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.
46 </para>
47
48 <para>
49 If you want to make your own filter from scratch, you may use
50 </para>
51
52<programlisting><![CDATA[
53gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
54 ]]></programlisting>
55 </section>
56
57 <section xml:id="sec-pkgs-nix-gitignore-usage-recursive">
58 <title>gitignore files in subdirectories</title>
59
60 <para>
61 If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
62 </para>
63
64<programlisting><![CDATA[
65gitignoreFilterRecursiveSource = filter: patterns: root:
66# OR
67gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
68 ]]></programlisting>
69 </section>
70</section>