protoc
plugins
Buf ships with two binaries that you can use as protoc
plugins:
Buf doesn't use these binaries but they can be useful in situations where you have a protoc setup in place, for example when using Bazel.
protoc-gen-buf-breaking
The protoc-gen-buf-breaking
binary performs breaking change detection as a protoc
plugin.
All flags and config are passed to the plugin as an option in JSON format. You need to pass these options using
--buf-breaking_opt
as opposed to --buf-breaking_out
, as the option includes the :
character as part of JSON.
The option for protoc-gen-buf-breaking
has this structure:
{
"against_input": @string,
"against_input_config": @string_or_json_config,
"input_config": @string_or_json_config,
"limit_to_input_files": @bool,
"exclude_imports": @bool,
"log_level": @string,
"log_format": @string,
"error_format": @string,
"timeout": @duration
}
An example option:
against_input
is required and limited to Buf image formats. The format must bebinpb
,json
, ortxtpb
, and can't bedir
,git
,tar
,zip
, etc.limit_to_input_files
limits checks to those files under build byprotoc
in the current invocation, in this case thefile_to_generate
in theCodeGeneratorRequest
. We usually recommend setting this option when using this plugin. We don't make this the default in order to maintain symmetry withbuf breaking
.
Here's an example usage of the binary in conjunction with protoc:
$ protoc \
-I . \
--buf-breaking_out=. \
'--buf-breaking_opt={"against_input":"image.binpb","limit_to_input_files":true}' \
$(find . -name '*.proto')
---
pet/v1/pet.proto:18:3:Field "1" on message "Pet" changed type from "enum" to "string".
protoc-gen-buf-lint
The protoc-gen-buf-lint
binary performs linting as a protoc
plugin.
All flags and config are passed to the plugin as an option in JSON format. You need to pass these options using
--buf-lint_opt
as opposed to --buf-lint_out
, as the option includes the :
character as part of JSON.
The option for protoc-gen-buf-lint
has this structure:
{
"input_config": @string_or_json_config,
"log_level": @string,
"log_format": @string,
"error_format": @string,
"timeout": @duration
}
An example option:
{
"input_config": {
"version": "v1",
"lint": {
"use": ["ENUM_NO_ALLOW_ALIAS"]
}
},
"error_format": "json"
}
Here's an example usage of the binary in conjunction with protoc:
$ protoc \
-I . \
--buf-lint_out=. \
$(find . -name '*.proto')
google/type/datetime.proto:17:1:Package name "google.type" should be suffixed with a correctly formed version, such as "google.type.v1".
pet/v1/pet.proto:42:10:Field name "petID" should be lower_snake_case, such as "pet_id".
pet/v1/pet.proto:47:9:Service name "PetStore" should be suffixed with "Service".
You can also use a custom configuration: