Command line¶
rainbow-fmt format [-u] PATH... rewrite files in place
rainbow-fmt check [-u] PATH... report files that would change
rainbow-fmt diff [-u] PATH... print the changes as unified diffs
rainbow-fmt format - --stdin-filepath PATH read stdin, write stdout
rainbow-fmt options FILE show the options that apply to FILE
rainbow-fmt init [DIR] write a project's first configuration
format, check and diff accept --set KEY=VALUE (repeatable), which
sets an option for every file, above configuration files
(configuration.md), --no-verify
(Verification), --no-cache (Cache) and
-j N / --jobs N (Parallel jobs).
Paths¶
- A file is formatted if its language is known (today: JSON and JSONC,
*.jsonand*.jsonc; CSS,*.css—css.md; Python,*.py—python.md; JavaScript,*.js,*.mjs,*.cjs,*.jsx—javascript.md; TypeScript,*.ts,*.mts,*.cts,*.tsx—typescript.md). - A directory is searched recursively for files of known languages.
Hidden directories (names starting with
.),node_modulesand the[files] excludepatterns of the nearest configuration are skipped; so are files of unknown languages, silently, and TypeScript declaration files (*.d.ts,*.d.mts,*.d.cts), which are formatted only when named. - A file named more than once (directly or through a directory) is formatted once.
-reads standard input and, forformat, writes the result to standard output.--stdin-filepathis required: its suffix selects the language and its directory the configuration.-cannot be combined with other paths.
Each file is formatted with its own nearest configuration
(configuration.md).
Output¶
| Command | Standard output |
|---|---|
format |
reformatted PATH for each file it rewrote |
check |
would reformat PATH for each file that would change |
diff |
a unified diff (--- PATH / +++ PATH (formatted)) per file |
Files that are already formatted are not written, and produce no output. Warnings and errors go to standard error.
Line endings in diffs¶
When formatting changes a file's line endings (a CRLF checkout formatted
with core.line_ending = "lf", say), diff does not show every line as
changed. It prints one line for the line endings, then diffs the content
with line endings normalized; a file whose content is already formatted
gets only that line:
$ rainbow-fmt diff README.md
README.md: line endings CRLF -> LF
--- README.md
+++ README.md (formatted)
@@ -1,2 +1,3 @@
## Usage
+
Run it.
After the diffs, a note on standard error names the files and the two ways
to make them agree with core.line_ending: set it to "preserve", or add
* text=auto eol=lf (eol=crlf for CRLF) to .gitattributes so Git
checks files out with the configured line ending.
Unknown file types¶
A file named explicitly whose language is unknown is skipped with a warning:
warning: notes.txt: unknown file type, skipped
Turn the warning off with --ignore-unknown (-u), or in the
configuration that applies to the file:
[files]
ignore_unknown = true
With -, input of an unknown type is copied to standard output unchanged.
Files that cannot be formatted¶
A file with a syntax error, an invalid inline directive
(configuration.md), that is not
valid UTF-8, that cannot be read, or that is nested too deeply (JSON: tens
of thousands of levels) is left unchanged and reported; the other files are
still formatted:
error: bad.json:1:5: syntax error, not formatted
error: app.py:2:1: unknown directive 'rainbow: of', not formatted
error: latin1.json: not valid UTF-8, not formatted
error: locked.json: Permission denied, not formatted
error: deep.json: nested too deeply, not formatted
The same goes for a bug: an unexpected exception while formatting a file is reported as an internal error for that file, and the run continues:
error: app.js: internal error (KeyError: 'x'), not formatted
Please report internal errors. Setting the environment variable
RAINBOW_FMT_TRACEBACK (to any value) prints the traceback after the
message.
The line and column of a syntax error are an estimate: the parser marks the region it could not read, and rainbow-fmt reports the stray text in it, or the point after the text that did parse.
Verification¶
Before a file is written, reported by check or diffed, the formatted
result is verified (rainbow_fmt.verify):
- it parses without syntax errors;
- its syntax tree equals the input's, apart from whitespace and comments: the same nodes in the same shape, and every token with the same text;
- it has the same comments, with the same text, in the same order (a comment may move past a comma);
- formatting it again changes nothing.
A file that fails is left unchanged and reported; the other files are still formatted, and the exit code is 1:
error: data.json:1:7: formatting would change the meaning, not formatted
error: data.json:1:5: formatting would change the comments, not formatted
error: data.json: formatting would produce invalid syntax, not formatted
error: data.json: formatting is not stable (a second pass changes the result), not formatted
The line and column point at the first difference in the input. A failure
means a bug in rainbow-fmt or in a [[rule]] override
(extending.md).
Verification roughly quadruples the time per file (0.35 s without and 1.5 s
with it for a 139 KiB JSON file). Skip it with --no-verify, or in the
configuration that applies to the file:
[files]
verify = false
Cache¶
A run records the files it found formatted (and format the files it
wrote); the next run skips them: they are neither formatted nor verified,
and count as unchanged. A file is skipped only if all of these match the
recorded run: its bytes, its options as resolved for it (so any change to a
configuration file, .editorconfig, override or --set that affects it
counts), its [[rule]] overrides, whether it is verified, and the versions
of rainbow-fmt and its grammars. Files with errors, files that would change
and standard input are not recorded.
The cache is a file in the user cache directory:
| Platform | Directory |
|---|---|
| Linux and others | $XDG_CACHE_HOME/rainbow-fmt (default ~/.cache/rainbow-fmt) |
| macOS | ~/Library/Caches/rainbow-fmt |
| Windows | %LOCALAPPDATA%\rainbow-fmt\Cache |
RAINBOW_FMT_CACHE_DIR overrides the directory (for CI caches). Deleting
the directory is always safe. A cache that cannot be read or written is
ignored, never an error. Turn the cache off with --no-cache or, for the
files a configuration applies to:
[files]
cache = false
Parallel jobs¶
From 8 files on, files are formatted by worker processes, one per CPU by
default. -j N / --jobs N sets the number (1: no workers), as does
[files] jobs in the configuration that applies to the working directory
(the command line wins). Output, its order, the messages, the files
written and the exit code are the same whatever the number of jobs.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Every file is formatted (or was skipped) |
| 1 | check/diff: some file would change; any command: some file could not be formatted or failed verification |
| 2 | Usage or configuration error (missing path, invalid option or [[rule]]); no file was written |
Files are formatted in memory first and written only when no usage or configuration error occurred.
rainbow-fmt options¶
$ rainbow-fmt options --set core.indent_size=2 legacy/new.json
# legacy/new.json (json)
core.max_width = 100 # rainbow.toml:2:13
core.indent_style = "space" # default
core.indent_size = 2 # --set core.indent_size
core.tab_width = 4 # default
core.line_ending = "lf" # default
language.json.trailing_comma = "never" # default
language.json.object_wrap = "fit" # rainbow.toml:6:29 override[0]
language.json.align_values = false # default
rule.pair = "source()" # rainbow.toml:8:1 rule[0]
FILE need not exist; its suffix selects the language and its directory the
configuration. Each line gives the value and its origin: default, a
preset (rainbow:balanced), an .editorconfig position and section
(.editorconfig:4:15 [*.json]), a configuration position (with the
override[N] or rule[N] it belongs to), or --set. Errors exit 2 as for the other commands.
rainbow-fmt explain¶
The same information by source: which configuration sources apply to
FILE, in resolution order, and the values each one decides, followed by
the inline directives found in the file:
$ rainbow-fmt explain legacy/new.json
# legacy/new.json (json)
defaults
core.indent_style = "space"
…
preset rainbow:balanced
core.line_ending = "lf"
shared.trailing_comma = "never"
rainbow.toml
core.max_width = 100
rainbow.toml override[0]
language.json.object_wrap = "fit"
directives
3: // rainbow: off
9: // rainbow: on
A source that decides nothing for the file (every value it sets is
overridden, or it does not match) is not listed; rainbow-fmt options
shows where every single value comes from. Directives that are not valid
are listed with the error ((invalid: unknown directive 'rainbow: nope')).
A position¶
rainbow-fmt explain FILE:LINE or FILE:LINE:COL (1-based; the file
must exist) explains one place in the file:
$ rainbow-fmt explain app.py:3:5
# app.py:3:5 (python)
node
3:5-3:8 string_start
3:5-3:15 string
3:5-3:15 expression_statement
3:5-3:15 block
2:1-3:15 function_definition
1:1-9:1 module
directives
1: # rainbow: set docstrings="aligned" (applies to 2:1-3:15 function_definition)
options
core.max_width = 99 # rainbow.toml:2:13
core.indent_style = "space" # default
…
language.python.docstrings = "aligned" # rainbow: set at line 1 (configured "preserve": default)
rules
string_start: none (its children, or printed as written)
string: rainbow.toml:4:1 rule[0] (a [[rule]] template)
expression_statement: none (its children, or printed as written)
block: rainbow_fmt.languages.python.format.block
function_definition: none (its children, or printed as written)
module: rainbow_fmt.languages.python.format.module
node: the syntax-tree nodes holding the position, innermost first, with their spans (line:column-line:column).directives: the directives in effect there, each with what it does (arainbow: setapplied to the member, anoffregion, a skipped member or line), ornone.options: every option's value at that position with its origin. A value arainbow: setchanged names the directive's line and the configured value it replaces. Inside anoffregion or a skipped member the options do not apply, and the section says so first.rules: for each node, what prints it: the pack's rule function, a[[rule]]template from the configuration (with its position), or none, for a node printed as its children or as written.
A missing file, or a line or column past the end, is an error (exit 2).
rainbow-fmt init¶
$ rainbow-fmt init
Save the configuration in . as:
1) rainbow.toml
2) pyproject.toml, as [tool.rainbow]
3) rainbow.yaml
4) .rainbow.toml
choice [1]: 2
Start from:
1) infer: the options that reproduce the style of the files here
2) a preset
3) the defaults: no options set
choice [1]:
Infer from the files under [.]: src tests
Add the rainbow-fmt hook to .pre-commit-config.yaml? [y/N] y
wrote pyproject.toml
wrote .pre-commit-config.yaml (the rainbow-fmt hook)
start: infer, 61 files (javascript: 11, python: 50)
mixed: language.javascript.semicolons ("always" in 9 files, "as_needed" in 2 files)
next: rainbow-fmt check .
init [DIR] writes the first configuration of a project (in DIR, . by
default). It decides three things, and on a terminal it asks about the
ones its flags leave open:
- The file (
--file NAME):rainbow.tomlby default, or.rainbow.toml, a YAML name, or a section in an existingpyproject.toml([tool.rainbow], added at the end) orpackage.json(a"rainbow"key, in the file's own indentation). The rest of either file is left as written;initdoes not create them. - The starting point:
--infer [PATH...]writes whatinferfinds in the files under the paths (DIR by default; give DIR before--infer), and lists the mixed options;--preset NAME(repeatable) writespreset = "NAME";--defaultswrites no options, only the core options and their defaults, commented out. On a terminal, infer is offered first when DIR holds files of a known language. - The pre-commit hook (
--pre-commit): the rainbow-fmt repo, at this version's tag (Integrations), goes into the.pre-commit-config.yamlat the root of the git repository, which is created if missing. An existing file gets the entry at the end ofrepos, in its own indentation; when the edited file would not parse as exactly that change, the entry is printed to paste by hand instead. On a terminal the answer defaults to no, and the question is skipped when the hook is already there.
Without a terminal (CI, scripts, agents), init asks nothing: give a
starting point, or --yes for the first answers offered (rainbow.toml,
--infer when DIR holds files of a known language and --defaults
otherwise, no hook). With neither, it exits 2 and lists the invocations.
A configuration already in DIR is never replaced: running init again
with the same result is a no-op (unchanged rainbow.toml), and another
result is an error. A configuration further up that applied to DIR until
now is named in a note, with the extends line that keeps its values.
--dry-run prints the changes as unified diffs and writes nothing. Each
file is read back, as rainbow-fmt reads configurations, before it is
written. Exit codes: 0 written or unchanged; 2 a usage or configuration
error, or no answer, with nothing written.
rainbow-fmt infer¶
$ rainbow-fmt infer src tests
# Inferred by rainbow-fmt infer from 61 files (javascript: 11, python: 50).
[core]
indent_size = 2
[language.javascript]
semicolons = "always" # mixed: "always" in 9 files, "as_needed" in 2 files
infer reads the files under the given paths (hidden directories and
node_modules skipped; up to --limit N files per language, the largest
first, 50 by default), formats them under each candidate value of each
option, and picks, option by option, the value that changes the fewest
lines. The result is the rainbow.toml that reproduces the project's
style; --write saves it in the working directory (never over an
existing one), and init --infer saves it in the
file of your choice. Values equal to the defaults are left out.
"preserve"is never inferred: it reproduces anything, so it says nothing about the style. Use it by hand for an option the project does not care about.- An option whose files disagree is mixed: it is set to the value that wins in most files, and the counts are in a comment. That is the list of things to decide.
- Line endings are counted, not formatted:
crlfwhen at least half the files use it. - Every candidate means formatting every sampled file, so a large
project takes a minute or two;
--limittrades accuracy for time.
rainbow-fmt test-pack¶
$ rainbow-fmt test-pack path/to/rainbow-lang-scheme
# scheme (path/to/rainbow-lang-scheme/fixtures, 7 cases)
ok 01_forms_that_fit
ok 02_special_forms
…
ok 07_syntax_error_is_left_unchanged
option matrix: 14 combinations, 14 safe
ok
PACK is a pack directory (its pyproject.toml names the Language in
the rainbow_fmt.languages entry-point group and fixtures/ holds the
golden cases; the pack need not be installed) or the name of an installed
language with --fixtures DIR. Every fixture's input must format to its
expected.*, formatting the output again must change nothing, and the
verifier must accept it. Then every value of every pack option is tried
on every fixture and on every file of --corpus PATH (files or
directories, repeatable), which must be safe in the same sense, whatever
the output. Each failure is listed (FAIL case: …, with a diff for a
wrong expected output); the exit code is 1 when a check fails, 2 for a
usage error. extending.md has the
pack's side.