skip to content

In a CI pipeline, why run `prettier --check` rather than `prettier --write`, and what do its exit codes 0, 1 and 2 mean?

level: juniorimportance: must knowfreq 34%

answer

  1. report, never rewrite
  2. the checkout is thrown away
  3. one means a style issue
  4. two means Prettier itself failed
  5. --list-different prints names only

basics

~20 s

prettier --check only reports unformatted files and exits 1 when any exist, so CI fails without touching the checkout; --write rewrites files in place for local use. Exit 0 means everything is formatted, exit 2 means Prettier hit an error.

solid answer

~50 s

In CI you want a gate, not a fixer. `prettier . --check` formats each file in memory, compares the result with what is on disk and changes nothing: it prints `[warn]` lines for the files that differ, ends with "Code style issues found … Run Prettier with --write to fix." and exits **1**. Exit **0** means every matched file already matches Prettier's output; exit **2** means something went wrong with Prettier itself, such as a file it cannot parse or a pattern that matched no files. `--write` rewrites files in place, which is what a developer runs locally or the editor does on save; in CI the rewritten files would be discarded and the job would pass while the branch stays unformatted. `--list-different` (`-l`) is the scriptable sibling: same exit 1, but it prints only the file names.

code

bash · 12 lines
bash
$ npx prettier . --check
Checking formatting...
[warn] src/billing/Invoice.tsx
[warn] Code style issues found in the above file. Run Prettier with --write to fix.
$ echo $?
1
$ npx prettier src/billing/Invoice.tsx --write
$ npx prettier . --check
Checking formatting...
All matched files use Prettier code style!
$ echo $?
0

go deeper

for a junior

Recall the split: --write rewrites files, --check only reports and exits 1 when something differs. Know that 0 is clean and 2 is an error in Prettier, not a style problem.

for a middle

Explain why --write in CI produces a green job on an unformatted branch, when --list-different beats --check, and which situations end in exit 2 rather than 1.

for a senior

Read a failing log quickly: tell a syntax error or an empty glob from a style failure, and know that --check plus --write exits 0 after fixing.

for a principal

Decide where formatting is fixed and where it is only verified, so developers fix it locally and the pipeline stays a pure, repeatable check.

## Three ways to run the same formatter Prettier is a **formatter**: given a file, it produces the one layout its rules allow. The CLI decides what happens to that output. Three flags matter for day-to-day work: | Flag | Touches files? | What it prints | Exit code when a file differs | |---|---|---|---| | `--write` / `-w` | Yes, rewrites in place | each file with its timing | `0` | | `--check` / `-c` | No | `[warn]` per file plus a summary | `1` | | `--list-different` / `-l` | No | only the file names | `1` | A typical pair of scripts is `prettier . --write` for developers and `prettier . --check` for the pipeline. Both read the same configuration file, which is why the docs recommend keeping options such as `singleQuote` in a `.prettierrc` rather than in CLI flags: the CLI, the editor integration and every other tool then agree. ## What the exit codes mean Prettier's documentation defines three codes for `--check`: 1. **`0`** - everything matched by the patterns is formatted. The console says "All matched files use Prettier code style!" 2. **`1`** - at least one file is not formatted. Each one is listed and the summary reads "Code style issues found in 2 files. Run Prettier with --write to fix." 3. **`2`** - something is wrong with Prettier rather than with the style of your code. Cases that land on **`2`** in the CLI source include: - a file Prettier **cannot parse** (a syntax error is reported as `SyntaxError` with its position, and the summary says "Error occurred when checking code style"); - a pattern that matches **no files** ("No matching files"), unless you pass `--no-error-on-unmatched-pattern`; - a file whose type Prettier **cannot infer a parser** for, unless you pass `--ignore-unknown` (`-u`); - a file that cannot be read or written. One caveat from the source: an invalid option value such as a non-integer `printWidth` stops the whole run with exit `1`, because it would fail for every file. So exit `1` normally means "unformatted files", but read the log before assuming it. ## Why CI checks and developers write - **A gate must fail.** `--write` exits `0` after fixing files; in CI those fixes live only in a throwaway checkout, so the job goes green while the branch stays unformatted. - **A check is reproducible.** `--check` changes nothing, so running it twice gives the same answer, and the log lists exactly which files to fix. - **Fixing belongs where the commit is made**: on save in the editor, or by running `prettier . --write` before pushing. Formatting staged files in a commit hook is a separate subject, covered by the question on Git hook managers. ## `--check` against `--list-different` The docs describe `--check` as working "the same way as `--list-different`" but with a human-friendly summary. Use `--check` when people read the output (a CI log), and `--list-different` when another program consumes it: it prints one path per line and nothing else, so you can pipe the list into another command. Both exit `1` when anything differs and neither changes a file. ## Combining flags `--check` and `--write` can be passed together. Prettier then rewrites the unformatted files, prints "Code style issues fixed in …" and, because the files are now formatted, does **not** set exit `1`. That is useful locally to see what changed; it is useless as a CI gate. Two more details that trip people up: - **Quote the globs**: `prettier "src/**/*.{ts,tsx}" --check`. Quoting lets the Prettier CLI expand the pattern instead of the shell, which keeps the command portable. - **What is checked is what is not ignored**: files in `node_modules`, in version-control folders and in the default ignore files are skipped before the comparison, so they can never fail the check. ## A worked example On a coworking-space membership portal, the pipeline runs `npx prettier . --check`. A pull request adds `src/billing/Invoice.tsx` written without Prettier. The job prints `[warn] src/billing/Invoice.tsx`, the summary line, and exits `1`; the developer runs `npx prettier src/billing/Invoice.tsx --write`, commits, and the next run exits `0`. If the same file had a stray `<` that broke parsing, the log would show a `SyntaxError` with line and column and the job would exit `2`, telling the developer that the code, not its layout, needs fixing first.

  • What does `prettier --check` do when its glob matches no files at all?
    It reports an error such as "No matching files" and exits `2`, because an empty match usually means a typo in the pattern. If the pattern is legitimately empty in some checkouts, pass `--no-error-on-unmatched-pattern` to suppress that error.
  • Why should formatting options live in a `.prettierrc` rather than as flags in the CI script?
    Flags such as `--single-quote` apply only to that one command. Editor integrations and other tooling read the configuration file, not your CI script, so options passed as flags make the editor format one way and CI check another. A `.prettierrc` gives every caller the same options.
  • A CI log shows exit code 2 but no `[warn]` lines - where do you look?
    Exit `2` is an error, not a style finding. Look for a `SyntaxError` with a file and position, a "No matching files" message from a bad glob, or a file type Prettier has no parser for; `--ignore-unknown` skips the last kind.

  • prettier --check fixes the files it reports
  • Running prettier --write in CI enforces formatting
  • Exit code 2 means some files are unformatted
  • --list-different only prints names and never fails the job
  • A file with a syntax error just counts as unformatted