Protobuf Tools

Buf is a tool for Protobuf files:

• Linter that enforces good API design choices and structure.

• Breaking change detector that enforces compatibility at the source code or wire level

• Configurable file builder that produces Images our extension of FileDescriptorSets

Prerequisites

# buf: proto tool https://buf.build/docs/tour-1
brew tap bufbuild/buf
brew install buf
# or use `go get` to install Buf
GO111MODULE=on go get github.com/bufbuild/buf/cmd/buf

Developer Workflow

Info

# To list all files Buf is configured to use:
buf ls-files
# To see your currently configured lint or breaking checkers:
buf check ls-lint-checkers
buf check ls-breaking-checkers
# To see all available lint checkers independent of configuration/defaults:
 buf check ls-lint-checkers --all

Build

# check
buf image build -o /dev/null
buf image build -o image.bin

Lint

buf check lint
# We can also output errors in a format you can then copy into your buf.yaml file
buf check lint --error-format=config-ignore-yaml
# Run breaking change detection
# for dev local
buf check breaking --against-input image.bin
buf check breaking --against-input '.git#branch=master'
# for CI
export HTTPS_GIT=https://github.com/xmlking/yeti.git
buf check breaking --against-input "$(HTTPS_GIT)#branch=master"

Format

make proto_format

Generate

Read gRPC on Node.js with Buf and TypeScript

make proto

Tools

grpcurl

# To use Buf-produced FileDescriptorSets with grpcurl on the fly:
grpcurl -protoset <(buf image build -o -) ...

ghz

# To use Buf-produced FileDescriptorSets with ghz on the fly:
ghz --protoset <(buf image build -o -) ...

Reference

1. Style Guide

2. Buf docs

3. Buf Example

4. Buf Schema Registry