Setup
This tour assumes you have installed the buf
binary on your $PATH
.
At any time, you can see the help for a command using --help
:
We will use googleapis to explore
what 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.
Clone googleapis
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
having a buf.yaml
file at the root of your repository, and running commands from this
context.
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: