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

As an example, here's a typical buf.gen.yaml for go and grpc, assuming protoc-gen-go and protoc-gen-go-grpc are on your $PATH:

version: v1beta1
plugins:
- name: go
out: gen/go
opt: paths=source_relative
- name: go-grpc
out: gen/go
opt: paths=source_relative,require_unimplemented_servers=false

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.

The first argument is the source, module, or image to generate from. If no argument is specified, defaults to ".".

Call with:

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

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.

If you only want to generate stubs for a subset of your input, you can do so via the --path flag:

# Only generate for the files in the directories proto/foo and proto/bar
$ buf generate --path proto/foo --path proto/bar
# Only generate for the files proto/foo/foo.proto and proto/foo/bar.proto
$ buf generate --path proto/foo/foo.proto --path proto/foo/bar.proto
# Only generate for the files in the directory proto/foo on your GitHub repository
$ buf generate --template buf.gen.yaml https://github.com/foo/bar.git --path proto/foo

Note that all paths must be contained within a root. For example, if you have the single root proto, you cannot specify --path proto, however --path proto/foo is allowed as proto/foo is contained within proto.

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.