Usage

Buf provides stub generation capability using it's high-performance, internal compiler via buf generate.

buf generate uses a template file of the following shape:

# The version of the generation template.
# Required.
# The only currently-valid value is v1beta1.
version: v1beta1
# The plugins to run.
plugins:
# The name of the plugin.
# Required.
# By default, buf generate will look for a binary named protoc-gen-NAME on your $PATH.
- name: go
# The the relative output directory.
# Required.
out: gen/go
# Any options to provide to the plugin.
# Optional.
opt: paths=source_relative
# The custom path to the plugin binary, if not protoc-gen-NAME on your $PATH.
path: custom-gen-go # optional
- name java
out: gen/java

By default, buf generate will look for a file of this shape named buf.gen.yaml in your current directory. This can be thought of as a template for the set of plugins you want to invoke. Then, call with:

# uses buf.gen.yaml as template, current directory as input
$ buf generate
# same as the defaults
$ buf generate --input . --template buf.gen.yaml
# --template also takes YAML or JSON data as input, so it can be used without a file
$ buf generate --input . --template '{"version":"v1beta1","plugins":[{"name":"go","out":"gen/go"}]}'
# download the repository, compile it, and generate per the bar.yaml template
$ buf generate --input https://github.com/foo/bar.git --template bar.yaml
# generate to the bar/ directory, prepending bar/ to the out directives in the template
$ buf generate --input https://github.com/foo/bar.git --template bar.yaml -o bar

The paths in the template and the -o flag will be interpreted as relative to your current directory, so you can place your template files anywhere.

Plugins are invoked in the order they are specified in the template, but each plugin has a per-directory parallel invocation, with results from each invocation combined before writing the result. This is equivalent behavior to buf protoc --by_dir.