Checkers

A Checker only selects a Pin's Version. Fetchers obtain source code. Except for cmd, the constructors below accept attribute sets, not the string shorthand supported by pin.github.

GitHub — pin.checker.github

Use target = "owner/repo" or owner and repo, without mixing them. Reads GitHub's /releases/latest and uses the original tag_name string. This differs from sorting Git tags.

{ pin }: {
  patchelf = pin.mk {
    checker = pin.checker.github { target = "NixOS/patchelf"; };
    fetcher = pin.fetcher.github { target = "NixOS/patchelf"; };
  };
}

Git — pin.checker.git

Use target or url, without mixing them. Supported modes:

include and exclude are Rust regular expressions filtering tag names. sort defaults to semver; lexicographic is also available. Do not use lexical ordering in place of semantic version comparison for versions such as 1.9 and 1.10.

{ pin }: {
  patchelf = pin.mk {
    checker = pin.checker.git {
      target = "https://github.com/NixOS/patchelf.git";
      mode = "tag";
      include = "^[0-9]+[.][0-9]+[.][0-9]+$";
      sort = "semver";
    };
    fetcher = pin.fetcher.git { target = "https://github.com/NixOS/patchelf.git"; };
  };
}

branch is only valid in branch mode, and ref only in ref mode. No matching tags or an unresolvable ref causes the Pin to fail.

crates.io — pin.checker.crate

Use target or name for the crate name. Reads newest_version from crates.io, falling back to max_version if absent. It does not filter exclusively for stable releases.

{ pin }: {
  ripgrep = pin.mk {
    checker = pin.checker.crate { target = "ripgrep"; };
    fetcher = pin.fetcher.url {
      url = version: "https://crates.io/api/v1/crates/ripgrep/${version}/download";
    };
  };
}

PyPI — pin.checker.pypi

Use target or name for the PyPI project name. Reads info.version from the project's JSON response. Choose the download independently with a version mapping:

{ pin }: {
  requests = pin.mk {
    checker = pin.checker.pypi { target = "requests"; };
    fetcher = pin.fetcher.zip {
      url = version: "https://files.pythonhosted.org/packages/source/r/requests/requests-${version}.tar.gz";
    };
  };
}

npm — pin.checker.npm

Use target or name; scoped package names are supported. distTag defaults to latest and selects an entry from the registry's dist-tags. Set another tag such as next as needed. The Checker does not scan and sort all published versions.

{ pin }: {
  vite = pin.mk {
    checker = pin.checker.npm { target = "vite"; distTag = "latest"; };
    fetcher = pin.fetcher.url {
      url = version: "https://registry.npmjs.org/vite/-/vite-${version}.tgz";
    };
  };
}

URL — pin.checker.url

Use target or url, with a required regex. Fetches the URL and matches its text. Uses the first capture group if present, otherwise the entire match. The result must not be empty.

{ pin }: {
  patchelf = pin.mk {
    checker = pin.checker.url {
      target = "https://api.github.com/repos/NixOS/patchelf/releases/latest";
      regex = ''"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)"'';
    };
    fetcher = pin.fetcher.github { target = "NixOS/patchelf"; };
  };
}

Command — pin.checker.cmd

Accepts a command string. The command must exit successfully and print a nonempty Version to stdout after trimming leading and trailing whitespace. Useful for fixed versions or upstream sources not covered by built-in Checkers.

{ pin }: {
  patchelf = pin.mk {
    checker = pin.checker.cmd "printf '0.18.0'";
    fetcher = pin.fetcher.github { target = "NixOS/patchelf"; };
  };
}

Command configuration is trusted executable input, not a sandbox. Print only the version to stdout and send diagnostics to stderr.