buf format
Format Protobuf files
Usage
$ buf format <source> [flags]
Description
By default, the source is the current directory and the formatted content is written to stdout.
Examples:
Write the current directory's formatted content to stdout:
$ buf format
Most people will want to rewrite the files defined in the current directory in-place with -w:
$ buf format -w
Display a diff between the original and formatted content with -d Write a diff instead of the formatted file:
$ buf format simple/simple.proto -d
$ diff -u simple/simple.proto.orig simple/simple.proto
--- simple/simple.proto.orig 2022-03-24 09:44:10.000000000 -0700
+++ simple/simple.proto 2022-03-24 09:44:10.000000000 -0700
@@ -2,8 +2,7 @@
package simple;
-
message Object {
- string key = 1;
- bytes value = 2;
+ string key = 1;
+ bytes value = 2;
}
Use the --exit-code flag to exit with a non-zero exit code if there is a diff:
$ buf format --exit-code
$ buf format -w --exit-code
$ buf format -d --exit-code
Format a file, directory, or module reference by specifying a source e.g. Write the formatted file to stdout:
$ buf format simple/simple.proto
syntax = "proto3";
package simple;
message Object {
string key = 1;
bytes value = 2;
}
Write the formatted directory to stdout:
$ buf format simple
...
Write the formatted module reference to stdout:
$ buf format buf.build/acme/petapis
...
Write the result to a specified output file or directory with -o e.g.
Write the formatted file to another file:
$ buf format simple/simple.proto -o simple/simple.formatted.proto
Write the formatted directory to another directory, creating it if it doesn't exist:
$ buf format proto -o formatted
This also works with module references:
$ buf format buf.build/acme/weather -o formatted
Rewrite the file(s) in-place with -w. e.g.
Rewrite a single file in-place:
$ buf format simple.proto -w
Rewrite an entire directory in-place:
$ buf format proto -w
Write a diff and rewrite the file(s) in-place:
$ buf format simple -d -w
$ diff -u simple/simple.proto.orig simple/simple.proto
...
The -w and -o flags cannot be used together in a single invocation.
Flags
--config string
The buf.yaml file or data to use for configuration
-d, --diff
Display diffs instead of rewriting files
--disable-symlinks
Do not follow symlinks when reading sources or configuration from the local filesystem By default, symlinks are followed in this CLI, but never followed on the Buf Schema Registry
--error-format string
The format for build errors printed to stderr. Must be one of [text,json,msvs,junit,github-actions]
--exclude-path strings
Exclude specific files or directories, e.g. "proto/a/a.proto", "proto/a" If specified multiple times, the union is taken
--exit-code
Exit with a non-zero exit code if files were not already formatted
-h, --help
help for format
-o, --output string
The output location for the formatted files. Must be one of format [dir,git,protofile,tar,zip]. If omitted, the result is written to stdout
--path strings
Limit to specific files or directories, e.g. "proto/a/a.proto", "proto/a" If specified multiple times, the union is taken
-w, --write
Rewrite files in-place
Flags inherited from parent commands
--debug
Turn on debug logging
--log-format string
The log format [text,color,json]
--timeout duration
The duration until timing out, setting it to zero means no timeout
-v, --verbose
Turn on verbose mode
Parent Command
- buf - The Buf CLI