Code formatting—Tutorial

We recommend completing the tour for an introduction to the buf format command.

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

Original—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:

Reformatted—weather.proto

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:

proto/simple/v1/simple.proto

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.