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 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
Required. Defines the current configuration version. The only accepted values are v1beta1
and v1
.
name
Optional.. Uniquely identifies your module. The name
must be a valid
module name and is directly associated with the BSR repository that owns it.
deps
Optional. 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
Optional Used to control how the Buf CLI builds modules. The build
section only has one
option, excludes
.
excludes
Optional. Lists directories to ignore from .proto
file discovery. Any directories added
to this list are completely skipped and excluded in the module. We don't recommend using this option, but in some
situations it's unavoidable.
lint
Optional. Specifies the lint rules enforced on the files in the module.
use
Optional. Lists the rules or categories to use for linting. For example, this config selects the
BASIC
lint category as well as the FILE_LOWER_SNAKE_CASE
rule:
version: v1
lint:
use:
- BASIC
- FILE_LOWER_SNAKE_CASE
The default is the DEFAULT
category.
except
Optional. Removes rules 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 the 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
Optional. 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
file. For example, the lint result in
foo/bar.proto
is ignored with this config:
version: v1
lint:
ignore:
- foo/bar.proto
ignore_only
Optional. 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 ENUM_PASCAL_CASE
rule and the BASIC
category:
version: v1
lint:
ignore_only:
ENUM_PASCAL_CASE:
- foo/foo.proto
- bar
BASIC:
- foo
allow_comment_ignores
Optional. Turns on comment-driven ignores. If this option is set, you can add leading comments within Protobuf files to ignore lint errors for certain components.
version: v1
lint:
allow_comment_ignores: true
If any line in a leading comment starts with buf:lint:ignore <rule_id>
, then the Buf CLI ignores lint errors for that
rule. For example:
syntax = "proto3";
// buf:lint:ignore PACKAGE_LOWER_SNAKE_CASE
// buf:lint:ignore PACKAGE_VERSION_SUFFIX
package A;
We don't recommend using this option. In team settings, it's difficult to maintain consistency when individual
engineers can easily opt out of lint rules. By using an authors or owners file and keeping all lint ignores in
buf.yaml
, a small group of reviewers must approve each exception.
As an alternative, you could move the offending types to a separate .proto
file, use an authors or owners file to
control access to it, and set the corresponding ignore
or ignore_only
value to point to that file. This allows
buf.yaml
to have its own access group and stay focused on the organization's defaults.
enum_zero_value_suffix
Optional. 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. However, organizations
can choose 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
Optional. Allows the same message type to be used for a single RPC's request and response type. We don't recommend using this option in general.
rpc_allow_google_protobuf_empty_requests
Optional. Allows RPC requests to be google.protobuf.Empty messages. You can set this if you want to allow messages to be void forever—that is, to never take any parameters. We don't recommend using this option in general.
rpc_allow_google_protobuf_empty_responses
Optional. Allows RPC responses to be google.protobuf.Empty messages. You can set this if you want to allow messages to never return any parameters. We don't recommend using this option in general.
service_suffix
Optional. Controls the behavior of the SERVICE_SUFFIX
lint rule. By default, this
rule verifies that all service names are suffixed with Service
. However, organizations can choose a different preferred
suffix—for example, API
. To set that:
version: v1
lint:
service_suffix: API
That config allows this:
service FooAPI {}
breaking
Optional. Specifies the breaking change detection rules enforced on the files contained within the module.
use
Optional. Lists the IDs or categories to use for breaking change detection. For example, this
config selects the WIRE
category and the FILE_NO_DELETE
rule:
version: v1
breaking:
use:
- WIRE
- FILE_NO_DELETE
The default value is the FILE
category, which is conservative and appropriate for most teams.
except
Optional. Removes IDs or categories from the use
list. We don't 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
Optional. Allows directories or files to be excluded from all 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
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 don't recommend this option in general.
For example, this config sets us specific ignores for the FILE_SAME_TYPE
rule and the WIRE
category:
version: v1
breaking:
ignore_only:
FILE_SAME_TYPE:
- foo/foo.proto
- bar
WIRE:
- foo
ignore_unstable_packages
Optional. Ignores packages with a last component that's 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
You can create a new buf.yaml
that contains reference material commented inline by using the
buf mod init --doc
command. Give it a try!