This tour assumes you have installed the
buf binary on your
protoc plugin section assumes you have also installed the
protoc-gen-buf-check-lint binaries, and have a working installation of
At any time, you can see the help for a command using
We will use googleapis to explore
buf can do. Googleapis is a widely-used repository of Protobuf definitions
containing the interfaces for Google's public APIs that contains 2,311 files as
of the writing of this tour, and all Protobuf import paths are relative to the
root of the repository, making it a great example.
First we need to clone googleapis to use in this example. We recommend resetting
master to the commit
d4aa417ed2bba89c2d216900282bddfdafef6128 which we used
to develop this tour.
All further commands in this tour assume your current directory is the root of this clone of googleapis. All further commands will also assume that the GOOGLEAPIS_COMMIT variable is set.
Add a basic configuration file
Create a file
buf.yaml will the following content:
There is no need to add this via
git, it is fine just to have this file uncommitted.
In Buf's default input mode, it assumes there is a
buf.yaml in your current
directory, or uses the default values in lieu of a
buf.yaml file. We recommend always
buf.yaml file at the root of your repository, and running commands from this
We will refer to this file throughout the tour.
Verify that Buf can build the repository
Before continuing, let's verify everything is set up properly.
The above command should have exit code 0 and no output.
If you'd like to skip a few steps in the tour, you can also print out the resulting Image (a FileDescriptorSet with Buf-specific metadata) in JSON: