Protoc Plugin

Buf ships a binary protoc-gen-buf-check-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-check-breaking_opt flag as opposed to a parameter to --buf_check_breaking_out as the option will include the ":" character as part of JSON.

The option for protoc-gen-buf-check-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" is required, and is limited to image formats, i.e the format must be bin, json, and cannot be dir, git, tar, zip.
  • 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 check breaking.

From the example from the tour:

$ protoc -I . --buf-check-breaking_out=. '--buf-check-breaking_opt={"against_input":"image.bin","limit_to_input_files":true}' $(find . -name '*.proto')
google/ads/googleads/v1/services/expanded_landing_page_view_service.proto:22:1: warning: Import google/protobuf/wrappers.proto but not used.
--buf-check-breaking_out: google/type/date.proto:50:3:Field "3" on message "Date" changed type from "int32" to "string".