View source for Nixpkgs/Update Scripts

Update Scripts can be added to packages via setting, <code><nowiki>passthru.updateScript</nowiki></code> which is then executed by [[r-ryantm]] to create an updated pull request or can be manually invoked via <code>nix-shell maintainers/scripts/update.nix --argstr package <packagename></code>.

== Update Scripts ==
List of prepackaged update scripts.

=== nix-update by Mic92 ===
[https://github.com/Mic92/nix-update nix-update] works for a range of different sources and will do the right thing most of the time.

<syntaxhighlight lang="nix">
passthru.updateScript = nix-update-script { };
</syntaxhighlight>

If you want functionality similar to that of unstableGitUpdater but with the additional handlers offered by nix-update, use:

<syntaxhighlight lang="nix">
passthru.updateScript = nix-update-script { extraArgs = [ "--version=branch" ]; };
</syntaxhighlight>

=== nixpkgs-update ===
[https://github.com/nix-community/nixpkgs-update nixpkgs-update] is used by [[r-ryantm]] for automated updates, if the package does not specify an <code>updateScript</code>. For more info, see the [https://nix-community.github.io/nixpkgs-update/ official documentation].

If you're wondering why your package isn't receiving automated updates, it can be useful to check the [https://r.ryantm.com/log/ r-ryantm logs].

=== Git Updater ===

Updates to the latest git tag. This updater only regenerates the source hash and is therefore unsuitable for package definitions with more than one FOD hash (e.g. Rust's <code>cargoHash</code>).

<syntaxhighlight lang="nix">
passthru.updateScript = gitUpdater {
  ignoredVersions = ""; # Optional - (grep -E) Filter to ignore versions
  allowedVersions = ""; # Optional - (grep -E) Filter to ignore versions
  rev-prefix = "v";     # Optional - set if tags have a prefix before the version number
  odd-unstable = false; # Optional - Ignore odd numberd versions
  patchlevel-unstable = false; # Optional - Ignore patchlevel versions
  url = null;           #  Optional - Set this to a git url when the src is not a git repo
};
</syntaxhighlight>Source: https://github.com/NixOS/nixpkgs/blob/master/pkgs/common-updater/git-updater.nix

=== Unstable Git Updater ===

Updates to the latest git commit. This updater only regenerates the source hash and is therefore unsuitable for package definitions with more than one FOD hash (e.g. Rust's <code>cargoHash</code>).

<syntaxhighlight lang="nix">
passthru.updateScript = unstableGitUpdater {
  branch = null; # Optional - Which branch should be updated from
  url = null; # Optional - The git url, if empty it will be set to src.gitRepoUrl
  tagPrefix = "v"; # Optional - strip this prefix from a tag name
  hardcodeZeroVersion = false; # Optional - Use a made-up version "0" instead of latest tag. Use when the project's tagging system is incompatible with what we expect from versions
  tagFormat = "*"; # Optional - A `git describe --tags --match '<format>'` pattern that tags must match to be considered
  tagConverter = null; # Optional - command to convert more complex tag formats. It receives the git tag via stdin and should convert it into x.y.z format to stdout. Example: https://github.com/NixOS/nixpkgs/blob/c0d71ad01729bf1acca3200ab418301ff2f9ee81/pkgs/by-name/ch/chirp/package.nix#L69-L73
  shallowClone = true; # Optional - do not perform a complete clone
};
</syntaxhighlight>Source: https://github.com/NixOS/nixpkgs/blob/master/pkgs/common-updater/unstable-updater.nix

=== Disabling nixpkgs-update for individual packages ===

Put the following comment somewhere in the package file:

<syntaxhighlight lang="nix">
# nixpkgs-update: no auto update
</syntaxhighlight>

=== Additional Resources ===

* [https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md#automatic-package-updates Contributing to nixpkgs - Automatic Package Updates (github.com/nixos/nixpkgs)]

[[Category:Nixpkgs]]