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 following buf.yaml file demonstrates all default values being explicitly set, this file is the equivalent of no options being set in your buf.yaml at all.

buf.yaml

version: v1# name and deps default to empty#name:#deps: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: Servicebreaking:  use:    - FILE

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:

buf.yaml

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 will not need to include the :<reference> suffix in most cases. Please refer to buf'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 will be 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 contained within the module.

`use`#

The use key is optional, and lists the IDs or categories to use for linting. For example, the following selects the BASIC lint category, as well as the FILE_LOWER_SNAKE_CASE ID:

buf.yaml

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, the following will result 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:

buf.yaml

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:

buf.yaml

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. The specified directory or file paths must be relative to the buf.yaml. For example, the lint result in foo/bar.proto will be ignored with the following:

buf.yaml

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, the following sets up specific ignores for the ID ENUM_PASCAL_CASE and the category BASIC:

buf.yaml

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.

buf.yaml

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 will ignore 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. However, organizations may have a different preferred suffix, for example _NONE, and this allows this to be set like so:

buf.yaml

version: v1lint:  enum_zero_value_suffix: _NONE

This will allow the following:

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 they will 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. However, organizations may have a different preferred suffix, for example API, and this allows this to be set like so:

buf.yaml

version: v1lint:  service_suffix: API

This will allow the following:

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, the following selects the WIRE breaking category, as well as the FILE_NO_DELETE ID:

buf.yaml

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, the following will result in all breaking rules in the FILE breaking category being used except for FILE_NO_DELETE:

buf.yaml

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. The specified directory or file paths must be relative to the buf.yaml. For example, the breaking result in foo/bar.proto will be ignored with the following:

buf.yaml

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:

buf.yaml

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, the following sets us specific ignores for the ID FILE_SAME_TYPE and the category WIRE:

buf.yaml

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, the following packages will be 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 config init --doc command. Give it a try!

Default values#

Fields#

version#

name#

deps#

build#

excludes#

lint#

use#

except#

ignore#

ignore_only#

allow_comment_ignores#

enum_zero_value_suffix#

rpc_allow_same_request_response#

rpc_allow_google_protobuf_empty_requests#

rpc_allow_google_protobuf_empty_responses#

service_suffix#

breaking#

use#

except#

ignore#

ignore_only#

ignore_unstable_packages#

Reference#

`version`#

`name`#

`deps`#

`build`#

`excludes`#

`lint`#

`use`#

`except`#

`ignore`#

`ignore_only`#

`allow_comment_ignores`#

`enum_zero_value_suffix`#

`rpc_allow_same_request_response`#

`rpc_allow_google_protobuf_empty_requests`#

`rpc_allow_google_protobuf_empty_responses`#

`service_suffix`#

`breaking`#

`use`#

`except`#

`ignore`#

`ignore_only`#

`ignore_unstable_packages`#