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:

$ buf --help
$ buf build --help
$ buf generate --help
$ buf breaking --help
$ buf lint --help
$ buf config ls-breaking-rules --help
$ buf config ls-lint-rules --help
$ buf ls-files --help
$ buf protoc --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.

$ GOOGLEAPIS_COMMIT="d4aa417ed2bba89c2d216900282bddfdafef6128"
$ git clone https://github.com/googleapis/googleapis
$ cd googleapis
$ git reset --hard "${GOOGLEAPIS_COMMIT}"

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:

# Below is not the lint and breaking configuration we recommend!
# This just just what googleapis passes.
# For lint, we recommend having the single value "DEFAULT" in "use"
# with no values in "except".
# For breaking, we recommend having the single value "FILE" in use.
# See https://docs.buf.build/lint-usage
# See https://docs.buf.build/breaking-usage
version: v1beta1
build:
  roots:
    - .
lint:
  use:
    - BASIC
    - FILE_LOWER_SNAKE_CASE
  except:
    - ENUM_NO_ALLOW_ALIAS
    - IMPORT_NO_PUBLIC
    - PACKAGE_AFFINITY
    - PACKAGE_DIRECTORY_MATCH
    - PACKAGE_SAME_DIRECTORY
breaking:
  use:
    - WIRE_JSON

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.

$ buf build

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:

$ buf build --exclude-source-info -o -#format=json | jq . | head
{
  "file": [
    {
      "name": "google/type/date.proto",
      "package": "google.type",
      "messageType": [
        {
          "name": "Date",
          "field": [
            {