nixfmt(1)

📦
version 0.5.3 · 2 versions
, in nixpkgs unstable

✨ NAME ✨

okay so bestie, welcome to nixfmt(1) — the nixfmt page from the General Commands Manual 💖

nixfmt — format Nix source code (Rust implementation). That's the whole NAME section, and yes, it's giving exactly what it says on the tin ✨

🦋 SYNOPSIS 🦋

nixfmt [OPTIONS] [FILES...|-]

🌸 DESCRIPTION 🌸

nixfmt reformats Nix expressions to a canonical style. It's a Rust reimplementation of the reference Haskell nixfmt(1) and aims for byte-for-byte output parity on supported inputs — no cap, that's the goal 💅

When invoked with one or more FILES, each file is reformatted in place. If a FILE is a directory, nixfmt recurses into it and formats every .nix file it finds. With no FILES, or with the single argument -, nixfmt reads the source from standard input and writes the formatted result to standard output 🎀

🚨 lowkey important: bare invocation (no FILES, no -) is deprecated. Use - to make the intent explicit, bestie.

💅 OPTIONS 💅

  • -w, --width=INT — maximum line width in characters. Default: 100.
  • --indent=INT — number of spaces to use for one indentation level. Default: 2.
  • -c, --check — do not modify any files; instead exit with status 1 if any input is not already formatted. In stdin mode no output is produced on standard output.
  • -m, --mergetool — run as a git mergetool(1). Expects exactly four file arguments BASE LOCAL REMOTE MERGED. Each of BASE, LOCAL and REMOTE is pre-formatted, git merge-file(1) is invoked on them, the result is formatted, and finally moved onto MERGED. The exit status of git merge-file is forwarded so the conflict count is preserved. Skipped with a warning when MERGED is not a .nix file. 🫶
  • -q, --quiet — suppress non-fatal diagnostics on standard error.
  • -s, --strict — accepted for compatibility with the reference nixfmt; currently a no-op. It's literally just there to be polite 💀
  • -v, --verify — after formatting, reparse and reformat the output to ensure idempotence. Fails with a non-zero exit status if the second pass differs from the first.
  • -a, --ast — print the internal AST to standard error (debugging aid). Exits with status 1.
  • --ir — print the internal intermediate representation to standard error (debugging aid). Exits with status 1.
  • -f, --filename=NAME — filename to use in diagnostic messages when input is read from standard input. Useful for editor integrations.
  • --message-format=FMT — how diagnostics are rendered on standard error. FMT is one of:
    • human (default) — rustc-style snippets with carets and fix-it hints.
    • json — one JSON object per line, shaped like an LSP Diagnostic: file, severity, code, message, 0-based range, byteRange, optional help and relatedInformation, plus the human rendered text. All standard-error output (including --check results and I/O errors) is JSON in this mode.
  • -?, --help — display a short help message and exit.
  • -V, --version — print the program version and exit.
  • --numeric-version — print just the numeric version (no program name) and exit.
  • -- — end of options. All remaining arguments are treated as file paths.

🎀 EXIT STATUS 🎀

  • 0 — all inputs were processed (and, in --check mode, all were already formatted).
  • 1 — a parse error, an unformatted input in --check mode, an I/O error, or an invalid invocation.

In --mergetool mode the exit status is the exit code of git merge-file, which is the number of remaining merge conflicts (or 0 if none). Periodt 🌈

🔥 EXAMPLES 🔥

Format every .nix file under the current directory in place:

nixfmt .

Check formatting in CI without modifying files:

nixfmt --check .

Format a snippet from a pipeline:

echo '{a=1;}' | nixfmt -

Consume diagnostics from a wrapper or LSP:

nixfmt --message-format=json --check . 2>&1 >/dev/null | jq .

Use as a git mergetool:

git config mergetool.nixfmt.cmd 'nixfmt --mergetool "$BASE" "$LOCAL" "$REMOTE" "$MERGED"'

🌈 SEE ALSO 🌈

The reference Haskell implementation lives at https://github.com/NixOS/nixfmt. The Rust port lives at https://github.com/Mic92/nixfmt-rs. 🦋

made with 💖 by nixfmt-rs, dated 1980-01-01 — and yes, you just read nixfmt(1). slay 🫶✨

📦 where this page comes from