pyrox.dev
Merge pull request #125702 from alarsyo/db-to-md-nix-gitignore
doc: nix-gitignore to CommonMark
authored by Ryan Mulligan and committed by GitHub c43e0f48 3b4cace6
+1
-1
doc/functions.xml
+1
-1
doc/functions.xml
+49
doc/functions/nix-gitignore.section.md
+49
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
+
nix-gitignore.gitignoreSource [] ./source
13
+
# Simplest version
14
+
15
+
nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
16
+
# This one reads the ./source/.gitignore and concats the auxiliary ignores
17
+
18
+
nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
19
+
# Use this string as gitignore, don't read ./source/.gitignore.
20
+
21
+
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
+
These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
27
+
28
+
```nix
29
+
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
30
+
gitignoreSource = gitignoreFilterSource (_: _: true);
31
+
```
32
+
33
+
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.
34
+
35
+
If you want to make your own filter from scratch, you may use
36
+
37
+
```nix
38
+
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
39
+
```
40
+
41
+
## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
42
+
43
+
If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
44
+
45
+
```nix
46
+
gitignoreFilterRecursiveSource = filter: patterns: root:
47
+
# OR
48
+
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
49
+
```
-70
doc/functions/nix-gitignore.xml
-70
doc/functions/nix-gitignore.xml
···
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[
40
-
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
41
-
gitignoreSource = 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[
53
-
gitignoreFilter = 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[
65
-
gitignoreFilterRecursiveSource = filter: patterns: root:
66
-
# OR
67
-
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
68
-
]]></programlisting>
69
-
</section>
70
-
</section>
···