Skip to main content

Protoc Plugin

Buf ships a binary protoc-gen-buf-breaking that performs the breaking change detection functionality as a protoc plugin. This is useful in situations where you already have a protoc plugin setup, such as Bazel.

All flags and config are passed as an option to the plugin as JSON. This must be done with the --buf-breaking_opt flag as opposed to a parameter to --buf-breaking_out as the option will include the ":" character as part of JSON.

The option for protoc-gen-buf-breaking has the following shape:

{  "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}

For example:

{  "against_input": "image.bin",  "limit_to_input_files": true}
  • against_input is required and limited to image formats, i.e the format must be bin or json, and cannot be dir, git, tar, zip, etc.
  • limit_to_input_files says to limit checks to those files under build by protoc in the current invocation, i.e. the file_to_generate in the CodeGeneratorRequest. Generally, you will want to set this option when using this plugin. We do not make this the default to have symmetry with buf breaking.
$ protoc -I . --buf-breaking_out=. '--buf-breaking_opt={"against_input":"image.bin","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".