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
.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.
breaking section is specified, the following default configuration is used.
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:
Or run this to use a buf.yaml file that is not in your current directory:
To see all available breaking checkers independent of configuration/defaults:
Breaking checker selection is done through the following options:
This selects the ids or categories to use for breaking change detection. For example, the following
WIRE breaking category, as well as the
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
[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.
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
We do not recommend removing checkers from a category.
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:
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:
This allows directories or files to be excluded from specific breaking checkers when
buf check breaking by taking a map from breaking checker id or category to path.
ignore, the paths should be relative to their root.
For example, the following sets us specific ignores for the id
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.
This results in ignoring packages with a last component that is one of the unstable forms recognized by PACKAGE_VERSION_SUFFIX:
For example, if this option is set, the following packages will be ignored:
As discussed in the configuration documentation, configuration can
be specified using the
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
As explained in the Inputs documentation, Buf will automatically use
build configuration for an against input in the following manner:
zipInputs, Buf will look at the root of the archive for a
gitInputs, Buf will look at the root of the cloned repository at the head of the cloned branch for a
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