Skip to content

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, *.json and *.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_modules and the [files] exclude patterns 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, for format, writes the result to standard output. --stdin-filepath is 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):

  1. it parses without syntax errors;
  2. 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;
  3. it has the same comments, with the same text, in the same order (a comment may move past a comma);
  4. 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 (a rainbow: set applied to the member, an off region, a skipped member or line), or none.
  • options: every option's value at that position with its origin. A value a rainbow: set changed names the directive's line and the configured value it replaces. Inside an off region 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.toml by default, or .rainbow.toml, a YAML name, or a section in an existing pyproject.toml ([tool.rainbow], added at the end) or package.json (a "rainbow" key, in the file's own indentation). The rest of either file is left as written; init does not create them.
  • The starting point: --infer [PATH...] writes what infer finds in the files under the paths (DIR by default; give DIR before --infer), and lists the mixed options; --preset NAME (repeatable) writes preset = "NAME"; --defaults writes 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.yaml at the root of the git repository, which is created if missing. An existing file gets the entry at the end of repos, 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: crlf when at least half the files use it.
  • Every candidate means formatting every sampled file, so a large project takes a minute or two; --limit trades 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.