ndf

A command-line program that makes it easier to compare how a set of Nix derivations changed between commits.

The motivating use case is having a Git repository with many NixOS configurations, with parts of the configuration factored out into common modules. ndf allows you to check how a given change to Nix code affected each configuration at the derivation level (see Worry-free NixOS refactors). By default ndf shows only whether a derivation changed at all, but it can also show how the derivations differ by using nix-diff.

Installation

Use the Nix flake in this repository to install the package into a profile, add it to a NixOS or Home Manager configuration, or run it directly from the command line:

nix run github:bartoszwjn/ndf

cargo install --git should work as well.

The program expects the following commands to be available in PATH at runtime:

• nix, as well as nix-instantiate, nix-build, etc.
• git, if operating on a pure Git repository.
• jj, if operating on a colocated Jujutsu/Git repository.
• The external tool used to compare derivations, if specified using the --tool option.

Usage

Run ndf without any arguments to compare all packages outputs of the Nix flake in the current directory between the HEAD commit and the current working tree.

Commonly used flags and options:

• Use --revision/-r, --from/-f and --to/-t to select commits that are compared to each other.
• Use --flake to choose the flake to compare (must be a Git worktree on the local filesystem).
• Use --file to compare output attributes of a Nix expression stored in a file.
• Use positional arguments to manually specify which output attributes to compare.
• --nixos makes it easier to compare NixOS configurations, by automatically appending config.system.build.toplevel to each compared attribute path. Additionally, attribute paths that select flake outputs are interpreted as relative to the nixosConfigurations prefix (instead of the default trio of packages.<system>, legacyPackages.<system> and empty prefix).
• With --glob/-g, positional arguments are treated as glob patterns that are matched against the existing output attributes of the flake or file being compared.

See the --help output for details about all command line flags and options.

Jujutsu

ndf has special support for Jujutsu workspaces. When ndf detects that the given repository is a Jujutsu workspace it switches to "Jujutsu mode", in which revisions are specified using Jujutsu's revset language and jj log is used to display them. The Jujutsu workspace must be a colocated Jujutsu/Git workspace, since Nix does not integrate with Jujutsu directly.

The automatic mode selection can be overridden using the --git and --jj flags.