buf.yaml v2 config file#

Thebuf.yaml file defines aworkspace, which represents a directory or directories of Protobuf files that you want to treat as a unit.The set consists of one or more packages—seeFiles and packages for more details about these relationships and how to structure your files.

Thebuf.yaml config file and field definitions below explain usage for each field.See thelint andbreaking change detection overviews for default configurations for those features.

The annotatedbuf.yaml file below assumes a directory structure like this:

workspace_root├── buf.yaml└── proto    ├── foo    │   └── foo.proto    └── bar        ├── a        │   └── d.proto        ├── b        │   ├── e.proto        │   └── f.proto        └── c            ├── g.proto            └── h.proto

version:v2# The v2 buf.yaml file specifies a local workspace, which consists of at least one module.# The buf.yaml file should be placed at the root directory of the workspace, which# should generally be the root of your source control repository.modules:# Each module entry defines a path, which must be relative to the directory where the# buf.yaml is located. You can also specify directories to exclude from a module.-path:proto/foo# Modules can also optionally specify their Buf Schema Registry module name, if it exists.name:buf.build/acme/foo# Subdirectories to exclude can be listed using relative paths. Paths are relative# to the buf.yaml file.-path:proto/barname:buf.build/acme/barexcludes:-proto/bar/a-proto/bar/b/c# A module can have its own lint and breaking configuration, which overrides the default# lint and breaking configuration in its entirety for that module. All values from the# default configuration are overridden and no rules are merged.lint:use:-STANDARDexcept:-IMPORT_USEDignore:-proto/bar/cignore_only:ENUM_ZERO_VALUE_SUFFIX:-proto/bar/a-proto/bar/b/f.proto# v1 configurations had an allow_comment_ignores option to opt-in to comment ignores.## In v2, we allow comment ignores by default, and allow opt-out from comment ignores# with the disallow_comment_ignores option.disallow_comment_ignores:falseenum_zero_value_suffix:_UNSPECIFIEDrpc_allow_same_request_response:falserpc_allow_google_protobuf_empty_requests:falserpc_allow_google_protobuf_empty_responses:falseservice_suffix:Servicedisable_builtin:false# Breaking configuration for this module only. Behaves the same as a module-level# lint configuration.breaking:use:-FILEexcept:-EXTENSION_MESSAGE_NO_DELETEignore_unstable_packages:truedisable_builtin:false# Multiple modules are allowed to have the same path, as long as they don't share '.proto' files.-path:proto/commonname:buf.build/acme/weatherincludes:-proto/common/weather-path:proto/commonname:buf.build/acme/locationincludes:-proto/common/locationexcludes:# Excludes and includes can be specified at the same time, but if they are, each directory# in excludes must be contained in a directory in includes.-proto/common/location/test-path:proto/commonname:buf.build/acme/otherexcludes:-proto/common/location-proto/common/weather# Dependencies shared by all modules in the workspace. Must be modules hosted in the Buf Schema Registry.# The resolution of these dependencies is stored in the buf.lock file.deps:-buf.build/acme/paymentapis# The latest accepted commit.-buf.build/acme/pkg:47b927cbb41c4fdea1292bafadb8976f# The '47b927cbb41c4fdea1292bafadb8976f' commit.-buf.build/googleapis/googleapis:v1beta1.1.0# The 'v1beta1.1.0' label.# The default lint configuration for any modules that don't have a specific lint configuration.## If this section isn't present, AND a module doesn't have a specific lint configuration, the default# lint configuration is used for the module.lint:use:-STANDARD-TIMESTAMP_SUFFIX# This rule comes from the plugin example below.# Default breaking configuration. It behaves the same as the default lint configuration.breaking:use:-FILE# Optional Buf plugins. Can use to require custom lint or breaking change rules specified in a locally# installed plugin. Each Buf plugin is listed separately, and can include options if the plugin allows# for them. If a rule has its `default` value set to true, the rule will be checked against even if# the 'lint' and 'breaking' fields aren't set.## See the example at https://github.com/bufbuild/bufplugin-go/blob/main/check/internal/example/cmd/buf-plugin-timestamp-suffix/main.go# for more detail about the sample below.plugins:-plugin:plugin-timestamp-suffix# Specifies the installed plugin to useoptions:# The TIMESTAMP_SUFFIX rule specified above allows the user to change the suffix by providing a# new value here.timestamp_suffix:_time

version#

Required. Defines the current configuration version.The only accepted values arev2,v1, orv1beta1.To use the configuration as specified below, it must be set tov2.See thebuf.yaml specifications forv1 orv1beta1 configurations if you haven't yet migrated tov2.

modules#

Required. Defines the list of modules that are built together in this workspace.Any dependencies that the fileshave on each other are automatically taken into account when building and shouldn't be declared in thedeps section.

path#

Required. The path to a directory containing Protobuf files, which must be defined relative to the workspace root(the directory that contains thebuf.yaml file).Allpath values must point to directories within the workspace.

name#

Optional. A Buf Schema Registry (BSR) path that uniquely identifies this directory.Thenamemust be a validmodule name and it defines the BSR repository that contains thecommit and label history and generated artifacts for the Protobuf files in the directory.

includes#

Optional. Lists directories within this directory to include in Protobuf file discovery.Only directories added to this list are included in Buf operations.

excludes#

Optional. Lists directories within this directory to exclude from Protobuf file discovery.Any directories added to this list are completely skipped and excluded from Buf operations.This can be specified together withincludes, in which case each directory inexcludes must be contained in a directory inincludes.

We don't recommend using this option, but in some situations it's unavoidable.

deps#

Optional. Declares one or more modules that your workspace depends on.Dependencies are shared between all modules in the workspace.Buf tooling already accounts for dependencies between the modules that are part of the set, so they shouldn't be declared here.

The value must be a valid path to a BSR module (either the public BSR atbuf.build or a private BSR instance).It can't be a local Git reference to abuf.yaml file or a URL path to a Git repo.This means that if you have a module you want to use as a dependency, it must also be pushed to the BSR.

The path can also include a specific reference, which is either acommit or a label.

Depending on specific module references is an advanced feature—you should depend on the latest commit whenever possible.Yourdeps don't need to include the:<reference> suffix in most cases.

lint#

Optional. The lint settings you specify in this section are the default for all modules in the workspace, but can be replaced for individual modules by specifying different settings at the module level.Module-level settings have all of the same fields and behavior as workspace-level settings.If no lint settings are specified for the workspace, it uses thedefault settings.

use#

Optional. Lists the categories and/or specific rules to use.For example, this config selects theBASIC lint category and theFILE_LOWER_SNAKE_CASE rule:

version:v2lint:use:-BASIC-FILE_LOWER_SNAKE_CASE

TheSTANDARD category is used iflint is unset.

except#

Optional. Removes rules or categories from theuse list.For example, this config selects all lint rules in theSTANDARD lint category except forENUM_NO_ALLOW_ALIAS and the rules in theBASIC category:

version:v2lint:use:-STANDARDexcept:-ENUM_NO_ALLOW_ALIAS-BASIC

Note that sinceSTANDARD is the default value foruse, this is equivalent to the above:

version:v2lint:except:-ENUM_NO_ALLOW_ALIAS-BASIC

ignore#

Optional. Excludes specific directories or files from all lint rules.If a directory is ignored, then all files and subfolders of the directory are also ignored.The specified pathsmust be relative to thebuf.yaml file.For example,foo/bar.proto is ignored with this config:

version:v2lint:ignore:-foo/bar.proto

ignore_only#

Optional. Allows directories or files to be excluded from specific lint categories or rules.As withignore, the pathsmust be relative tobuf.yaml.For example, this config sets up specific ignores for theENUM_PASCAL_CASE rule and theBASIC category:

version:v2lint:ignore_only:ENUM_PASCAL_CASE:-foo/foo.proto-barBASIC:-foo

disallow_comment_ignores#

Optional. Default isfalse if unset, meaning that you can ignore lint rules for specific components in your Protobuf files by adding a comment to them:

syntax="proto3";// Skip these rules for this package name. Changing name creates a breaking change.// buf:lint:ignore PACKAGE_LOWER_SNAKE_CASEpackageA;// buf:lint:ignore PACKAGE_VERSION_SUFFIX

If this option is unset, the linter ignores the specified rule for any comment that starts with// buf:lint:ignore RULE_ID.

If this option is set totrue, any such comments are ignored.See thelint overview to learn how and when to use comment ignores.

Inv1 configurations, this key was calledallow_comment_ignores and defaulted tofalse.The default behavior inv2 configurations is to allow comment ignores.

enum_zero_value_suffix#

Optional. Controls the behavior of theENUM_ZERO_VALUE_SUFFIX lint rule.By default, this rule verifies that the zero value of all enums ends in_UNSPECIFIED, as recommended by theGoogle Protobuf Style Guide.However, organizations can choose a different preferred suffix—for example,_NONE.To set it, provide the desired value:

version:v2lint:enum_zero_value_suffix:_NONE

That config allows this:

enumFoo{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.

rpc_allow_google_protobuf_empty_requests#

Optional. Allows RPC requests to begoogle.protobuf.Emptymessages.You can set this if you want to allow messages to be void forever and never take any parameters.We don't recommend using this option.

rpc_allow_google_protobuf_empty_responses#

Optional. Allows RPC responses to begoogle.protobuf.Emptymessages.You can set this if you want to allow messages to never return any parameters.We don't recommend using this option.

service_suffix#

Optional. Controls the behavior of theSERVICE_SUFFIX lint rule.By default, this rule verifies that all service names are suffixed withService.However, organizations can choose a different preferred suffix—for example,API.To set that:

version:v2lint:service_suffix:API

That config allows this:

serviceFooAPI{}

disable_builtin#

Optional. Default isfalse if unset. If this option is set totrue, Buf's built-in lint rules are disabled.

breaking#

Optional. Specifies thebreaking change detection rules enforced on the Protobuf files inthe directory.

use#

Optional. Lists the rules or categories to use for breaking change detection.For example, this config selects theWIRE category and theFILE_NO_DELETE rule:

version:v2breaking:use:-WIRE-FILE_NO_DELETE

TheFILE category is used ifbreaking is unset, which is conservative and appropriate for most teams.

except#

Optional. Removes rules or categories from theuse list.For example, this config results in all breaking rules in theFILE category being used except forFILE_NO_DELETE:

version:v2breaking:use:-FILEexcept:-FILE_NO_DELETE

We don't recommend using this option.

ignore#

Optional. Excludes specific directories or files from all breaking change detection rules.If a directory is ignored, then all files and subfolders of the directory are also ignored.The specified pathsmust be relative to thebuf.yaml file.For example,foo/bar.proto is ignored with this config:

version:v2breaking: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.For example:

version:v2breaking:use:-FILEignore:-foo/bar/v1beta1-foo/bar/v1beta2-foo/baz/v1alpha1

If you want to ignore all alpha, beta, or test packages, we recommend using theignore_unstable_packages setting instead.

ignore_only#

Optional. Allows directories or files to be excluded from specific breaking change detection categories or rules.As withignore, the pathsmust be relative tobuf.yaml.For example, this config sets us specific ignores for theFILE_SAME_TYPE rule and theWIRE category:

version:v2breaking:ignore_only:FILE_SAME_TYPE:-foo/foo.proto-barWIRE:-foo

We don't recommend this option.

ignore_unstable_packages#

Optional. Ignores packages with a last component that's one of the unstable forms recognized by the Buf checker'sPACKAGE_VERSION_SUFFIX rule:

• 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

disable_builtin#

Optional. Default isfalse if unset. If this option is set totrue, Buf's built-in breaking rules are disabled.

plugins#

Optional. SpecifiesBuf plugins for applying custom lint or breaking change rules and categories, either in place of or in addition to Buf's.This field lists the plugins to use and their options, and you then specify their rules and categories in thelint and/orbreaking sections where you want them to be checked.

plugin#

Required. A string that points to a Buf plugin binary on your${PATH}, its relative or absolute location on disk, or aremote BSR plugin path.Alternatively, you can specify a list of strings, with the remaining strings being arguments passed to the plugin binary.

options#

A list of option definitions if the plugin allows for them.These are key-value pairs, and are usually used to overwrite a default value (for example, a field suffix), and then run the check against the new value instead.See thetimestamp example in thebufplugin-go repo for more detail.