Configuration

Configuration for Buf's various operations is usually handled via a configuration file buf.yaml checked in to the root of your repository. It is recommended to always have a buf.yaml file checked in to your current repository.

The default configuration location is dependent on the Input. See the Input documentation for more details. For the general case, namely using your current directory as Input, buf expects a buf.yaml file in your current directory.

If there is no buf.yaml in the expected location, buf operates as if there is a buf.yaml file with the default values, detailed below.

Configuration overrides

Specifying an alternative configuration location is an advanced feature. For easy usage of buf, simply put a buf.yaml file in the root of your repository, and run buf from the root of your repository.

Users can explicitly set a configuration via a file path or direct JSON or YAML data. This is useful for situations where you may want to specify all options via the command line, for example with Bazel integrations and/or when using the protoc plugins.

All commands have one or more --.*config flags that control this behavior For example:

  • buf build --config specifies the config for the source input.
  • buf check lint --config specifies the config for the source or image input.
  • buf check breaking --config specifies the config for the source or image input.
  • buf check breaking --against-config specifies the config for the source or image input to compare against.

The value of this flag is interpreted as follows:

  • If the value ends in .json, this is interpreted to be a local path to a JSON file.
  • If the value ends in .yaml, this is interpreted to be a local path to a YAML file.
  • Otherwise, this is interpreted to be either JSON or YAML data, which is directly parsed.

Examples:

# Read the JSON file foo/bar.json.
buf check lint --config foo/bar.json
# Read the YAML file foo/bar.yaml.
buf check lint --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 ENUM_NO_ALLOW_ALIAS lint checker for linting.
buf check lint --config '{"lint":{"use":["ENUM_NO_ALLOW_ALIAS"]}}'

buf.yaml defaults

The below is a buf.yaml file that represents all default values being explicitly set, that is this file is the equivalent of no options being set in your buf.yaml at all.

version: v1beta1
build:
roots:
- .
lint:
use:
- DEFAULT
enum_zero_value_suffix: _UNSPECIFIED
rpc_allow_same_request_response: false
rpc_allow_google_protobuf_empty_requests: false
rpc_allow_google_protobuf_empty_responses: false
service_suffix: Service
breaking:
use:
- FILE

buf.yaml reference

The below is a commented reference file for all options. See the individual build, lint, and breaking documentation for more details.

# This specifies the configuration file version.
#
# This controls the configuration file layout, defaults, and lint/breaking
# checkers and checker categories. Buf takes breaking changes seriously in
# all aspects, and none of these will ever change for a given version.
#
# The only currently valid version is "v1beta1".
# This key will be required for Buf v1.0.
version: v1beta1
# This specifies the buf.yaml layout.
#
# buf.yaml files should always be in the root of your repository.
# build contains the options for builds.
#
# This affects the behavior of buf build, as well as the build behavior
# for source lint and breaking change checks.
#
# If you want to build all files in your repository, and all imports in your
# .proto files derive from the root of your repository, this section can be
# omitted.
build:
# roots is the directories that all .proto files are contained within, and
# all imports must derive from.
#
# Only .proto files within these directory will be compiled. This path must
# be relative to directory that buf.yaml is in (usually the root of your
# repository).
#
# Roots can not overlap, that is one root can not contain another root. For
# example, "a", and "a/b" would be invalid.
#
# The default is the directory of buf.yaml (usually the root of your
# repository). If all of your imports start from this directory, this option
# can be left unset.
roots:
- proto
# excludes is the list of directories within root to exclude.
#
# These directories will not be built or checked. If a directory is excluded,
# buf treats the directory as if it does not exist.
#
# All directory paths in exclude must be relative to the directory of
# your buf.yaml. Only directories can be specified, and all specified
# directories must be within a root directory. For example, if your
# only root is "proto", all excludes must start with "proto".
excludes:
- proto/foo
- proto/bar/baz
# lint contains the options for lint checks.
lint:
# use is the list of checker categories and ids to use for buf check lint.
#
# Categories are sets of checker ids.
# Run buf check ls-lint-checkers --all to get a list of all checkers.
#
# The union of the categories and ids will be used.
#
# The default is [DEFAULT].
use:
- DEFAULT
- UNARY_RPC
# except is the list of checker ids or categories to remove from the use
# list.
#
# This allows removal of specific checkers from the union of checkers derived
# from the use list of categories and ids.
except:
- PACKAGE_DIRECTORY_MATCH
# ignore is the list of directories or files to ignore for all checkers.
#
# All directories and file paths are specified relative to a root directory,
# that is *with the root directory stripped*. For example, if you have a root
# "proto" and want to ignore the directory "proto/bat", you would specify
# "bat" in the ignore list. This is so that these configuration options work
# for both sources and images.
#
# The directory "." is not allowed - this is equivalent to ignoring
# everything.
ignore:
- bat
- ban/ban.proto
# ignore_only is the map from checker id or category to file or directory to
# ignore.
#
# All directories and file paths are specified relative to a root directory,
# that is *with the root directory stripped*, as described above.
#
# The directory "." is not allowed - this is equivalent to using the "except"
# option.
ignore_only:
ENUM_PASCAL_CASE:
- foo/foo.proto
- bar
PACKAGE_AFFINITY:
- foo
# enum_zero_value_suffix affects the behavior of the ENUM_ZERO_VALUE_SUFFIX
# checker.
#
# This will result in this suffix being used instead of the default
# "_UNSPECIFIED" suffix.
enum_zero_value_suffix: _NONE
# rpc_allow_same_request_response affects the behavior of the
# RPC_REQUEST_RESPONSE_UNIQUE checker.
#
# This will result in requests and responses being allowed to be the same
# type for a single RPC.
rpc_allow_same_request_response: true
# rpc_allow_google_protobuf_empty_requests affects the behavior of the
# RPC_REQUEST_STANDARD_NAME and RPC_REQUEST_RESPONSE_UNIQUE checkers.
#
# This will result in google.protobuf.Empty requests being ignored for
# RPC_REQUEST_STANDARD_NAME, and google.protobuf.Empty requests being allowed
# in multiple RPCs.
rpc_allow_google_protobuf_empty_requests: true
# rpc_allow_google_protobuf_empty_responses affects the behavior of the
# RPC_RESPONSE_STANDARD_NAME and the RPC_REQUEST_RESPONSE_UNIQUE checkers.
#
# This will result in google.protobuf.Empty responses being ignored for
# RPC_RESPONSE_STANDARD_NAME, and google.protobuf.Empty responses being
# allowed in multiple RPCs.
rpc_allow_google_protobuf_empty_responses: true
# service_suffix affects the behavior of the SERVICE_SUFFIX checker.
#
# This will result in this suffix being used instead of the default "Service"
# suffix.
service_suffix: API
# allow_comment_ignores allows comment-driven ignores.
#
# If this option is set, leading comments can be added within Protobuf files
# to ignore lint errors for certain components. If any line in a leading comment starts
# with `buf:lint:ignore ID`, then Buf will ignore lint errors for this id. For example:
#
# syntax = "proto3";
# // buf:lint:ignore PACKAGE_LOWER_SNAKE_CASE
# // buf:lint:ignore PACKAGE_VERSION_SUFFIX
# package A;
#
# We do not recommend using this, as it allows indivudal engineers in a large
# organization to decide on their own lint rule exceptions. However, there are
# cases where this is necessarily, and we want users to be able to make informed
# decisions, so we provide this as an opt-in.
allow_comment_ignores: true
# breaking contains the options for breaking checks.
breaking:
# use is the list of checker categories and ids to use for buf check breaking.
#
# Categories are sets of checker ids.
# Run buf check ls-breaking-checkers --all to get a list of all checkers.
#
# The union of the categories and ids will be used.
#
# As opposed to lint, where you may want to do more customization, with breaking
# is is generally better to only choose one of the following options:
#
# - [FILE]
# - [PACKAGE]
# - [WIRE]
# - [WIRE_JSON]
#
# The default is [FILE], as done below.
use:
- FILE
# except is the list of checker ids or categories to remove from the use
# list.
#
# This allows removal of specific checkers from the union of checkers derived
# from the use list of categories and ids.
#
# As opposed to lint, we generally recommend using one of the preconfigured
# options. Removing specific checkers from breaking change detection is an
# advanced option.
except:
- FIELD_SAME_NAME
# ignore is the list of directories or files to ignore for all checkers.
#
# All directories and file paths are specified relative to a root directory,
# that is *with the root directory stripped*. For example, if you have a root
# "proto" and want to ignore the directory "proto/bat", you would specify
# "bat" in the ignore list. This is so that these configuration options work
# for both sources and images.
#
# The directory "." is not allowed - this is equivalent to ignoring
# everything.
ignore:
- bat
- ban/ban.proto
# ignore_only is the map from checker id or category to file or directory to
# ignore.
#
# All directories and file paths are specified relative to a root directory,
# that is *with the root directory stripped*, as described above.
#
# The directory "." is not allowed - this is equivalent to using the "except"
# option.
ignore_only:
FIELD_NO_DELETE:
- foo/foo.proto
- bar
WIRE_JSON:
- foo
# ignore_unstable_packages results in ignoring packages with a last component
# that is one of the unstable forms recognized by the "PACKAGE_VERSION_SUFFIX"
# lint checker. The following forms will be ignored:
#
# - 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
ignore_unstable_packages: true