Skip to content

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.

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.

The linter has a built-in set of rules and categories and can also accept rules and categories via Buf plugins. You can use them alongside or in place of Buf's defaults.

Rules and categories#

The linter's built-in rules are split up into categories to make choosing a strictness level straightforward, but rules can also be selected individually to more closely match your organization's policies. See the rules and categories page for detailed information.

The configuration categories, from strictest to most lenient, are:

  • STANDARD
  • 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 pass the MINIMAL rules. There are also two top-level categories outside of the strictness hierarchy that address comments and unary RPCs specifically.

Next steps#