Linting – Overview
Linting tools help to maintain the quality of code by enforcing a set of rules for style, syntax, and best practices. They can catch errors early, make the code easier to understand, and reduce the amount of manual code review required. The Buf CLI lints Protobuf files using a set of rules designed to encourage common conventions and maximize forward compatibility without restricting your organization's ability to adopt an in-house style guide.
This document provides an overview of Buf's Protobuf linting features.
We recommend completing the tour for an introduction to the
buf lint
command.
Key concepts
The Buf CLI's linter can check your schemas at two phases of development:
- During development: You can integrate with your editor for immediate feedback as
you're iterating, and also spot-check by running
buf lint
. - In code review: You can integrate with your CI/CD workflows (like GitHub Actions) to ensure that linting errors get flagged directly in your review flow without the need for constant human vigilance.
Rules and categories
The linter's rules are split up into categories, so choosing a strictness level is straightforward. We recommend using one of the predefined categories, but rules can also be selected individually to match more unusual policies. See the rules and categories page for detailed information.
The configuration categories, from strictest to most lenient, are:
STANDARD
(This category was previously calledDEFAULT
)BASIC
MINIMAL
Changes that pass linting under a stricter policy also pass with all less-strict policies. For example, passing the
STANDARD
rules means you will pass the MINIMAL
rules. There are also two top-level categories outside of the
strictness hierarchy that address comments and unary RPCs specifically.
Defaults and configuration
You configure lint rules in the buf.yaml
configuration file, which is placed at the root of the Protobuf
module it defines. If the input to buf lint
doesn't contain a buf.yaml
file, the Buf CLI operates as if there's a
buf.yaml
file with these values:
version: v2
lint:
use:
- STANDARD
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
Below is an example of each buf lint
configuration option. For more information on specific options and the rules
and categories, see the buf.yaml
reference and the rules and categories page.
version: v2
lint:
use:
- STANDARD
except:
- FILE_LOWER_SNAKE_CASE
ignore:
- bat
- ban/ban.proto
ignore_only:
ENUM_PASCAL_CASE:
- foo/foo.proto
- bar
BASIC:
- foo
disallow_comment_ignores: false # The default behavior of this key has changed from v1
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
Usage examples
The Buf CLI can lint inputs beyond your local Protobuf files, such as
Git repositories and tarballs. This can be useful in a variety of
scenarios, such as using protoc
output as Buf CLI input. Here are some example scripts:
$ protoc -I . --include_source_info $(find . -name '*.proto') -o /dev/stdout | buf lint -
$ buf lint 'https://github.com/googleapis/googleapis.git' --config buf.yaml
$ buf lint buf.build/acme/petapis
$ buf lint --error-format=json
For remote locations that require authentication, see HTTPS Authentication and SSH Authentication.
Limit to specific files
By default, the Buf CLI builds all files under your buf.yaml
configuration file,
but you can choose to lint only specific files or directories. This is an advanced feature that's mostly intended to be
used by other systems like editors. In general, it's better to let the Buf CLI discover all files and handle this for
you. If you do need this, however, you can use the --path
flag:
$ buf lint \
--path path/to/foo.proto \
--path path/to/bar.proto
You can also combine this with an inline configuration override:
$ buf lint \
--path path/to/foo.proto \
--path path/to/bar.proto \
--config '{"version":"v2","lint":{"use":["BASIC"]}}'
Ignoring rules with Protobuf comments
In rare cases, you may want to ignore a lint rule for a specific element of a Protobuf file (for example, when it's out of compliance but changing it is too risky due to downstream effects). You can override the linter on a per-line basis by adding a comment above the line you want it to ignore:
syntax = "proto3";
// buf:lint:ignore PACKAGE_LOWER_SNAKE_CASE
// buf:lint:ignore PACKAGE_VERSION_SUFFIX
package A;
This will work by default, but won't work if your buf.yaml
file has disallow_comment_ignores
set to true
. See the
buf.yaml
documentation for details.
Integration with CI/CD workflows
Because buf lint
is part of a CLI, you can easily integrate it into CI/CD workflows. For instructions, see the
General CI/CD setup and GitHub Actions pages.
Related docs
- Try out linting with the tutorial
- Get detailed explanations of the linting rules and categories
- Browse the buf.yaml configuration file reference and
buf lint
command reference - See more about the types of inputs that the Buf CLI accepts