diff options
author | Florian Klink <flokli@flokli.de> | 2022-06-03 11:17:25 +0200 |
---|---|---|
committer | Florian Klink <flokli@flokli.de> | 2022-06-03 14:37:31 +0200 |
commit | 1cefcfab2d3eb9274f4627a178a59d6f980f7f3b (patch) | |
tree | 25cd448fd8587224366f1ef48571f053eb4465eb | |
parent | 7b3000f1d0f24b5ad8bd51a70290167fc2819a50 (diff) |
nixos/doc: move fetchpatch documentation to fetcher documentation
… and link from the coding-conventions chapter to it. Closes #48569.
-rw-r--r-- | doc/builders/fetchers.chapter.md | 12 | ||||
-rw-r--r-- | 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 30591c1673c8f..70380248f8c65 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 41973292863c7..9a01b5a0828c8 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. |