buff

Lint Protocol Buffer files

$ buf lint [path/to/protos]

$ buf build [path/to/protos]

$ buf breaking --against [.git#branch=main]

$ buf generate

$ buf format -w [path/to/protos]

$ buf push

$ buf dep add [buf.build/googleapis/googleapis]

buf command [options] [path]

buf is a tool for working with Protocol Buffers, providing linting, breaking change detection, code generation, and a dependency management ecosystem. It addresses common pain points with protoc and large Protobuf codebases.
The linting engine enforces best practices and style consistency across Protobuf definitions. Breaking change detection compares against git branches or published versions, preventing accidental API incompatibilities.
Code generation is configured via buf.gen.yaml, replacing complex protoc command lines. The Buf Schema Registry (BSR) enables sharing and versioning Protobuf modules as dependencies, similar to package managers for other languages.

lint

Run linting rules on Protobuf files.

Build Protobuf files and verify they compile.

Check for breaking API changes.

Generate code using configured plugins.

Format Protobuf files.

Push module to Buf Schema Registry (BSR).

Manage dependencies (add, update).

Export module to a directory.

Reference to compare against for breaking changes.

Write formatted output back to files.

Path to buf.yaml configuration.

Error output format: text, json, msvs, github-actions.

buf.yaml configuration is required for most operations. The BSR requires authentication for pushing modules. Breaking change detection may flag intentional changes as breaking; review carefully. Some protoc plugins may not be directly compatible with buf generate.

Buf was created by the team behind gRPC at Uber and founded as a company in 2020. It was developed to solve problems they encountered managing large Protobuf codebases, including inconsistent style, accidental breaking changes, and complex build configurations. The Buf Schema Registry launched to provide a npm/Maven-like experience for Protobuf dependencies.

protoc(1), grpcurl(1), grpc-tools(1)