Formatting
ur format lays out each file as the formatter its language’s projects already use: Python as Black
does, JavaScript, TypeScript, and Markdown as Prettier does, Rust as rustfmt does, and so on. One
command, and one configuration, cover every language in a project, with no formatter to install for
each.
ur format .
Ur searches each directory it is given for source files, skipping hidden files and the paths Git ignores, and rewrites each file in place. It prints how many files it reformatted, left unchanged, skipped, and could not format.
In CI
ur format --check . writes nothing: it lists the files that would change, and fails if any would.
--verify checks each formatted file before writing it: the file must parse as the original did,
differ from it only in layout, and format again to itself. A file that fails keeps its source.
Choosing a style
Each language has a style, the formatter Ur follows for it. A language with more than one, as SQL
has SQLFluff and Ur’s own River, takes the first unless the project chooses another, with style in
its language’s table in ur.toml, or for one run with --style:
ur format --style river queries/
Configuring it
Without an ur.toml, each style reads its formatter’s own configuration as that formatter finds it,
such as Prettier’s .prettierrc and Black’s pyproject.toml. With one, ur.toml decides:
the configuration reference gives every key. The options every style shares, such as
width, have the same name for every style, so width = 100 sets Prettier’s printWidth, Black’s
line-length, and rustfmt’s max_width alike. Each style’s page below gives its defaults, its own
options, and what it makes of a sample.
target names the versions of each language a project targets, such as python-3.11, and
--profile sets one for one run: a style that formats differently by version, as Black does,
formats for the versions targeted. Each language’s page lists the profiles it
takes.
The styles
| Style | Formats | What it is |
|---|---|---|
black | Python | Black, the Python formatter. |
google-java-format | Java | Google's Java formatter, in Google Java Style. |
mathlib | Lean | The style of Mathlib, Lean's library of mathematics. |
prettier | JavaScript, TypeScript, Markdown | Prettier, the formatter for JavaScript, TypeScript, and Markdown. |
river | SQL | Ur's own SQL style, which right-aligns each clause's keyword along a river. |
rubocop | Ruby | RuboCop, the Ruby linter and formatter. |
rustfmt | Rust | rustfmt, Rust's own formatter. |
sqlfluff | SQL | SQLFluff, the SQL linter and formatter. |
tla2tools | TLA+ | The style of the TLA+ tools, tla2tools.jar. |
Ur lints Shell code too, but does not format it yet.
Each style's name is the one ur.toml and --style take; Riveris the only style of Ur's own.