diff options
author | Ryan Mulligan <ryan@ryantm.com> | 2021-06-06 07:35:06 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-06-06 07:35:06 -0700 |
commit | c43e0f48735f2e839b656b7b1ec792babeed6a15 (patch) | |
tree | 4806d071c410172790fcac96bb6bbd71ae101859 /doc | |
parent | 3b4cace64dc19096e6696cfc474fc47b7189e73b (diff) | |
parent | 26ac257e4fecc050f28da30399afdfee83d98836 (diff) |
Merge pull request #125702 from alarsyo/db-to-md-nix-gitignore
doc: nix-gitignore to CommonMark
Diffstat (limited to 'doc')
-rw-r--r-- | doc/functions.xml | 2 | ||||
-rw-r--r-- | doc/functions/nix-gitignore.section.md | 49 | ||||
-rw-r--r-- | doc/functions/nix-gitignore.xml | 70 |
3 files changed, 50 insertions, 71 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 5a9240ec800e2..e8ab8d97b913c 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -10,5 +10,5 @@ <xi:include href="functions/generators.xml" /> <xi:include href="functions/debug.xml" /> <xi:include href="functions/prefer-remote-fetch.xml" /> - <xi:include href="functions/nix-gitignore.xml" /> + <xi:include href="functions/nix-gitignore.section.xml" /> </chapter> diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md new file mode 100644 index 0000000000000..2fb833b230001 --- /dev/null +++ b/doc/functions/nix-gitignore.section.md @@ -0,0 +1,49 @@ +# pkgs.nix-gitignore {#sec-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 {#sec-pkgs-nix-gitignore-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. + +```nix +{ 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. +``` + +These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`: + +```nix +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 + +```nix +gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; +``` + +## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive} + +If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: + +```nix +gitignoreFilterRecursiveSource = filter: patterns: root: +# OR +gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); +``` diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml deleted file mode 100644 index 37a82b196ccf2..0000000000000 --- a/doc/functions/nix-gitignore.xml +++ /dev/null @@ -1,70 +0,0 @@ -<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> |