Buf uses a self-contained compiler that is verified to produce
exactly equivalent output to
protoc. This compiler has a number of advantages over
protoc separately, and is tested against thousands of Protobuf definitions
including Protobuf grammar edge cases that almost all users will never hit. However,
we don't expect you to take our word for it - we wouldn't trust that statement ourselves
without our own verification.
Buf is able to use a variety of Inputs, one of which is binary Images. Since Images
are FileDescriptorSets (and vice versa), Buf is able to use output from
protoc as input.
Let's return to our lint example. Comment out the
exceptions from your
Run the following:
Note we added 2>/dev/null to suppress the unused import warnings. In general, you should not do this, as both warnings and build errors are printed to stderr from protoc, and there is no way to suppress warnings. We recommend doing this in two steps instead - first, create a .bin file, then, use this .bin file as the input for buf lint.
This is the equivalent of our
buf lint example earlier in the tour. What this does:
protocto build a FileDescriptorSet with SourceCodeInfo for all Protobuf files in the repository.
- Outputs this FileDescriptorSet to stdout.
- Uses this FileDescriptorSet as a binary Image file inputted on stdin for
Note we had to include SourceCodeInfo to have line and column references. If we do not, the following is outputted, and any comment checks will not work:
As per the Inputs documentation, Buf will still look for a
buf.yaml file in your current
directory. However, you can override this to be a different JSON or YAML file, or direct JSON or
The below avoids any file I/O by
buf other than reading the Image from stdin:
protoc to build is a perfectly fine way to use Buf, and may be preferable in situations
where you already are using
protoc as part of your build environment, such as for repositories
managed by Bazel. However, you do have the following disadvantages:
- Buf does additional checks to verify your Protobuf layout is sane, namely it does not allow overlapping proto_paths, and makes sure all file paths are unique relative to the proto paths. This is an extremely important check to perform in most scenarios.
- Buf utilizes all available cores to complete compilation, and will generally be much faster, although Protobuf compilation is generally very quick regardless. As a comparison on a system with four cores:
- Buf cannot compute relative or absolute paths for lint or breaking change output when Images
are used as input. For example, if you ran
buf lintwith different directory inputs, you get equivalent output paths, however if using Images, you always get the paths relative to the proto paths.