Nix formatting team: Full Nixpkgs reformat

Announcements
1

After the previous partial Nixpkgs reformat, the Nix formatting team is now ready for follow-up: To fully standardise formatting in Nixpkgs! :rocket:

Highlights:

  • All files will be formatted using a pinned version the official Nix formatter, aka pkgs.nixpkgs-rfc-format. CI will enforce this going forward, ensuring that all files continue to be formatted consistently.
  • Inside Nixpkgsā€™ nix-shell/nix develop, you will be able to run treefmt to get the right formatting on all files. You can also use this with a pre-commit/push Git hook or your editorā€™s auto-format-on-save feature!

We are coordinating asynchronously on Matrix and will hold a final review and merge party :tada: at 2025-04-01T18:00:00Z in this Jitsi, feel free to join both!

If you have questions, concerns or problems, let us know here, in the Matrix room, in the nixfmt issue tracker or ping @NixOS/nix-formatting in Nixpkgs.

Note that the formatter is still being worked on, so we appreciate any support and could use some more Haskellers!

Merge conflicts

This PR will lead to merge conflicts for a number of PRs. Hereā€™s two ways which will usually work to resolve formatting conflicts automatically.

Method 1: Auto-rebase script

You can use the new auto-rebase script. This takes some time to run (especially if you have a lot of commits in your PR), but should take care of rebasing the current branch while automatically resolving any merge conflicts caused by the full Nixpkgs reformat:

git fetch upstream
maintainers/scripts/auto-rebase/run.sh upstream/master

Method 2: git mergetool

:warning: Warning

This method has a bug (see Mergetool fixes by infinisil Ā· Pull Request #291 Ā· NixOS/nixfmt Ā· GitHub for the fix, though it will take some time for it to be propagated) that can affect merge correctness. As such, it is not recommended right now. If you use it regardless, make sure to double-check the result for correctness.

Instructions

Nixfmt newly provides a mode usable by git mergetool that is faster and more general than the above, and allows resolving almost all formatting-related conflicts automatically.
Thereā€™s more extensive docs, but the most basic way to use it is as follows:

# Run these once:
git config mergetool.nixfmt.cmd 'nixfmt --mergetool "$BASE" "$LOCAL" "$REMOTE" "$MERGED"'
git config mergetool.nixfmt.trustExitCode true

# Run these to rebase:
git rebase master
git mergetool -t nixfmt .

In other news: pkgs.nixfmt-tree

Not directly related to the above, we want to also highlight that thereā€™s a new pkgs.nixfmt-tree package, which is a convenient wrapper around nixfmt-rfc-style and treefmt, making it straightforward to integrate into nix fmt, nix-shell or nix develop for your personal projects.

See the package description for how to use it!

Personal refocusing

Speaking as just @infinisil now, this will be one of my last efforts for Nix formatting, as I plan to step down from the team soon in order to focus on my new responsibilities as a NixOS Foundation member. It has been a joy to work with the other members, and Iā€™m looking forward to seeing the gears turning without my involvement!

To close this chapter, I feel the need to give another huge shout-out to Antithesis and Tweag. Theyā€™ve enabled me to spend time on this for over three years now, thank you!

84 Likes
2

Weā€™re on schedule to merge this tomorrow! I messed up the times a little bit all over the place, so just to clarify: We meet 2025-04-01T18:00:00Z in this Jitsi for the merge party :tada:

You can also see this in the official calendar and the community calendar.

12 Likes
3

Iā€™m happy to say that everything went according to plan, Nixpkgs is fully formatted! :tada:

If you see people struggling with merge conflicts caused by the reformat, please link them to this post or How to resolve formatting-related conflicts Ā· Issue #395247 Ā· NixOS/nixpkgs Ā· GitHub

And just to confirm because of the unlucky date: No this is not a joke! :smile:

36 Likes
4

Thanks for the detailed post, and the wonderful work on this! Much appreciated.

Are there any detailed, recommended instructions on how to set this up? treefmtā€™s README mentions nixpkgs-fmt which is considered deprecated of course in favor of nixfmt-rfc-style.

Maybe we should suggest people to use https://pre-commit.com/ somehow? Iā€™m not very experienced with Git Hooks and with https://pre-commit.com/ in particular, but I think itā€™d be helpful for everyone to get some guidance maybe?

5

Check out the nixfmt Readme for a bunch of instructions :smiley:

3 Likes
7

Great documentation by the nixfmt Readme.

One thing this is especially nice when setting this up in projects is to use flake-parts which has integration with the mentioned tools treefmt-nix and git-hooks.nix. Personally I wrapped up these tools that I use in every project inside terlar/dev-flake which can be used by flake-parts partitions functionality to get it outside of the main flake.

Some editor config that was missing:

VSCode
Using the plugin Custom Local Formatters.

Configured like:
.vscode/extensions.json:

{
    "recommendations": [
        "jkillian.custom-local-formatters"
    ]
}

.vscode/settings.json:

{
  "customLocalFormatters.formatters": [
    {
      "command": "treefmt --stdin ${file}",
      "languages": ["*"]
    }
  ],
  "editor.defaultFormatter": "jkillian.custom-local-formatters",
  "editor.formatOnSave": true
}

Emacs
Using the package apheleia.

.dir-locals.el:

((nil . ((apheleia-formatter . treefmt))))
8

I am out of the loop, why couldnā€™t this be done a few days before stable (25.05) comes out in Beta?

9

Thereā€™s no beta, and itā€™s already done, so why hand-wring?
Besides, itā€™s actually itā€™s a good thing it was done a while before the release, to avoid more headaches during ZHF or otherwise disrupting the release process overall.

3 Likes
10

I think it might have a negative impact on backportability.

11

To some degree, even individual expression reformats would impact backports, e.g. in cases where some breaking updates werenā€™t backported but a future fix could be backported, the fix diff wouldnā€™t apply cleanly. In those cases manual resolution would still be necessary. IMO this just rips off the bandaid, and based on NixOS 25.05 ā€“ Release schedule Ā· Issue #390768 Ā· NixOS/nixpkgs Ā· GitHub the last day to do breaking changes (in the general case) would beā€¦today. They just did it a week prior.

1 Like
12

For backporting, itā€™s actually better to do it just before a release (so before ZHF). If we did it just after release, 25.05 and 24.11 will not be formatted the same way. Weā€™ll have less conflicts the way it was done.

2 Likes
13

I suppose youā€™ve missed that 24.11 also got the treewite reformat?

2 Likes