mirror of
https://github.com/NixOS/nix
synced 2024-09-19 10:50:24 -04:00
Define Formatter Command Line Interface
This commit is contained in:
parent
790dd2555b
commit
06676b7cc5
|
@ -2,6 +2,19 @@ R""(
|
|||
|
||||
# Examples
|
||||
|
||||
- Format the current flake: `$ nix fmt`
|
||||
|
||||
This is an alias to `$ nix fmt .`
|
||||
|
||||
- Format specific folders and/or files: `$ nix fmt ./folder ./file.nix`
|
||||
|
||||
- Check formatting but not edit any files: `$ nix fmt -- --check /file.nix`
|
||||
|
||||
- Read code from standard input and print the formatted result to standard
|
||||
output: `$ nix fmt -- -- - <input.nix >formatted.nix`
|
||||
|
||||
A formatter must be configured in the flake output to work.
|
||||
|
||||
With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):
|
||||
|
||||
```nix
|
||||
|
@ -13,10 +26,6 @@ With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):
|
|||
}
|
||||
```
|
||||
|
||||
- Format the current flake: `$ nix fmt`
|
||||
|
||||
- Format a specific folder or file: `$ nix fmt ./folder ./file.nix`
|
||||
|
||||
With [nixfmt](https://github.com/serokell/nixfmt):
|
||||
|
||||
```nix
|
||||
|
@ -28,7 +37,8 @@ With [nixfmt](https://github.com/serokell/nixfmt):
|
|||
}
|
||||
```
|
||||
|
||||
- Format specific files: `$ nix fmt ./file1.nix ./file2.nix`
|
||||
Note: the latest release of `nixfmt` doesn't support formatting folders (using
|
||||
`nix fmt`), but it will be fixed it in the next release.
|
||||
|
||||
With [Alejandra](https://github.com/kamadorueda/alejandra):
|
||||
|
||||
|
@ -41,13 +51,50 @@ With [Alejandra](https://github.com/kamadorueda/alejandra):
|
|||
}
|
||||
```
|
||||
|
||||
- Format the current flake: `$ nix fmt`
|
||||
|
||||
- Format a specific folder or file: `$ nix fmt ./folder ./file.nix`
|
||||
|
||||
# Description
|
||||
|
||||
`nix fmt` will rewrite all Nix files (\*.nix) to a canonical format
|
||||
`nix fmt` will rewrite Nix files (\*.nix) to a canonical format
|
||||
using the formatter specified in your flake.
|
||||
|
||||
If `--` occurs in arguments, all arguments after the first `--` are passed to
|
||||
the formatter literally. You can pass extra arguments to the formatter instead
|
||||
of Nix using `--`.
|
||||
|
||||
# Formatter Command Line Interface
|
||||
|
||||
The key words "MUST", "SHOULD" and "MAY" here are to be interpreted as
|
||||
described in RFC 2119.
|
||||
|
||||
To make formatter invocations portable, we define Formatter Command Line
|
||||
Interface. The main binary of the formatter package specified in the flake MUST
|
||||
follow the command line interface below.
|
||||
|
||||
1. It MUST accept one or more input paths of files. If a folder is given, it
|
||||
SHOULD add all \*.nix files recursively under it as inputs. It MAY support
|
||||
custom ignore rules besides the trivial recursion.
|
||||
|
||||
2. It MUST support separator argument `--`. If `--` is given, all arguments
|
||||
after the first `--` MUST be treated as input paths as-is but not flags.
|
||||
|
||||
3. If only one input path argument `-` is given and it is after `--`, the
|
||||
formatter MUST read the Nix file content to be formatted from the standard
|
||||
input, and write ONLY the formatted result content to the standard output.
|
||||
If the operation succeeds, no matter whether the result is different from
|
||||
the input, it MUST returns a zero exit code; otherwise, it MUST returns an
|
||||
non-zero exit code, and in this case, the content of the standard output is
|
||||
implementation defined.
|
||||
|
||||
4. Except the case of reading from standard input, the formatter MUST format
|
||||
all input files in-place by default, and return a zero exit code for
|
||||
success. If any error occurs, it MUST return an non-zero exit code.
|
||||
|
||||
5. If flag `-c` or `--check` is given, it MUST only check all inputs and not
|
||||
write back to any input paths. In the case of reading from standard input,
|
||||
it SHOULD print nothing to the standard output). It MUST returns a zero
|
||||
exit code when all inputs need no modification after formatting; otherwise,
|
||||
it MUST return an non-zero exit code.
|
||||
|
||||
6. Except for flags defined above, extra flags MAY be supported, the meaning
|
||||
of which are implementation defined.
|
||||
|
||||
)""
|
||||
|
|
Loading…
Reference in a new issue