buf.yaml
The buf.yaml
file defines a module, and is
placed at the root of the Protobuf source files it defines. The placement of the
buf.yaml
configuration tells buf
where to search for .proto
files, and how
to handle imports.
This file contains lint and breaking change detection rules, and if applicable, the name of your module and a list of dependencies.
#
Default valuesThe buf.yaml
config file below demonstrates all default values being explicitly
set, this file is the equivalent of no options being set in your buf.yaml
at
all.
version: v1name: ""deps: []build: excludes: []breaking: use: - FILElint: 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
#
Fieldsversion
#
The version
key is required, and defines the current configuration
version. The only accepted values are v1beta1
and v1
.
name
#
The name
is optional, and uniquely identifies your module. The name
must be a valid module name and is
directly associated with the repository that owns it.
deps
#
The deps
key is optional, and declares one or more modules that your
module depends on. Each deps
entry must be a module reference, and, is
directly associated with a repository, as well as a
reference, which is either a tag
or commit. A complete example of the different deps
format is shown below:
version: v1name: buf.build/acme/petapisdeps: - buf.build/acme/paymentapis # The latest commit. - buf.build/acme/pkg:47b927cbb41c4fdea1292bafadb8976f # The '47b927cbb41c4fdea1292bafadb8976f' commit. - buf.build/googleapis/googleapis:v1beta1.1.0 # The 'v1beta1.1.0' tag.
Depending on specific references is an advanced feature; you should depend on the latest commit whenever possible. In other words, your
deps
don't need to include the:<reference>
suffix in most cases. Seebuf
's best practices to learn more!
build
#
The build
key is optional, and is used to control how buf
builds
modules. The build
section only has one option:
excludes
#
The excludes
key is optional, and lists directories to ignore from
.proto
file discovery. Any directories added to this list are completely
skipped and excluded in the module. We do not recommend using this option in
general, however in some situations it is unavoidable.
lint
#
The lint
key is optional, and specifies the lint rules
enforced on the files in the module.
use
#
The use
key is optional, and lists the IDs or categories to use for
linting. For example, this config selects the BASIC
lint category as well as
the FILE_LOWER_SNAKE_CASE
ID:
version: v1lint: use: - BASIC - FILE_LOWER_SNAKE_CASE
The default use
value is the single item, DEFAULT
.
except
#
The except
key is optional, and removes IDs or categories from the use
list. For example, this config results in all lint rules in the DEFAULT
lint
category being used except for ENUM_NO_ALLOW_ALIAS
and all lint rules in the
BASIC
category:
version: v1lint: use: - DEFAULT except: - ENUM_NO_ALLOW_ALIAS - BASIC
Note that since DEFAULT
is the default value for use
, this is equivalent to
the above:
version: v1lint: except: - ENUM_NO_ALLOW_ALIAS - BASIC
ignore
#
The ignore
key is optional, and allows directories or files to be excluded
from all lint rules when running buf lint
. If a directory is ignored,
then all files and subfolders of the directory will also be ignored. The specified
directory or file paths must be relative to the buf.yaml
. For example, the
lint result in foo/bar.proto
is ignored with this config:
version: v1lint: ignore: - foo/bar.proto
ignore_only
#
The ignore_only
key is optional, and allows directories or files to be
excluded from specific lint rules when running buf lint
by taking a map from
lint rule ID or category to path. As with ignore
, the paths must be
relative to the buf.yaml
.
For example, this config sets up specific ignores for the ID ENUM_PASCAL_CASE
and the category BASIC
:
version: v1lint: ignore_only: ENUM_PASCAL_CASE: - foo/foo.proto - bar BASIC: - foo
allow_comment_ignores
#
The allow_comment_ignores
key is optional, and turns on comment-driven
ignores. We do not recommend using this option in general, however in some
situations it is unavoidable.
version: v1lint: allow_comment_ignores: true
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
ignores lint errors for this ID.
For example:
syntax = "proto3";
// buf:lint:ignore PACKAGE_LOWER_SNAKE_CASE// buf:lint:ignore PACKAGE_VERSION_SUFFIXpackage A;
enum_zero_value_suffix
#
The enum_zero_value_suffix
key is optional, and controls the behavior of
the ENUM_ZERO_VALUE_SUFFIX
lint rule. By default, this rule verifies that the
zero value of all enums ends in _UNSPECIFIED
, as recommended by the
Google Protobuf Style Guide.
But organizations may have a different preferred suffix, for example _NONE
. To
set that:
version: v1lint: enum_zero_value_suffix: _NONE
That config allows this:
enum Foo { FOO_NONE = 0;}
rpc_allow_same_request_response
#
The rpc_allow_same_request_response
key is optional, and allows the same
message type to be used for a single RPC's request and response type. We do
not recommend using this option in general.
rpc_allow_google_protobuf_empty_requests
#
The rpc_allow_google_protobuf_empty_requests
key is optional, and allows
RPC requests to be
google.protobuf.Empty
messages. This can be set if you want to allow messages to be void forever, that
is, to never take any parameters. We do not recommend using this option in
general.
rpc_allow_google_protobuf_empty_responses
#
The rpc_allow_google_protobuf_empty_responses
key is optional, and allows
RPC responses to be
google.protobuf.Empty
messages. This can be set if you want to allow messages to never return any
parameters. We do not recommend using this option in general.
service_suffix
#
The service_suffix
key is optional, and controls the behavior of the
SERVICE_SUFFIX
lint rule. By default, this rule verifies that all service
names are suffixed with Service
. But organizations may have a different
preferred suffix, for example API
. To set that:
version: v1lint: service_suffix: API
That config allows this:
service FooAPI {}
breaking
#
The breaking
key is optional, and specifies the breaking change detection
rules enforced on the files contained within the module.
use
#
The use
key is optional, and lists the IDs or categories to use for
breaking change detection. For example, this config selects the WIRE
breaking
category, as well as the FILE_NO_DELETE
ID:
version: v1breaking: use: - WIRE - FILE_NO_DELETE
The default value is the single item FILE
, which is what we recommend.
except
#
The except
key is optional, and removes IDs or categories from the use
list. We do not recommend using this option in general. For example, this
config results in all breaking rules in the FILE
breaking category being used
except for FILE_NO_DELETE
:
version: v1breaking: use: - FILE except: - FILE_NO_DELETE
ignore
#
The ignore
key is optional, and allows directories or files to be excluded
from all breaking rules when running buf breaking
. If a directory is ignored,
then all files and subfolders of the directory will also be ignored. The specified
directory or file paths must be relative to the buf.yaml
. For example, the
breaking result in foo/bar.proto
is ignored with this config:
version: v1breaking: ignore: - foo/bar.proto
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: v1breaking: use: - FILE ignore: - foo/bar/v1beta1 - foo/bar/v1beta2 - foo/baz/v1alpha1
ignore_only
#
The ignore_only
key is optional, and allows directories or files to be
excluded from specific breaking rules when running buf breaking
by taking a
map from breaking rule ID or category to path. As with ignore
, the paths
must be relative to the buf.yaml
. We do not recommend this option in
general.
For example, this config sets us specific ignores for the ID FILE_SAME_TYPE
and the category WIRE
:
version: v1breaking: ignore_only: FILE_SAME_TYPE: - foo/foo.proto - bar WIRE: - foo
ignore_unstable_packages
#
The ignore_unstable_packages
key is optional, and ignores 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, these packages are ignored:
foo.bar.v1alpha1
foo.bar.v1beta1
foo.bar.v1test
#
ReferenceIf you prefer, you can create a new buf.yaml
with the reference material
described here commented in-line with the buf mod init --doc
command. Give it
a try!