cargo fmt --check: Formatting Gate in CI
cargo fmt --check runs rustfmt in check mode: it prints a diff and exits non-zero if any file is not formatted, but it does not edit files.
For a formatting gate you do not want CI rewriting files; --check just reports and fails. Pair it with --all to cover every workspace crate.
What it does
cargo fmt drives rustfmt over the package. With --check it does not write changes; it prints the diff that would be applied and exits with code 1 if anything differs. --all formats every member of the workspace.
Common usage
cargo fmt --all --check
cargo fmt --all # actually rewrite files locally
cargo fmt --check -- --edition 2021 # pass options to rustfmtFlags
| Flag | What it does |
|---|---|
| --check | Report diffs and exit non-zero; do not modify files |
| --all | Format/check every package in the workspace |
| -p <crate> | Limit to a single package |
| -- --edition <year> | Pass the edition to rustfmt |
| -- --config <k=v> | Override a rustfmt config value |
In CI
rustfmt is a rustup component (rustup component add rustfmt). The check needs no build cache since it does not compile, so it is a fast, cheap early gate. Keep a committed rustfmt.toml so local and CI formatting agree across toolchain versions.
Common errors in CI
"error: components ... rustfmt are unavailable for download" means the pinned nightly lacks rustfmt; pick a toolchain date that has it or install the stable component. A successful diff print followed by a non-zero exit is expected: that is the gate failing. "error: unknown option --check" only on very old cargo means you must use cargo fmt -- --check instead.