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 values
The 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: v1
name: ""
deps: []
build:
excludes: []
lint:
use:
- DEFAULT
except: []
ignore: []
ignore_only: {}
allow_comment_ignores: false
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
except: []
ignore: []
ignore_only: {}
ignore_unstable_packages: false
Fields
version
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: v1
name: buf.build/acme/petapis
deps:
- 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.
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: v1
lint:
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: v1
lint:
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: v1
lint:
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: v1
lint:
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: v1
lint:
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: v1
lint:
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_SUFFIX
package 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: v1
lint:
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: v1
lint:
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: v1
breaking:
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: v1
breaking:
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: v1
breaking:
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: v1
breaking:
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: v1
breaking:
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
Reference
If 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!