FAQ

Command and flag migrations

You may have recently gotten one of the following warnings:

Command "build" is deprecated, "image" sub-commands are now all implemented under the top-level "buf build" command, use "buf build" instead.
We recommend migrating, however this command continues to work.
See https://docs.buf.build/faq for more details.
Flag --input has been deprecated, input as the first argument instead.
We recommend migrating, however this flag continues to work.
See https://docs.buf.build/faq for more details.

As we work towards v1.0, we are cleaning up the CLI UX. As part of this, we made the following changes:

  • buf image build has been moved to buf build and now accepts images as inputs.
  • buf beta image convert has been deleted, as buf build now covers this functionality.
  • The -o flag is no longer required for buf build, instead defaulting to the OS equivalent of /dev/null.
  • The --source flag on buf build has been deprecated in favor of passing the input as the first argument.
  • The --source-config flag on buf build has been moved to --config.
  • The --input flag on buf check lint has been deprecated in favor of passing the input as the first argument.
  • The --input-config flag on buf check lint has been moved to --config.
  • The --input flag on buf check breaking has been deprecated in favor of passing the input as the first argument.
  • The --input-config flag on buf check breaking has been moved to --config.
  • The --against-input flag on buf check breaking has been moved to --against.
  • The --against-input-config flag on buf check breaking has been moved to --against-config.
  • The --input flag on buf generate has been deprecated in favor of passing the input as the first argument.
  • The --input-config flag on buf generate has been moved to --config.
  • The --input flag on buf ls-files has been deprecated in favor of passing the input as the first argument.
  • The --input-config flag on buf ls-files has been moved to --config.
  • The --file flag has been moved to --path and now also accepts directories as opposed to just files.

We feel these changes make using buf more natural. Examples:

# compile the files in the current directory
buf build
# equivalent to the default no-arg invocation
buf build .
# build the repository at https://github.com/foo/bar.git
buf build https://github.com/foo/bar.git
# lint the files in the proto directory
buf check lint proto
# check the files in the current directory against the files on the master branch for breaking changes
buf check breaking --against .git#branch=master
# check the files in the proto directory against the files in the proto directory on the master branch
buf check breaking proto --against .git#branch=master,subdir=proto

Note that existing commands and flags continue to work. While the deprecation messages will be printed, and we recommend migrating to the new invocations, your existing invocations have no change in functionality.

buf.yaml version

You may have recently gotten the following warning:

WARN File "buf.yaml" has no version set. Please add "version: v1beta1". See https://docs.buf.build/faq for more details.

We have added the concept of version to the configuration. For a given version, the following will not change:

  • Configuration file layout
  • Default configuration files
  • Lint and breaking checkers, and their associated categories.

Our goal at Buf is to never break users. You should be able to upgrade Buf, and expect the same results, forever. In this spirit, we want to make sure that upgrading Buf does not result in any configuration differences, and does not result in different lint or breaking change results.

We also need to be able to enhance the lint and breaking change functionality, and improve on the configuration shape as well. To accomplish this, while not breaking users who have come to rely on the existing shape and checkers, we have added this version. The only currently-available version is v1beta1.

The v1beta1 version will be supported forever. This will not be removed when we hit v1.0. Having a version set in your configuration is currently optional, however we will require having a version as of v1.0. This will be one of the only (if not the only) breaking changes between the beta and v1.0.

To prepare for this, and to remove this warning, just add a version to the top of your buf.yaml:

version: v1beta1

As a simple one-liner to do so, run the following:

$ cat <(echo version: v1beta1) buf.yaml > buf.yaml.tmp && mv buf.yaml.tmp buf.yaml

A version can (and should) also be added to the protoc plugin options. For example:

$ protoc -I . \
--buf-check-lint_out=. \
'--buf-check-lint_opt={"input_config":{"version":"v1beta1","lint":{"use":["ENUM_NO_ALLOW_ALIAS"]}}}' \
$(find . -name '*.proto')

We apologize for any inconvenience this warning may have caused.