Formatting your Protobuf files using a consistent and standardized style is a critical aspect of ensuring the
readability and maintainability of your codebase. The Buf CLI provides a simple and powerful solution for enforcing
this. With the buf format
command, you can ensure that your Protobuf files adhere to industry best practices.
buf format
rewrites Protobuf files according to an opinionated style, so it
has no configuration options. No need to waste time and energy deciding how .proto
files ought to be
formatted—the tool decides so you don't have to.
In this tutorial, you'll learn how to solve some common formatting problems with buf format
.
Usage and examples
By default, the input is the current directory and the formatted content is written to
stdout. Given the weather.proto
example file and file layout below, you get the following changes when you run the command.
$ buf format
.
└── proto
├── buf.yaml
└── weather
└── v1
└── weather.proto
syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "google/protobuf/datetime.proto";
package weather;
message Location {
float latitude = 1;
float longitude = 2;
}
message CurrentWeatherRequest {
Location location = 1;
}
message CurrentWeatherResponse {
float temperature = 1;
}
service WeatherVisionService {
rpc CurrentWeather (CurrentWeatherRequest) returns (CurrentWeatherResponse);
}
you'll get a reformatted weather.proto
file:
syntax = "proto3";
package weather;
import "google/protobuf/datetime.proto";
import "google/protobuf/timestamp.proto";
message Location {
float latitude = 1;
float longitude = 2;
}
message CurrentWeatherRequest {
Location location = 1;
}
message CurrentWeatherResponse {
float temperature = 1;
}
service WeatherVisionService {
rpc CurrentWeather(CurrentWeatherRequest) returns (CurrentWeatherResponse);
}
For a complete list of flags for buf format
, see the reference. Below are some of the key options,
with results for a simple.proto
file:
syntax = "proto3";
package simple.v1;
message Object {
string key = 1;
bytes value = 2;
}
To rewrite files in place, use the -w
or --write
flag.
$ buf format -w $ cat proto/simple/v1/simple.proto
Outputsyntax = "proto3"; package simple.v1; message Object { string key = 1; bytes value = 2; }
Most people will want to use buf format -w
.
To display a diff between the original and formatted content, use -d
or --diff
.
$ buf format -d
Outputdiff -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
To write the result to a specified output file or directory, use -o
or --output
and specify the file path.
# 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
The -w and -o flags cannot be used together in a single invocation.