We highly recommend completing the tour to get an overview of
To get started, add a
buf.yaml file to the root of your repository that contains
your Protobuf definitions.
This represents a
buf.yaml file that sets the defaults for the build and for the lint rules:
roots as necessary. This correlates to your
To run linting from the root of your repository:
- Discover all Protobuf files per your configuration.
- Copy the Protobuf files into memory.
- Compile all Protobuf files.
- Run the compilation result against the configured lint rules.
If there are errors, they will be printed out in a
file:line:column:message format by default.
For example, from the tour:
Output can also be printed as JSON. From the tour:
We can also output errors in a format you can then copy into your
buf.yaml file. This allows you
to ignore all existing lint errors and correct them over time. From the tour:
Buf can lint additional inputs instead of just your local Protobuf files. This is useful in a
variety of scenarios, including enabling
protoc output be used as
See the Input documentation for details on all available inputs.
By default, Buf builds all files under configuration per the
build config. You can instead
manually specify the file or directory paths to build and lint. This is an advanced feature intended to be used
for editor or Bazel integration - it is better to let Buf discover all files under management and
handle this for you in general.
Combine this with an in-line configuration override to make the only file I/O performed
by Buf being the reading of your specified
A lot of builds will have vendored Protobuf files that you want to ignore for linting. For example, you may build against googleapis for grpc-gateway. The following represents how to handle this situation:
Buf ships a Docker image bufbuild/buf that allows you to use Buf as part of your Docker workflow. For example: