From 26ac257e4fecc050f28da30399afdfee83d98836 Mon Sep 17 00:00:00 2001 From: Antoine Martin Date: Fri, 4 Jun 2021 18:22:19 +0200 Subject: doc: nix-gitignore to CommonMark Closes #125670 --- doc/functions.xml | 2 +- doc/functions/nix-gitignore.section.md | 49 ++++++++++++++++++++++++ doc/functions/nix-gitignore.xml | 70 ---------------------------------- 3 files changed, 50 insertions(+), 71 deletions(-) create mode 100644 doc/functions/nix-gitignore.section.md delete mode 100644 doc/functions/nix-gitignore.xml (limited to 'doc') diff --git a/doc/functions.xml b/doc/functions.xml index 5a9240ec800..e8ab8d97b91 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -10,5 +10,5 @@ - + diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md new file mode 100644 index 00000000000..2fb833b2300 --- /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 {} }: + + 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 37a82b196cc..00000000000 --- a/doc/functions/nix-gitignore.xml +++ /dev/null @@ -1,70 +0,0 @@ -
- 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 - - - 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-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): - - - - - - 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 iff it's blacklisted by either your filter or the gitignoreFilter. - - - - If you want to make your own filter from scratch, you may use - - - -
- -
- gitignore files in subdirectories - - - If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: - - - -
-
-- cgit 1.4.1