buf format: Canonical .proto Formatting in CI
buf format applies a canonical layout to .proto files; with --exit-code it fails CI when any file is not already formatted.
buf format is the gofmt of protobuf. In CI you usually run it in check mode so an unformatted file blocks the merge instead of being silently rewritten.
What it does
buf format parses each .proto and re-emits it in a fixed style (consistent indentation, field alignment, import ordering). By default it prints the formatted result to stdout; -w writes in place, -d shows a diff, and --exit-code makes it return non-zero when changes would be made.
Common usage
# write formatting in place
buf format -w
# CI check: fail if anything is unformatted
buf format --diff --exit-code
# format a single path
buf format -w --path proto/api/v1Flags and options
| Flag | What it does |
|---|---|
| -w, --write | Rewrite files in place |
| -d, --diff | Print a unified diff of the changes |
| --exit-code | Exit non-zero if any file would change (check mode) |
| -o, --output <path> | Write formatted output to a file or - for stdout |
| --path <path> | Restrict formatting to specific files or dirs |
In CI
Use buf format --diff --exit-code as a gate so the job fails and shows exactly what is misformatted, without mutating the checkout. Run buf format -w locally (or in a pre-commit hook) so contributors fix it before pushing.
Common errors in CI
In check mode the job exits non-zero and the --diff output shows the needed changes; the fix is to run buf format -w and commit. A hard "Failure: <file>: syntax error" means the file does not parse, so format cannot run; fix the syntax (usually a missing semicolon or brace) first, often surfaced more clearly by buf build.