buf

module
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 7, 2022 License: Apache-2.0

README

The Buf logo

Buf

License Release CI Docker Homebrew AUR Slack

The buf CLI is a tool for working with Protocol Buffers.

Installation

Homebrew

You can install buf using Homebrew (macOS or Linux):

brew install bufbuild/buf/buf

This installs:

Other methods

For other installation methods, see our official documentation, which covers:

Usage

Buf's help interface provides summaries for commands and flags:

buf --help

For more comprehensive usage information, consult Buf's documentation, especially these guides:

CLI breaking change policy

We will never make breaking changes within a given major version of the CLI. Once buf reaches v1.0, you can expect no breaking changes until v2.0. But as we have no plans to ever release a v2.0, we will likely never break the buf CLI.

This breaking change policy does not apply to commands behind the buf beta gate, and you should expect breaking changes to commands like buf beta registry. The policy does go into effect, however, when those commands or flags are elevated out of beta.

Our goals for Protobuf

Buf's goal is to replace the current paradigm of API development, centered around REST/JSON, with a schema-driven paradigm. Defining APIs using an IDL provides numerous benefits over REST/JSON, and Protobuf is by far the most stable and widely adopted IDL in the industry. We've chosen to build on this widely trusted foundation rather than creating a new IDL from scratch.

But despite its technical merits, actually using Protobuf has long been more challenging than it needs to be. The Buf CLI and the BSR are the cornerstones of our effort to change that for good and to make Protobuf reliable and easy to use for service owners and clients alike—in other words, to create a modern Protobuf ecosystem.

While we intend to incrementally improve on the buf CLI and the BSR, we're confident that the basic groundwork for such an ecosystem is already in place.

The Buf Schema Registry

The Buf Schema Registry (BSR) is a SaaS platform for managing your Protobuf APIs. It provides a centralized registry and a single source of truth for all of your Protobuf assets, including not just your .proto files but also remote plugins. Although the BSR provides an intuitive browser UI, buf enables you to perform most BSR-related tasks from the command line, such as pushing Protobuf sources to the registry and managing users and repositories. The BSR is currently in beta.

The BSR is not required to use buf. We've made the core features of the buf CLI available to all Protobuf users.

More advanced CLI features

While buf's core features should cover most use cases, we've included some more advanced features to cover edge cases:

  • Automatic file discovery. Buf walks your file tree and builds your .proto files in accordance with your supplied build configuration, which means that you no longer need to manually specify --proto_paths. You can still, however, specify .proto files manually through CLI flags in cases where file discovery needs to be disabled.
  • Fine-grained rule configuration for linting and breaking changes. While we do have recommended defaults, you can always select the exact set of rules that your use case requires, with 40 lint rules and 53 breaking change rules available.
  • Configurable error formats for CLI output. buf outputs information in file:line:column:message form by default for each lint error and breaking change it encounters, but you can also select JSON and, in the near future, JUnit output.
  • Editor integration driven by buf's granular error output. We currently provide linting integrations for both Vim and Visual Studio Code but we plan to support other editors, such as Emacs and JetBrains IDEs like IntelliJ and GoLand, in the future.
  • Universal Input targeting. Buf enables you to perform actions like linting and breaking change detection not just against local .proto files but also against a broad range of other Inputs, such as tarballs and ZIP files, remote Git repositories, and pre-built image files.
  • Speed. Buf's internal Protobuf compiler compiles your Protobuf sources using all available cores without compromising deterministic output, which is considerably faster than protoc. This allows for near-instantaneous feedback, which is of special importance for features like editor integration.

Next steps

Once you've installed buf, we recommend completing the Tour of Buf, which provides a broad but hands-on overview of the core functionality of both the CLI and the BSR. The tour takes about 10 minutes to complete.

After completing the tour, check out the remainder of the docs for your specific areas of interest and our roadmap to see what we have in store for the future.

Community

For help and discussion around Protobuf, best practices, and more, join us on Slack.

For updates on the Buf CLI, follow this repo on GitHub.

For feature requests, bugs, or technical questions, email us at dev@buf.build. For general inquiries or inclusion in our upcoming feature betas, email us at info@buf.build.

Directories

Path Synopsis
cmd
buf
private
buf/bufgen
Package bufgen does configuration-based generation.
Package bufgen does configuration-based generation.
buf/bufmigrate
Package bufmigrate contains logic for migrating between different configuration file versions.
Package bufmigrate contains logic for migrating between different configuration file versions.
buf/bufwire
Package bufwire wires everything together.
Package bufwire wires everything together.
buf/bufwork
Package bufwork defines the primitives used to enable workspaces.
Package bufwork defines the primitives used to enable workspaces.
buf/cmd/buf/workspacetests/other/proto/workspacetest
Package workspacetest is used to test if workspaces work when buf is executed in a sub-directory specified in the workspace.
Package workspacetest is used to test if workspaces work when buf is executed in a sub-directory specified in the workspace.
bufpkg/bufapimodule
Package bufapimodule provides bufmodule types based on bufapi types.
Package bufapimodule provides bufmodule types based on bufapi types.
bufpkg/bufcheck
Package bufcheck contains the implementations of the lint and breaking change detection rules.
Package bufcheck contains the implementations of the lint and breaking change detection rules.
bufpkg/bufcheck/bufbreaking
Package bufbreaking contains the breaking change detection functionality.
Package bufbreaking contains the breaking change detection functionality.
bufpkg/bufcheck/bufbreaking/internal/bufbreakingbuild
Package bufbreakingbuild contains the RuleBuilders used by bufbreakingv*.
Package bufbreakingbuild contains the RuleBuilders used by bufbreakingv*.
bufpkg/bufcheck/bufbreaking/internal/bufbreakingcheck
Package bufbreakingcheck impelements the check functions.
Package bufbreakingcheck impelements the check functions.
bufpkg/bufcheck/bufbreaking/internal/bufbreakingv1
Package bufbreakingv1 contains the VersionSpec for v1.
Package bufbreakingv1 contains the VersionSpec for v1.
bufpkg/bufcheck/bufbreaking/internal/bufbreakingv1beta1
Package bufbreakingv1beta1 contains the VersionSpec for v1beta1.
Package bufbreakingv1beta1 contains the VersionSpec for v1beta1.
bufpkg/bufcheck/buflint
Package buflint contains the linting functionality.
Package buflint contains the linting functionality.
bufpkg/bufcheck/buflint/internal/buflintbuild
Package buflintbuild contains the RuleBuilders used by buflintv*.
Package buflintbuild contains the RuleBuilders used by buflintv*.
bufpkg/bufcheck/buflint/internal/buflintcheck
Package buflintcheck impelements the check functions.
Package buflintcheck impelements the check functions.
bufpkg/bufcheck/buflint/internal/buflintv1
Package buflintv1 contains the VersionSpec for v1.
Package buflintv1 contains the VersionSpec for v1.
bufpkg/bufcheck/buflint/internal/buflintv1beta1
Package buflintv1beta1 contains the VersionSpec for v1beta1.
Package buflintv1beta1 contains the VersionSpec for v1beta1.
bufpkg/bufconfig
Package bufconfig contains the configuration functionality.
Package bufconfig contains the configuration functionality.
bufpkg/bufconnect
Package bufconnect provides buf-specific Connect functionality.
Package bufconnect provides buf-specific Connect functionality.
bufpkg/buflock
Package buflock manages the buf.lock lock file.
Package buflock manages the buf.lock lock file.
bufpkg/bufplugin/bufpluginconfig
Package bufpluginconfig defines the buf.plugin.yaml file.
Package bufpluginconfig defines the buf.plugin.yaml file.
bufpkg/bufplugin/bufplugindocker
Package bufplugindocker contains utilities for building Buf plugins using the Docker API.
Package bufplugindocker contains utilities for building Buf plugins using the Docker API.
bufpkg/bufstyle
Package bufstyle defines lint analyzers that help enforce Buf's Go code standards.
Package bufstyle defines lint analyzers that help enforce Buf's Go code standards.
pkg/app
Package app provides application primitives.
Package app provides application primitives.
pkg/app/appcmd
Package appcmd contains helper functionality for applications using commands.
Package appcmd contains helper functionality for applications using commands.
pkg/app/appflag
Package appflag contains functionality to work with flags.
Package appflag contains functionality to work with flags.
pkg/app/applog
Package applog contains utilities to work with logging.
Package applog contains utilities to work with logging.
pkg/app/appname
Package appname provides containers for named applications.
Package appname provides containers for named applications.
pkg/app/appproto
Package appproto contains helper functionality for protoc plugins.
Package appproto contains helper functionality for protoc plugins.
pkg/app/appproto/appprotoexec
Package appprotoexec provides protoc plugin handling and execution.
Package appprotoexec provides protoc plugin handling and execution.
pkg/app/appproto/appprotoos
Package appprotoos does OS-specific generation.
Package appprotoos does OS-specific generation.
pkg/diff
Package diff implements diffing.
Package diff implements diffing.
pkg/encoding
Package encoding provides encoding utilities.
Package encoding provides encoding utilities.
pkg/filepathextended
Package filepathextended provides filepath utilities.
Package filepathextended provides filepath utilities.
pkg/git/cmd/git-ls-files-unstaged
Package main implements a file lister for git that lists unstaged files.
Package main implements a file lister for git that lists unstaged files.
pkg/github/githubtesting
Package githubtesting provides testing functionality for GitHub.
Package githubtesting provides testing functionality for GitHub.
pkg/ioextended
Package ioextended provides io utilities.
Package ioextended provides io utilities.
pkg/licenseheader
Package licenseheader handles license headers.
Package licenseheader handles license headers.
pkg/netrc
Package netrc contains functionality to work with netrc.
Package netrc contains functionality to work with netrc.
pkg/normalpath
Package normalpath provides functions similar to filepath.
Package normalpath provides functions similar to filepath.
pkg/osextended
Package osextended provides os utilities.
Package osextended provides os utilities.
pkg/protogenutil
Package protogenutil provides support for protoc plugin development with the appproto and protogen packages.
Package protogenutil provides support for protoc plugin development with the appproto and protogen packages.
pkg/protosource
Package protosource defines minimal interfaces for Protobuf descriptor types.
Package protosource defines minimal interfaces for Protobuf descriptor types.
pkg/storage
Package storage implements a simple storage abstraction.
Package storage implements a simple storage abstraction.
pkg/storage/cmd/ddiff
Package main implements the ddiff command that diffs two directories.
Package main implements the ddiff command that diffs two directories.
pkg/storage/storagearchive
Package storagearchive implements archive utilities.
Package storagearchive implements archive utilities.
pkg/storage/storagemem
Package storagemem implements an in-memory storage Bucket.
Package storagemem implements an in-memory storage Bucket.
pkg/storage/storagemem/internal
Package internal splits out ImmutableObject into a separate package from storagemem to make it impossible to modify ImmutableObject via direct field access.
Package internal splits out ImmutableObject into a separate package from storagemem to make it impossible to modify ImmutableObject via direct field access.
pkg/storage/storageos
Package storageos implements an os-backed storage Bucket.
Package storageos implements an os-backed storage Bucket.
pkg/storage/storagetesting
Package storagetesting implements testing utilities and integration tests for storage.
Package storagetesting implements testing utilities and integration tests for storage.
pkg/storage/storageutil
Package storageutil provides helpers for storage implementations.
Package storageutil provides helpers for storage implementations.
pkg/stringutil
Package stringutil implements string utilities.
Package stringutil implements string utilities.
pkg/tmp
Package tmp provides temporary files and directories.
Package tmp provides temporary files and directories.
pkg/zaputil
Package zaputil implements utilities for zap.
Package zaputil implements utilities for zap.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL