Skip to content

Testing External Flakes Locally

This guide explains how to temporarily modify your nixfiles configuration to test local changes to an external Flake (such as antigravity-nix) before submitting a pull request or upstreaming the fix.

The Challenge

In a Flake-based system like nixfiles, inputs are pinned using flake.lock. Furthermore, in this repository, flake.nix is auto-generated by the flake-file tool and shouldn't be edited directly.

To test local changes to an external flake, you must update the input declaration, regenerate the main flake.nix, update the lock file, and then rebuild.

Step-by-Step Guide

1. Declare the Local Path

Find the module where the external flake input is declared (e.g., modules/tools/antigravity.nix) and change its URL to point to your local repository clone:

flake-file.inputs.antigravity.url = "path:/home/username/git/github.com/jacopone/antigravity-nix";

Tip

Use path: instead of git+file::

  • path:/path/to/repo fetches the directory directly, including any uncommitted (dirty) changes.
  • git+file:///path/to/repo only builds files that have been committed to Git. Using path: is much faster and cleaner for iterative local testing.

Warning

Nix's path: fetcher does not support ?dir=... query parameters!

  • If the input URL uses a subdirectory selector (e.g. ?dir=dotfiles/home-manager), changing it to path: will drop the dir parameter and lock the root directory instead.
  • Because the root of the input changes, any paths importing from that input (e.g., "${inputs.vorburger-dotfiles}/home.nix") will break unless they are adjusted to import via the relative subdirectory (e.g., "${inputs.vorburger-dotfiles}/dotfiles/home-manager/home.nix").
  • Additionally, if files in the subdirectory access parent files (e.g. ../../git-clone.sh), it will throw a sandbox/pure mode evaluation error because the parent directories are not part of the copied path store.

Tip

Recommended Alternative (Push Upstream): For flakes that use subdirectories, using local path overrides can be complex due to the path structure changes described above. It is easier and highly recommended to:

  1. Push your changes to the upstream Git repository (or a temporary branch).
  2. Run nix flake update <input-name> to pull and test the changes. This avoids having to modify import paths in your Nix configuration.

2. Regenerate flake.nix

Since flake.nix is managed by flake-file, you must regenerate it by running this command in your nixfiles root directory:

nix run .#write-flake

3. Update the Flake Lockfile

Even though flake.nix now references the local path, Nix still uses the locked revision in flake.lock. Force Nix to lock the new local path by running:

nix flake update <input-name>

For example, to update the antigravity input:

nix flake update antigravity

4. Apply and Rebuild

Now you can perform your normal NixOS rebuild. Nix will build the package using your local modified repository code:

sudo nixos-rebuild switch --flake .

Reverting Back to Upstream

Once you have verified your changes and are ready to revert to the upstream flake:

  1. Restore the URL in the module file (e.g., reset modules/tools/antigravity.nix back to "github:jacopone/antigravity-nix").
  2. Regenerate the flake:
nix run .#write-flake
  1. Update the lockfile to pin back to the remote repository:
nix flake update antigravity
  1. Clean up any build results if needed.