From 1cefcfab2d3eb9274f4627a178a59d6f980f7f3b Mon Sep 17 00:00:00 2001 From: Florian Klink Date: Fri, 3 Jun 2022 11:17:25 +0200 Subject: [PATCH] nixos/doc: move fetchpatch documentation to fetcher documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit … and link from the coding-conventions chapter to it. Closes #48569. --- doc/builders/fetchers.chapter.md | 12 ++++++++++++ doc/contributing/coding-conventions.chapter.md | 13 ++----------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 30591c1673c8..70380248f8c6 100644 --- a/doc/builders/fetchers.chapter.md +++ b/doc/builders/fetchers.chapter.md @@ -26,8 +26,20 @@ stdenv.mkDerivation { The main difference between `fetchurl` and `fetchzip` is in how they store the contents. `fetchurl` will store the unaltered contents of the URL within the Nix store. `fetchzip` on the other hand, will decompress the archive for you, making files and directories directly accessible in the future. `fetchzip` can only be used with archives. Despite the name, `fetchzip` is not limited to .zip files and can also be used with any tarball. +## `fetchpatch` {#fetchpatch} + `fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example, it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time. +- `relative`: Similar to using `git-diff`'s `--relative` flag, only keep changes inside the specified directory, making paths relative to it. +- `stripLen`: Remove the first `stripLen` components of pathnames in the patch. +- `extraPrefix`: Prefix pathnames by this string. +- `excludes`: Exclude files matching these patterns (applies after the above arguments). +- `includes`: Include only files matching these patterns (applies after the above arguments). +- `revert`: Revert the patch. + +Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well. + + Most other fetchers return a directory rather than a single file. ## `fetchsvn` {#fetchsvn} diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index 41973292863c..9a01b5a0828c 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -511,6 +511,8 @@ patches = [ Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way. +If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [](#fetchpatch) for details. + ```nix patches = [ ./0001-changes.patch ]; ``` @@ -538,17 +540,6 @@ If you do need to do create this sort of patch file, one way to do so is with gi $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch ``` -If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`: - -- `relative`: Similar to using `git-diff`'s `--relative` flag, only keep changes inside the specified directory, making paths relative to it. -- `stripLen`: Remove the first `stripLen` components of pathnames in the patch. -- `extraPrefix`: Prefix pathnames by this string. -- `excludes`: Exclude files matching these patterns (applies after the above arguments). -- `includes`: Include only files matching these patterns (applies after the above arguments). -- `revert`: Revert the patch. - -Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well. - ## Package tests {#sec-package-tests} Tests are important to ensure quality and make reviews and automatic updates easy.