Skip to main content

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 lint --config specifies the config for the source or image input.
  • buf breaking --config specifies the config for the source or image input.
  • buf 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 lint --config foo/bar.json
# Read the YAML file foo/bar.yaml.
buf 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 rule for linting.
buf 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
# rules and rule 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
# 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 rules.
#
# 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 [.], i.e. the directory of your buf.yaml (usually the root of
# your repository). If all of your imports start from this directory, this
# option can be left unset.
roots:
- .
# 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:
- foo
- bar/baz
# lint contains the options for lint rules.
lint:
# use is the list of rule categories and ids to use for buf lint.
#
# Categories are sets of rule ids.
# Run buf config ls-lint-rules --all to get a list of all rules.
#
# The union of the categories and ids will be used.
#
# The default is [DEFAULT].
use:
- DEFAULT
# except is the list of rule ids or categories to remove from the use
# list.
#
# This allows removal of specific rules from the union of rules derived
# from the use list of categories and ids.
except:
- ENUM_VALUE_UPPER_SNAKE_CASE
# ignore is the list of directories or files to ignore for all rules.
#
# 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 rule 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.
#
# Note you can generate this section using
# "buf lint --error-format=config-ignore-yaml". The result of this command
# can be copy/pasted here.
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
# rule.
#
# This will result in this suffix being used instead of the default
# "_UNSPECIFIED" suffix.
enum_zero_value_suffix: _UNSPECIFIED
# rpc_allow_same_request_response affects the behavior of the
# RPC_REQUEST_RESPONSE_UNIQUE rule.
#
# This will result in requests and responses being allowed to be the same
# type for a single RPC.
rpc_allow_same_request_response: false
# rpc_allow_google_protobuf_empty_requests affects the behavior of the
# RPC_REQUEST_STANDARD_NAME and RPC_REQUEST_RESPONSE_UNIQUE rules.
#
# 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: false
# rpc_allow_google_protobuf_empty_responses affects the behavior of the
# RPC_RESPONSE_STANDARD_NAME and the RPC_REQUEST_RESPONSE_UNIQUE rules.
#
# 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: false
# service_suffix affects the behavior of the SERVICE_SUFFIX rule.
#
# This will result in this suffix being used instead of the default "Service"
# suffix.
service_suffix: Service
# 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 individual 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: false
# breaking contains the options for breaking rules.
breaking:
# use is the list of rule categories and ids to use for
# buf breaking.
#
# Categories are sets of rule ids.
# Run buf config ls-breaking-rules --all to get a list of all rules.
#
# 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 rule ids or categories to remove from the use
# list.
#
# This allows removal of specific rules from the union of rules derived
# from the use list of categories and ids.
#
# As opposed to lint, we generally recommend using one of the preconfigured
# options. Removing specific rules from breaking change detection is an
# advanced option.
except:
- FIELD_SAME_NAME
# ignore is the list of directories or files to ignore for all rules.
#
# 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 rule 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 rule. 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: false

Runtime cache directory#

buf caches files it downloads as part of module resolution in a folder on the local filesystem to avoid incurring the cost of downloading modules repeatedly. To choose where to cache the files it checks the following list in order:

  • The value of $BUF_CACHE_DIR, if set.
  • The value of $XDG_CACHE_HOME falling back to $HOME/.cache on Linux and Mac and %LocalAppData% for Windows.