nix fmt's "formatter" attribute name is unclear so it gets used for non-nix files

[LunNova]

nix fmt is intended for formatting only .nix files, per both the man page and the long discussion when it was merged in #6087

It uses a generic sounding formatter attribute, which seems like a formatter for your flake, not a formatter for your flake's nix files. To learn that it isn't you have to know to check the docs for the nix fmt command or go read the original PR.
Since there's no mechanism to prevent it from formatting all files, there are usages in the wild which format all file types in a project. Example https://github.com/marigold-dev/pollinate/blob/1dcc46fa95b5e063e37cddbf0c5e4caccfffaf66/flake.nix#L30

The documentation should be changed to allow for formatting non-nix files, or the attribute should be renamed to make it much more obvious what the intent was.

See also #6241

[LunNova]

cc @roberth since you suggested an alternative attr already in #6087 (comment)

[roberth]

Seems like users have found a useful command. Can't blame them.
We can generalize the docs, and that'd also be in line with generalizing the feature as an alias for nix dev fmt as linked.

Technically we could make it appear more restrictive by passing a list of .nix filenames as arguments, but Nix has no business being a formatting framework either. This would be like having the worst parts of nix-shell all over again.

[LunNova]

The only concern I have with just updating the documentation is if in the future nix fmt gets a default implementation that specifically formats nix files it might be confusing to have it start formatting non-nix files in some flakes.
It does seem like the simplest change and it lines up with what people are already doing.

[roberth]

if in the future nix fmt gets a default implementation

If this is going to be a goal at any point, we better deprecate nix fmt first and let people use nix dev fmt in the meanwhile, as I expect the community "process" of settling on a format to take more years.

nix dev would be free form, and therefore nix dev fmt doesn't carry such weight.

[infinisil]

Relevant: NixOS/rfcs#166

Require that any default formatting in the Nix CLI must use the official Nix formatter