nixpkgs-review

Build changed packages in the specified pull request

$ nixpkgs-review pr [pr_number|pr_url]

$ nixpkgs-review pr --post-result [pr_number|pr_url]

$ nixpkgs-review pr --print-result [pr_number|pr_url]

$ nixpkgs-review rev [HEAD]

$ nixpkgs-review wip

$ nixpkgs-review wip --staged

nixpkgs-review <command> [options] [arguments]

Common commands include:
nixpkgs-review pr <PR_NUMBER_OR_URL> [options]
nixpkgs-review head [options]
nixpkgs-review wip [options]
nixpkgs-review build-products [options] <paths...>

pr
    Reviews a specific GitHub pull request by its number or URL.

head
    Reviews changes between the current HEAD and the upstream nixpkgs branch.

wip
    Reviews changes in the current working tree, useful for local development.

build-products
    Allows building specific derivations or paths within the review context.

-j, --cores
    Specifies the maximum number of CPU cores to use for parallel builds.

--dry-run
    Shows which derivations would be built without actually performing the builds.

--build-args
    Passes additional arguments directly to the underlying nix-build command.

--package
    Limits the review to a specific package, improving efficiency for targeted changes (used with 'pr' command).

--attr
    Limits the review to a specific attribute path, e.g., 'pkgs.hello' (used with 'pr' command).

--keep-going
    Continues building other derivations even if some derivations fail, useful for diagnosing multiple issues.

--test
    Runs tests defined for the derivations in the review.

--system
    Specifies the target system for builds, e.g., 'x86_64-linux' or 'aarch64-darwin'.

--offload
    Offloads builds to a remote Nix builder, potentially speeding up reviews or using specific hardware.

nixpkgs-review is a crucial tool for contributors to the Nixpkgs repository. It automates the process of testing changes introduced by a GitHub pull request locally on a user's machine. By fetching the PR's commits, merging them with the upstream nixpkgs branch, and then attempting to build or test the affected derivations, it helps identify regressions, build failures, or other issues before changes are merged.

This allows reviewers to quickly verify the correctness of proposed updates without manually setting up complex build environments. It can operate on an entire PR, specific packages, or even just local changes, providing flexibility for different review scenarios. It primarily uses nix-build and nix-instantiate internally.

nixpkgs-review can be resource-intensive, requiring significant disk space and CPU time, especially for large pull requests or when rebuilding many dependencies. Its performance is highly dependent on the user's system specifications and the extent of changes being reviewed. It assumes a local clone of the nixpkgs repository is available and updated. While effective for build and basic test verification, it doesn't replace manual testing for complex runtime behaviors not covered by automated tests.

Users typically start by navigating to their local nixpkgs clone, then run nixpkgs-review pr <PR_NUMBER>. The tool fetches the PR, merges it with the current branch, and attempts to build or test the affected derivations. Reviewers then check the output for build failures or test regressions before providing feedback on the GitHub pull request.

One of nixpkgs-review's strengths is its ability to leverage Nix's content-addressable caching. If derivations or their dependencies have been built before (either locally or via a binary cache), they won't be rebuilt, significantly speeding up subsequent reviews and reducing resource consumption.

nixpkgs-review originated as a community-driven effort within the Nix ecosystem to standardize and streamline the process of reviewing pull requests for the massive nixpkgs repository. Initially, various ad-hoc scripts were used for local testing. As the size and complexity of nixpkgs grew, a more robust and unified tool became essential to enable efficient collaboration and maintain the repository's quality. Its development reflects the Nix community's commitment to robust CI/CD practices, allowing for a high volume of contributions while ensuring stability.

nix-build(1), nix-instantiate(1), nix(1), nix-shell(1), git(1)