Usage

The buf format command rewrites .proto files in-place according to an opinionated style.

Configuration

The buf format command has no configuration options. There's only one way to format .proto files, so that every .proto file looks and feels the same way. Stop wasting time and energy on deciding how .proto files ought to be formatted - buf decides for you so you don't have to.

Examples

By default, the input is the current directory and the formatted content is written to stdout. For example, given the following tree:

.└── proto    ├── buf.yaml    └── simple        └── v1            └── simple.proto

proto/simple/v1/simple.proto

syntax = "proto3";
package simple.v1;

message Object {     string key = 1;    bytes value = 2;}

# Write the current directory's formatted content to stdout$ buf formatsyntax = "proto3";
package simple.v1;
message Object {  string key = 1;  bytes value = 2;}

Rewrite the file(s) in-place with -w. For example,

# Rewrite the files defined in the current directory in-place$ buf format -w$ cat proto/simple/v1/simple.protosyntax = "proto3";
package simple.v1;
message Object {  string key = 1;  bytes value = 2;}

Most people will want to use 'buf format -w'.

Display a diff between the original and formatted content with -d. For example,

# Write a diff instead of the formatted file$ buf format -ddiff -u proto/simple/v1/simple.proto.orig proto/simple/v1/simple.proto--- proto/simple/v1/simple.proto.orig    ...+++ proto/simple/v1/simple.proto         ...@@ -2,8 +2,7 @@
 package simple.v1;
- message Object {-    string key = 1;-   bytes value = 2;+  string key = 1;+  bytes value = 2; }

You can also 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 an input. For example,

# Write the formatted file to stdout$ buf format proto/simple/v1/simple.protosyntax = "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. For example,

# Write the formatted file to another file$ buf format proto/simple/v1/simple.proto -o formatted/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. For example,

# 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 -wdiff -u proto/simple/v1/simple.proto.orig proto/simple/v1/simple.proto...

The -w and -o flags cannot be used together in a single invocation.