skip to content

What does SwiftFormat's --lint mode do differently from a normal run, and what do --lenient and its exit codes mean for a CI step?

level: middleimportance: should knowfreq 38%

answer

  1. same rules, nothing written
  2. formats in memory, then compares
  3. one line per change, with the rule name
  4. exit codes 0, 1 and 70
  5. --lenient changes the verdict, not the rules

basics

~20 s

With --lint, SwiftFormat formats each file in memory, writes nothing, reports every line that would change and exits 1 if any file needs formatting. --lenient keeps the report but exits 0; exit 70 means bad input or configuration.

solid answer

~40 s

`swiftformat --lint .` runs exactly the rules and options a normal run would, formats each file in memory and compares the result with the input, so CI checks code against the same `.swiftformat` developers format with. Each line that needs a change is printed as `path:line:1: error: (ruleName) description`, and the run exits **1** when any file needs formatting, **0** when none do, and **70** for a program error such as an unknown option. `--lenient` prints the same lines as warnings and exits 0, which suits an advisory step or an Xcode build phase. `--dry-run` only counts the files that would change and exits 0, while `--strict` makes a normal formatting run write its changes and still exit 1. Rules listed under `--lint-only` run only in lint mode.

code

bash · 8 lines
bash
# Gate: fails the job (exit 1) when any file needs formatting
swiftformat --lint .

# Advisory: same report as warnings, always exits 0 unless the config is broken (70)
swiftformat --lint --lenient .

# Format and still fail if anything had to change
swiftformat --strict .

go deeper

for a junior

Recall that --lint changes no files, reports lines needing formatting and fails with exit code 1, while a plain run rewrites the files.

for a middle

Explain the three exit codes, how --lenient, --strict and --dry-run differ, and why linting with the formatter's own configuration keeps CI and laptops in agreement.

for a senior

Choose between a gating --lint step and an advisory --lenient one, use --lint-only for rules that need human fixes, and adopt the gate on legacy code with one formatting commit or a snapshot.

for a principal

Decide whether layout is enforced at all: a hard gate ends style review comments but blocks merges on whitespace, while an advisory report keeps flow but lets drift accumulate.

## Format mode versus lint mode SwiftFormat is a formatter first: a plain `swiftformat .` rewrites every Swift file it finds in place. `--lint` turns the same engine into a checker. - It runs **the same rules and options** as format mode, read from the same `.swiftformat` files, so CI judges code by exactly the configuration developers format with. - It formats each file **in memory**, compares the result with the input, and reports each line that differs. - It **writes nothing** to disk; `--output` is ignored with a warning in this mode. Because both modes share one configuration, a file that passes `--lint` is one a developer's local `swiftformat` run would leave untouched, and vice versa, apart from any rules listed under `--lint-only`. That symmetry is the reason to lint with the formatter rather than with a second tool's approximation of its rules. ## What a lint run prints The default reporter prints one compiler-style line per change, naming the rule that wants it, followed by a summary: ```plaintext /ci/PetAdoption/Sources/Breeds/BreedTable.swift:14:1: error: (trailingCommas) Add or remove trailing commas in comma-separated lists. /ci/PetAdoption/Sources/Breeds/BreedTable.swift:22:1: error: (consecutiveSpaces) Replace consecutive spaces with a single space. Source input did not pass lint check. 1/48 files require formatting. ``` Other formats are available with `--reporter json`, `github-actions-log`, `xml` (Checkstyle-compatible) or `sarif`, written to a file with `--report path`. `--quiet` suppresses everything except errors, and `--verbose` also lists files that needed no change. ## Exit codes | Code | Meaning | When you see it | |---|---|---| | `0` | success | formatting finished, or `--lint` found nothing, or `--lenient` was set | | `1` | lint failure | `--lint` without `--lenient` found code needing changes, or `--strict` applied changes | | `70` | program error | unreadable input, a bad option, a `--min-version` the binary does not meet | A CI job that fails on exit 1 enforces the format; a job that fails only on 70 catches a broken configuration while leaving style advisory. ## --lenient, --strict and --dry-run These three flags are easy to mix up, so compare them directly: 1. `--lint --lenient` checks, prints each change as a **warning** instead of an error, and exits 0. Use it for an advisory step, or in an Xcode build phase that should show issues without failing the build. 2. `--strict` belongs to format mode: SwiftFormat writes its changes **and** exits 1 if it had to change anything, so a pipeline both fixes the code and learns that it was unformatted. 3. `--dry-run` formats in memory, changes nothing and reports how many files would have been formatted, but exits 0 unless `--strict` is added. It is a preview, not a gate. ## Lint-only rules `--lint-only` names rules that run only in lint mode. In a normal run they are removed from the rule set, so local formatting never applies them, while `--lint` still reports their violations: ```plaintext --rules braces,indent --lint-only trailingClosures,unusedArguments ``` That fits rules whose rewrite a team wants a human to apply, such as renaming unused arguments, while the purely mechanical layout rules keep autofixing. ## Adopting --lint on unformatted code Turning on a failing `--lint` step over a codebase that was never formatted fails every file at once. Two ways through: - Format the whole codebase in one dedicated commit, then enable the gate, so the formatting change never hides inside a feature pull request. - Since 0.64.0, run once with `--snapshot`: it creates a `.swiftformat-snapshot` file at the inputs' common root, and from then on SwiftFormat skips files whose contents still match their snapshot, so only new and modified files are checked. Snapshot entries are not tied to rules or options, so changing the configuration does not wake up unchanged files; delete the file and run `--snapshot` again to refresh it. ## Wiring the report into tools - `--reporter github-actions-log` prints each change as a CI log annotation, which the README's example workflow uses to surface warnings on pull requests. - `--reporter sarif --report swiftformat.sarif` writes a file a code-scanning tool can ingest, and `json` or `xml` suit custom dashboards. - In an Xcode Run Script phase, the default reporter's compiler-style lines appear in the issue navigator, so `--lint --lenient` gives in-editor feedback without failing the build or touching files. - Treat exit code 70 as a hard failure everywhere, even in an advisory job: it means the configuration itself is broken and nothing was checked. 0.64.0 also added `--color auto|always|never`, so `--color always` keeps colored warnings in a captured CI log.

  • How do you start enforcing --lint on a codebase that has never been formatted?
    Either reformat everything in one dedicated commit and then switch the gate on, or, from SwiftFormat 0.64.0, run once with `--snapshot`, which creates a `.swiftformat-snapshot` file; files whose contents still match it are skipped. Only new and modified files are then checked, and changing the rules does not reformat untouched files until the snapshot is deleted and captured again.
  • What does --lint-only buy a team over simply enabling a rule?
    A rule listed under `--lint-only` is removed from normal formatting runs and added in `--lint` runs. Developers' local `swiftformat` never rewrites code with it, yet CI still reports each violation, so a rule whose fix needs human judgement, such as `unusedArguments`, can be enforced without being applied automatically.

  • --lint fixes the files first and then reports what it changed.
  • --lenient skips the rules that would otherwise fail the run.
  • --dry-run on its own fails the build when files need formatting.
  • Exit code 1 means SwiftFormat crashed or the configuration is invalid.
  • Lint mode reads a separate, stricter rule set from format mode.

Assumes SwiftFormat 0.64.0; --snapshot and --color were added in that release, while --lint, --lenient, --strict and the exit codes predate it.