diff options
author | Raitis Veinbahs <wimuan@gmail.com> | 2019-02-18 11:57:30 +0200 |
---|---|---|
committer | zimbatm <zimbatm@zimbatm.com> | 2019-02-18 09:57:30 +0000 |
commit | d8a7a01fecb4dd05dead58f70ea4bfd0b8336459 (patch) | |
tree | c21d8981098c1ac0c4ca9cab29406f5487e4b676 /doc/functions | |
parent | 1472b9902acd70640d4e40636fcdd545669216a9 (diff) | |
download | nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar.gz nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar.bz2 nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar.lz nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar.xz nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.tar.zst nixpkgs-d8a7a01fecb4dd05dead58f70ea4bfd0b8336459.zip |
nix-gitignore: init at v3.0.0 (#46112)
closes siers/nix-gitignore#6
Diffstat (limited to 'doc/functions')
-rw-r--r-- | doc/functions/nix-gitignore.xml | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml new file mode 100644 index 00000000000..465b38e0bf1 --- /dev/null +++ b/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> |