Add some documentation about the official nix formatter #1129

jfly · 2025-04-13T18:27:30Z

Ping @NixOS/nix-formatting, since I can't see to add the team as a reviewer on this PR.

We now have some decent tooling around this, but it's not very discoverable for people new to nix. We (the formatting team) believe nix.dev is a good place for this documentation to live.

I copied this text (with slight modifications) from nix eval --raw nixpkgs#nixfmt-tree.meta.longDescription.

MattSturgeon

Thanks for tackling this!

source/guides/recipes/autoformatting.md

fricklerhandwerk · 2025-04-13T20:32:37Z

source/guides/recipes/autoformatting.md

+  formatter.''${system} = nixpkgs.legacyPackages.''${system}.nixfmt-tree;
+  ```
+
+- The same can be done more efficiently with the `treefmt` command,


Please show exactly one way of doing things, and since official documentation is committed to stable features (and you already point out that it's more efficient) let's use the one where you add the package to your shell environment.

Please show exactly one way of doing things

I'm not sure I agree we should limit ourselves to only documenting a single approach to things.

nix fmt and nix-shell --run treefmt both have their own pros and cons, I'd expect users would want to be aware of each.

Realty is, we have to balance cognitive load against factual completeness. This place is about managing cognitive load, reference documentation is for completeness. I'd appreciate discussion in reference documentation and issue threads on the costs and benefits of various approaches, but the motto of nix.dev is "getting things done" -- not "agonizing over the options". We're free to agonize in these behind the scenes exchanges, but we must not spill that on beginners.

Tbh I'm not sure if nix fmt has a benefit other than it being a shorter command, but we should recommend direnv anyways, in which case treefmt has the exact same length. I'd be fine with dropping nix fmt, though open about other benefits I'm missing!

I've removed nix fmt. We still do unfortunately document 3 different ways of doing things (nixfmt-tree, treefmt.withConfig, and finally treefmt-nix), but I've tried to convey the reason you would choose the next step.

fricklerhandwerk · 2025-04-13T20:34:25Z

source/guides/recipes/autoformatting.md

+}
+```
+
+Alternatively you can switch to the more fully-featured [treefmt-nix](https://github.com/numtide/treefmt-nix).


Rather than propose ever more alternative ways of doing things, I'd appreciate (and review) a guide to set up a pre-commit hook with treefmt-nix.

While they both relate to formatting, and both produce a configured instance of treefmt, pkgs.nixfmt-tree, pkgs.treefmt.withConfig, and treefmt-nix all exist for different reasons and suit different use cases.

Users who just want to configure formatting nix files in their project shouldn't need to download or configure treefmt-nix; there's a solution built into nixpkgs.

Users who want a more complex formatting setup, where they end up configuring several treefmt options, may benefit from using either treefmt-nix or pkgs.treefmt.withConfig.

Right, and then we'd need to ask what's the purpose of any given article, and whether this information may be better placed elsewhere, such as is Nixpkgs contributor docs.

This sort of problem appears all of the time here, and sometimes one first needs to write an entirely different guide to to write the guide one originally wanted to write. Otherwise it becomes just as unfocused and confusing as we still have an unfortunate reputation for.

I've taken another stab at the docs. It's hopefully less of a choose your own adventure, and more of a journey along increasingly complex, but more powerful options, and you can stop anywhere along that journey if you want.

a guide to set up a pre-commit hook with treefmt-nix.

I opted to leave this out, for a couple of reasons:

It would assume you're working in a git repo.

It solves the problem at the wrong layer. IMO the right thing to do is to get people configuring their editors to autoformat for them (which conveniently would not care if you're in a git repo or not).

infinisil · 2025-04-15T19:28:28Z

From the formatting team meeting today:

Discussed changes to make, there are legitimate reasons for keeping documentation of multiple options, but we can remove some of the options, in particular:
- nix fmt -> Use a shell with treefmt instead
- nixfmt-tree.override -> Use treefmt.withConfig instead
- treefmt --ci -> Use treefmt-nix instead
In general briefly mention when one would want to use the next step
@jfly will also check about the possibility of (moving treefmt-nix into Nixpkgs](https://discourse.nixos.org/t/formatting-team-meeting-2025-03-18/61868/2) (potentially combining it with treefmt.withConfig), which would remove one more way of doing things
- But this might hurt the development speed of treefmt-nix considerably

nixos-discourse · 2025-04-15T19:29:51Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/formatting-team-meeting-2025-04-15/63097/1

jfly

I've updated this PR with a second, more streamlined version of the docs.

source/guides/recipes/autoformatting.md

jfly · 2025-04-25T23:53:13Z

source/guides/recipes/autoformatting.md

+  formatter.''${system} = nixpkgs.legacyPackages.''${system}.nixfmt-tree;
+  ```
+
+- The same can be done more efficiently with the `treefmt` command,


I've removed nix fmt. We still do unfortunately document 3 different ways of doing things (nixfmt-tree, treefmt.withConfig, and finally treefmt-nix), but I've tried to convey the reason you would choose the next step.

source/guides/recipes/autoformatting.md

jfly · 2025-04-25T23:57:24Z

source/guides/recipes/autoformatting.md

+}
+```
+
+Alternatively you can switch to the more fully-featured [treefmt-nix](https://github.com/numtide/treefmt-nix).


I've taken another stab at the docs. It's hopefully less of a choose your own adventure, and more of a journey along increasingly complex, but more powerful options, and you can stop anywhere along that journey if you want.

a guide to set up a pre-commit hook with treefmt-nix.

I opted to leave this out, for a couple of reasons:

It would assume you're working in a git repo.

It solves the problem at the wrong layer. IMO the right thing to do is to get people configuring their editors to autoformat for them (which conveniently would not care if you're in a git repo or not).

MattSturgeon

LGTM overall. Minor comments, thoughts & suggestions:

source/guides/recipes/autoformatting.md

MattSturgeon · 2025-04-26T21:48:07Z

source/guides/recipes/autoformatting.md

+
+This can get a little tedious.
+[treefmt-nix](https://github.com/numtide/treefmt-nix) has a big library of
+preconfigured formatters, and provides a `check` derivation you can use in CI.


If we're mentioning the check derivation, should we include a (simple) example of using it?

If flakes are acceptable in nix.dev guides, maybe adding the drv to a flake's checks output would be a suitable example?

Such an example may be a good opportunity to "sneak in" defining formatter and devshell outputs, although not if that ends up making the example less simple.

I agree it would be nice to include a simple example of using the check derivation, but that requires either using npins or flakes to pull in treefmt-nix. It gets messy kind of fast, and I'm lightly leaning towards "just send them to treefmt-nix to figure this out", as I've done here.

I'm very ambivalent on this, though. I'm going to leave this unresolved, perhaps someone with strong opinions will show up.

source/guides/recipes/autoformatting.md

We now have some decent tooling around this, but it's not very discoverable for people new to nix. We (the formatting team) believe `nix.dev` is a good place for this documentation to live.

MattSturgeon

Looks good from my perspective 😁

Thanks @jfly

jfly requested a review from a team as a code owner April 13, 2025 18:27

jfly mentioned this pull request Apr 13, 2025

Update nix fmt man page with official formatter example NixOS/nix#13014

Merged

MattSturgeon reviewed Apr 13, 2025

View reviewed changes

source/guides/recipes/autoformatting.md Outdated Show resolved Hide resolved

source/guides/recipes/autoformatting.md Outdated Show resolved Hide resolved

source/guides/recipes/autoformatting.md Outdated Show resolved Hide resolved

MattSturgeon reviewed Apr 13, 2025

View reviewed changes

source/guides/recipes/autoformatting.md Show resolved Hide resolved

fricklerhandwerk reviewed Apr 13, 2025

View reviewed changes

infinisil added this to Nix formatting Apr 15, 2025

github-project-automation bot moved this to Todo in Nix formatting Apr 15, 2025

jfly mentioned this pull request Apr 15, 2025

Improving flake formatting experience NixOS/nixfmt#273

Closed

jfly force-pushed the nixfmt branch from e754774 to e412c84 Compare April 26, 2025 00:09

jfly commented Apr 26, 2025

View reviewed changes

jfly requested review from MattSturgeon, fricklerhandwerk and infinisil April 26, 2025 00:11

MattSturgeon reviewed Apr 26, 2025

View reviewed changes

Add some documentation about the official nix formatter

bd295cb

We now have some decent tooling around this, but it's not very discoverable for people new to nix. We (the formatting team) believe `nix.dev` is a good place for this documentation to live.

jfly force-pushed the nixfmt branch from e412c84 to bd295cb Compare April 27, 2025 02:55

MattSturgeon approved these changes Apr 27, 2025

View reviewed changes

Mic92 merged commit c76bc9b into NixOS:master Apr 29, 2025
4 of 5 checks passed

github-project-automation bot moved this from Todo to Done in Nix formatting Apr 29, 2025

fricklerhandwerk mentioned this pull request Apr 29, 2025

move nixfmt instructions to FAQ #1131

Merged

mergify bot mentioned this pull request May 1, 2025

Update nix fmt man page with official formatter example (backport #13014) NixOS/nix#13124

Merged

Uh oh!

Add some documentation about the official nix formatter #1129

Add some documentation about the official nix formatter #1129

Uh oh!

Conversation

jfly commented Apr 13, 2025

Uh oh!

MattSturgeon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fricklerhandwerk Apr 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

infinisil commented Apr 15, 2025

Uh oh!

nixos-discourse commented Apr 15, 2025

Uh oh!

jfly left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MattSturgeon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MattSturgeon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

fricklerhandwerk Apr 13, 2025 •

edited

Loading