Configuration

Buf's breaking change detector is configured through a buf.yaml file that should be checked in to the root of your repository. Buf will automatically read this file if present. Configuration can also be provided via the command-line flag --config, which accepts a path to a .json or .yaml file, or direct JSON or YAML data.

The following is an example of all available configuration options. See the configuration reference for more details.

version: v1beta1
breaking:
use:
- FILE
except:
- RPC_NO_DELETE
ignore:
- bat
- ban/ban.proto
ignore_only:
FIELD_SAME_JSON_NAME:
- foo/foo.proto
- bar
WIRE:
- foo
ignore_unstable_packages: true

If no breaking section is specified, the following default configuration is used.

version: v1beta1
breaking:
use:
- FILE

Breaking checker selection

The primary purpose of configuration is to select the breaking checkers you want to apply.

All breaking checkers have an id, and belong to one or more categories. Configuration options accept both ids and categories, where specifying a category is equivalent to manually listing all ids in that categories.

You can print your currently-configured breaking checkers at any time by running:

$ buf check ls-breaking-checkers

Or run this to use a buf.yaml file that is not in your current directory:

$ buf check ls-breaking-checkers --config foo/buf.yaml

To see all available breaking checkers independent of configuration/defaults:

$ buf check ls-breaking-checkers --all

Breaking checker selection is done through the following options:

use

This selects the ids or categories to use for breaking change detection. For example, the following selects the WIRE breaking category, as well as the FILE_NO_DELETE id:

version: v1beta1
breaking:
use:
- WIRE
- FILE_NO_DELETE

As opposed to lint checkers, breaking checkers are not meant to be overly customized. Breaking checkers are generally meant to work in unison to detect a category of breaking change, as opposed to merely being independent rules.

Usually, you will use one of the following values for use:

  • [FILE] which will enforce that generated stubs do not break on a per-file basis.
  • [PACKAGE] which will enforce that generated stubs do not break on a per-package basis.
  • [WIRE] which will enforce that wire compatibility is not broken.
  • [WIRE_JSON] which will enforce that wire and JSON wire compatibility are not broken.

See the overview for a longer description of the purpose of each category.

The default value is the single item FILE, which is what we recommend.

except

This removes ids or categories from the use list. For example, the following will result in all breaking checkers in the FILE breaking category being used except for FILE_NO_DELETE:

version: v1beta1
breaking:
use:
- FILE
except:
- FILE_NO_DELETE

We do not recommend removing checkers from a category.

ignore

This allows directories or files to be excluded from all breaking checkers when running buf check breaking. The specified directory or file paths should be relative to their root. For example, given a root proto, and a file proto/bar/baz.proto, the following will result in proto/bar/baz.proto being ignored:

version: v1beta1
build:
roots:
- proto
breaking:
ignore:
- bar/baz.proto

This is so that buf check breaking works regardless of what Input it is checking.

This option can be useful for ignoring packages that are in active development but not deployed in production, especially alpha or beta packages, and we expect ignore to be commonly used for this case. For example:

version: v1beta1
breaking:
use:
- FILE
ignore:
- foo/bar/v1beta1
- foo/bar/v1beta2
- foo/baz/v1alpha1

ignore_only

This allows directories or files to be excluded from specific breaking checkers when running buf check breaking by taking a map from breaking checker id or category to path. As with ignore, the paths should be relative to their root.

For example, the following sets us specific ignores for the id FILE_SAME_TYPE and the category WIRE:

version: v1beta1
breaking:
ignore_only:
FILE_SAME_TYPE:
- foo/foo.proto
- bar
WIRE:
- foo

We don't recommend using this option. Additionally, please let us know if you are using it and what your use case is, we would greatly appreciate hearing about it.

ignore_unstable_packages

This results in ignoring packages with a last component that is one of the unstable forms recognized by PACKAGE_VERSION_SUFFIX:

  • v\d+test.*
  • v\d+(alpha|beta)\d+
  • v\d+p\d+(alpha|beta)\d+

For example, if this option is set, the following packages will be ignored:

  • foo.bar.v1alpha1
  • foo.bar.v1beta1
  • foo.bar.v1test

Configuration overrides

As discussed in the configuration documentation, configuration can be specified using the --config flag.

Examples:

# Read the JSON file foo/bar.json.
buf check breaking --against '.git#branch=master' --config foo/bar.json
# Read the YAML file foo/bar.yaml.
buf check breaking --against '.git#tag=v1.0.0' --config foo/bar.yaml
# Use the given JSON data.
# This results in the build assuming there is one root, the current directory, and only
# using the WIRE breaking category.
buf check breaking --against '.git#branch=master' --config '{"breaking":{"use":["WIRE"]}}'

Against input configuration

buf check breaking actually deals with two Protobuf schemas: your current schema (the "input") and your previous schema (the "against input"). The breaking configuration is only needed and read from the input, and has no meaning on the against input - Buf uses your current configuration to determine what breaking checkers to run.

For image formats, there is no build needed, so no configuration is needed for the against input. However, for source formats, Buf needs to know how to build your against input, i.e. it needs to know the roots.

As explained in the Inputs documentation, Buf will automatically use the build configuration for an against input in the following manner:

  • For tar and zip Inputs, Buf will look at the root of the archive for a buf.yaml file after strip_components is applied.
  • For git Inputs, Buf will look at the root of the cloned repository at the head of the cloned branch for a buf.yaml file.

If no file is found, the default build configuration is used, namely a single root which is the root of the source input. You can specify an alternative build configuration on the command line with the --against-config flag. For example, let's say we have a tarball with no configuration, and a single root proto:

$ buf check breaking --against path/to/foo.tar.gz --against-config '{"build":{"roots":["proto"]}}'