buf.gen.yaml, buf.yaml, and buf.policy.yaml files.buf.gen.yaml files: “Run buf generate” and “Check for plugin updates”.lint.ignore and breaking.ignore paths in buf.yaml that do not match any file in the workspace.buf format error handling for edition 2024.descriptor.proto.buf lint to use the structured error API instead of parsing cel-go's text output.--debug-address flag to buf lsp serve to provide debug and profile support.buf.yaml deps, buf.gen.yaml remote plugins and input modules, buf.policy.yaml name and BSR plugins, and buf.lock dep names, making each a clickable link to its BSR page.buf.yaml files to update all dependencies (buf.dep.updateAll) or check for available updates (buf.dep.checkUpdates).buf flags with fixed value sets and file/directory arguments.buf curl URL path shell completions (service and method names) via server reflection, --schema, or the local buf module.buf format.buf generate --clean deleting files from nested plugin output directories.buf.build/docs links for lint rules from check plugins and policies.buf dep graph --format json silently dropping dependencies when a dependency was already seen.--rbs_out as a protoc_builtin plugin (requires protoc v34.0+).buf generate to preserve modification timesbuf beta registry plugin delete to prompt the user for deletion, matching the UX of the other deletion commands. Use --force to restore the old behavior.exclude_types in buf generate dropping transitive dependencies of import files retained for their extension fields.buf registry policy {commit,create,delete,info,label,settings} commands to manage BSR policies.import keyword.PROTOVALIDATE lint rule to support checking unenforceable required rules on repeated.items, map.keys and map.values.buf source edit deprecate command to deprecate types by setting the deprecate = true option.PROTOVALIDATE lint rule to support checking cel_expression fields for valid CEL.PROTOVALIDATE lint rule to support field mask rules.swift_prefix to remain unset when no override is provided in managed mode.swift_prefix to managed mode.textDocument/rename and textDocument/prepareRename support for buf lsp serve.buf beta registry plugin push.buf registry login in WSL2.--create flag for buf push to avoid errors on already existing modules if create is disallowed.textDocument/documentSymbol support for buf lsp serve.--timeout flag to 0, which results in no timeout by default.PROTOVALIDATE lint rule to allow for custom rules that do not have id or message fields.buf beta lsp to buf lsp serve. Command buf beta lsp is now deprecated.textDocument/References support for buf lsp serve.buf lsp serve.buf lsp serve.buf lsp serve.buf lsp serve.buf lsp serve.buf format to remove extraneous whitespace before the first header node (syntax/package declarations).PROTOVALIDATE lint rule to check IGNORE_IF_ZERO_VALUE on fields that track presence.buf format on fields with missing field number tags.include and exclude path handling for workspaces to avoid unnecessary file system operations. This change can result in a performance improvement for large workspaces. --http2-prior-knowledge flag set.gitlab-code-quality error format to print errors in the GitLab Code Quality format for buf lint and buf breaking.source_control_url to json outputs for buf registry {module, plugin} commit commands.buf export --all flag to include non-proto source files.buf lint will no longer warn about uses of (buf.validate.message).disabled, as it was removed in protovalidate v0.14.0. Please update to protovalidate v0.14.0 or higher, using the steps outlined in the protovalidate release notes.buf breaking --against-registry to work with new modules that have no commits on the default branch.buf beta stats to buf stats.buf registry sdk info command.buf breaking, ignoring new module(s).CSR category to breaking rules.protoc-gen-buf-breaking and protoc-gen-buf-lint.buf generate for empty files, files with no declared types.buf lint for predefined rules variables.buf config migrate to filter out removed rules.PROTOVALIDATE lint rule.exclude_type on a non imported package.--exclude-type flag for buf generate when an input is specified.buf lint and buf breaking output even when source code info is not available. This allows buf lint and buf breaking to respect ignore and ignore_only configurations when source code info is not available.buf convert to allow for zero length for binpb, txtpb, and yaml formats.--include-types for buf generate.--against-registry flag to buf breaking that runs breaking checks against the latest commit on the default branch of the corresponding module in the registry.buf generate.buf generate. Adds the ability to exclude types with the parameter exclude_types in buf.gen.yaml and a flag --exclude-types in the CLI. Type filters may now also be specified as plugin parameters in buf.gen.yaml.filter for use with git inputs. This sets the filter flag argument for the git fetch command.buf plugin push --label to allow pushing a plugin with a label.--digest-changes-only flag to buf registry {module,plugin} commit list to filter out commits that have no digest changes.buf plugin push --source-control-url to allow pushing a plugin with the source control url.buf registry plugin {create,delete,info,update} commands to manage BSR plugins.buf beta lsp.--type flag filter for buf build where import ordering is not deterministic.buf plugin push command to push a plugin to the Buf Schema Registry. Only WebAssembly check plugins are supported at this time.buf plugin update and buf plugin prune command to manage plugins in the buf.lock file. Only WebAssembly check plugins are supported at this time.buf registry plugin commit {add-label,info,list,resolve} to manage BSR plugin commits.buf registry plugin label {archive,info,list,unarchive} to manage BSR plugin commits.buf registry module update to buf registry module settings update. Command buf registry module update is now deprecated.buf lint and buf breaking commands.buf registry commit to buf registry module commit. Command buf registry commit is now deprecated.buf registry label to buf registry module label. Command buf registry label is now deprecated.buf registry whoami command, which checks if you are logged in to the Buf Schema Registry at a given domain.buf registry module info --format=json to add default_label_name, which provides the name of the default label of a module.PROTOVALIDATE lint rule to check example field options. Examples will be checked that they satisfy the field constraints, and are only present if constraints are present.PROTOVALIDATE lint rule to check predefined rules. Predefined rules will be checked that they compile..wasm file extension to specify a path to a Wasm plugin.buf beta lsp.buf dep graph --format flag that defaults to dot, and adds the option json, to print the dependency graph in JSON format.buf format where trailing comments on commas in message literals were not properly propagated to the formatted proto, empty message literals were not properly indented, and compound strings in options added an extra newline before trailing commas.buf curl.buf lint where comment ignores in the shape of // buf:lint:ignore <RULE_ID> <extra comment> were not recognized due to the extra comment.buf config ls-{breaking,lint}-rules. Default rules are those rules which are run if no lint or breaking rules are explicitly configured in your buf.yaml.DEFAULT lint rule category to STANDARD. With the concept of default rules being introduced, having a category named DEFAULT is confusing, as while it happens that all the rules in the DEFAULT lint category are also default rules, the name has become overloaded. As with all buf changes, this change is backwards-compatible: the DEFAULT lint category continues to work, and always will. We recommend changing to STANDARD, however.includes key to module configurations in v2 buf.yaml, accepting a list of directories.includes is specified, a proto file is considered in the module only if it is in one of the directories specified.includes and excludes keys are specified for a module, a proto file is considered part of this module if it is contained in any of the include paths and not in any of the exclude paths.buf.yaml to have the same directory path.--http3 flag to buf curl which forces buf curl to use HTTP/3 as the transport.buf.lock files when buf dep update does not find new dependencies to update and there is no existing buf.lock.buf push to push the license file or doc file (e.g. README.md, LICENSE) in the same directory as buf.yaml if a module does not have a license file or doc file in the module's directory.--path flag for lint and breaking rules to avoid resolving all files within a module. This change can result in a performance improvement for large workspaces.STABLE_PACKAGE_NO_IMPORT_UNSTABLE lint rule which disallows files from stable packages to import files from unstable packages.--list-services and --list-methods flags to buf curl, which trigger the command to list known services or methods in the RPC schema, instead of invoking an RPC method.clean as a top-level option in buf.gen.yaml, matching the buf generate --clean flag. If set to true, this will delete the directories, jar files, or zip files set to out for each plugin.buf registry login to complete the login flow in the browser by default. This allows users to login with their browser and have the token automatically provided to the CLI.buf registry organization {create, delete, info, update} commands to manage BSR organizations. Remove buf beta registry organization commands.buf registry module {create, delete, deprecate, info, undeprecate, update} commands to manage BSR modules. Remove buf beta registry repository commands.buf registry label {archive, info, list, unarchive} commands to manage BSR module labels. Remove buf beta registry label commands and buf beta registry {archive, unarchive}.buf registry commit {add-label, info, list, resolve} to manage BSR module commits. Remove buf beta registry commit commands.ref to align with the git notion of a ref. This allows for the use of branch names, tag names, and commit hashes.buf build errors with absolute path directory inputs without workspace and/or module configurations (e.g. buf.yaml, buf.work.yaml) and proto file paths set to the --path flag.buf generate --clean flag that will delete the directories, jar files, or zip files that the plugins will write to, prior to generation. Allows cleaning of existing assets without having to call rm -rf.--username flag on and username prompt on buf registry login. A username is no longer required to log in.buf config ls-modules command to list configured modules.buf generate would succeed on missing insertion points and panic on empty insertion point files.buf generate to allow the use of Editions syntax when doing local code generation by proxying to a protoc binary (for languages where code gen is implemented inside of protoc instead of in a plugin: Java, C++, Python, etc).protoc_path property of for buf.gen.yaml, where the first array element is the actual path and other array elements are extra arguments that are passed to protoc each time it is invoked.--source-control-url and --create-default-label when using --git-metadata with buf push.buf push --git-metadata when local tags point to different objects than the remote tags.PROTOVALIDATE lint rule violations.buf beta registry label {create,get,list} to replace buf beta registry {draft, tag} commands.buf beta commit {get,list} command outputs to display create time and stop displaying associated tags.buf beta commit list <buf.build/owner/repository> when the reference is empty. It now lists commits in the repository instead of listing commits of the default label.buf format to canonicalize the punctuation used in message literals in option values. The output now always uses { and } instead of < and >; it adds : separators between field names and message values if the source omitted them, and it removes unnecessary separators between fields (, and ; are allowed, but neither is needed).buf format -w so that it does not touch files whose contents don't actually change. This eliminates noisy notifications to file-system-watcher tools that are watching the directory that contains proto sources.buf generate to work with plugins provided by protoc for versions v24.0 to v25.3. Editions support was experimental in these releases, and the plugins advertise incomplete support for editions, which triggers buf to report an error. With this fix, these plugins can be used again as long as none of the input files use editions syntax.buf push --exclude-unnamed flag to exclude unnamed modules when pushing to the BSR.buf generate to warn instead of error when proto3 optional is required but not supported by a plugin.--path and --exclude-path paths are relative to the #subdir rather than the root of the input. This fixes an unintended behavior change that was introduced in v1.32.0.module input for protoc-gen-buf-lint and protoc-gen-buf-breaking to allow users to specify the module for v2 configuration files.v2 for buf.yaml and buf.gen.yaml configuration files.buf config migrate to migrate configuration files to the latest version (now v2).buf mod init to buf config init. buf mod init is now deprecated.buf mod ls-lint-rules to buf config ls-lint-rules. buf mod ls-lint-rules is now deprecated.buf mod ls-breaking-rules to buf config ls-breaking-rules. buf mod ls-breaking-rules is now deprecated.buf mod prune to buf dep prune. buf mod prune is now deprecated.buf mod update to buf dep update. buf mod update is now deprecated.buf mod {clear-cache,cc} to buf registry cc. buf mod {clear-cache,cc} is now deprecated.buf beta graph to stable as buf dep graph.buf push --create-visibility to private when the --create flag is set. Users are no longer required to set --create-visibility when running buf push --create.buf push --label, which allows users to set labels when pushing new commits to the BSR.buf push --source-control-url, which allows users to associate commits pushed to the BSR with a URL to a source code repository.buf push --create-default-label, which allows users to set a default label for a repository when calling buf push --create.buf push --git-metadata, which automatically sets appropriate --label, --source-control-url, and --create-default-label flags based on the current Git repository.buf convert --validate to apply protovalidate rules to incoming messages specified with --from.buf mod open.buf beta migrate-v1beta1 This is now replaced with buf config migrate.buf registry sdk version to get the version of a Generated SDK for a module and plugin.buf beta registry archive and buf beta registry unarchive commands for archiving and unarchiving labels on the BSR.buf to be used with sources that use edition 2023, instead of proto2 or proto3 syntax. This also updates the protoc-gen-buf-breaking and protoc-gen-buf-lint Protobuf plugins to support files that use edition 2023.buf breaking rules to work with Protobuf Editions. To support Editions, some rules have been deprecated and replaced with Editions-aware rules. All deprecated rules continue to work for existing users.FIELD_SAME_CTYPE has been replaced with FIELD_SAME_CPP_STRING_TYPE, which considers both ctype field options and new (pb.cpp).string_type features when deciding on backwards compatibility.FIELD_SAME_LABEL has been replaced with three rules that all check “cardinality”. The new rules can distinguish between maps and other repeated fields and between implicit and explicit field presence. The new rules are:FIELD_SAME_CARDINALITY in the FILE and PACKAGE categories.FIELD_WIRE_COMPATIBLE_CARDINALITY in the WIRE category.FIELD_WIRE_JSON_COMPATIBLE_CARDINALITY in the WIRE_JSON category.FILE_SAME_JAVA_STRING_CHECK_UTF8 has been replaced with FIELD_SAME_JAVA_UTF8_VALIDATION, which considers both the java_string_check_utf8 file option and (pb.java).utf8_validation features when deciding on backwards compatibility.FILE_SAME_SYNTAX rule with a few related rules that can catch the same sort of compatibility issues, but in an Editions source file that changes feature values:MESSAGE_SAME_JSON_FORMAT and ENUM_SAME_JSON_FORMAT catch changes to the json_format feature, which controls whether support for the JSON format is best-effort or properly supported. When supported, the compiler performs more checks relating to field name collisions for the JSON format as well as for FieldMask usage.FIELD_SAME_UTF8_VALIDATION catches changes to the utf8_validation feature, which controls validation of string values.ENUM_SAME_TYPE catches changes to an enum's type, open vs. closed.buf breaking. All existing rules for fields are now applied to extensions, except for FIELD_NO_DELETE (and its variants). There are also new EXTENSION_NO_DELETE and PACKAGE_EXTENSION_NO_DELETE rules for catching deletions of an extension. The new rules are not active by default in existing v1 and v1beta1 configurations, for backwards-compatibility reasons. Migrate your config to v2 to use them.buf lint. It previously only checked extensions that were defined inside of messages.FIELD_NOT_REQUIRED lint rule that prevents use of required in proto2 files and of features.field_presence = LEGACY_REQUIRED in Editions files. This new rule is not active by default in existing v1 and v1beta1 configurations, for backwards-compatibility reasons. Migrate your config to v2 to use them.buf convert --validate to apply protovalidate rules to incoming messages specified with --from.buf config migrate to migrate configuration files to the latest version (now v2).buf beta graph to stable as buf dep graph.buf mod init to buf config init. buf mod init is now deprecated.buf mod ls-lint-rules to buf config ls-lint-rules. buf mod ls-lint-rules is now deprecated.buf mod ls-breaking-rules to buf config ls-breaking-rules. buf mod ls-breaking-rules is now deprecated.buf mod prune to buf dep prune. buf mod prune is now deprecated.buf mod update to buf dep update. buf mod update is now deprecated.buf mod {clear-cache,cc} to buf registry cc. buf mod {clear-cache,cc} is now deprecated.buf mod open.buf beta migrate-v1beta1.buf registry sdk version to get the version of a Generated SDK for a module and plugin.buf lint incorrectly reports an error for (buf.validate.field).repeated is set for a repeated validation rule.buf generate so it populates the recently-added source_file_descriptors field of the CodeGeneratorRequest message. This provides the plugin with access to options that are configured to only be retained in source and not at runtime (via field option). Descriptors in the proto_file field will not include any options configured this way for the files named in file_to_generate field.--exclude-source-retention-options flag to buf build, which causes options configured to only be retained in source to be stripped from the output descriptors.yaml format. All commands that take image inputs, output images, or convert between message formats, now take yaml as a format, in addition to the existing binpb and txtpb formats. Some examples:buf build -o image.yamlbuf ls-files image.yamlbuf convert --type foo.Bar --from input.binpb --to output.yamlyaml and json formats now accept two new options: use_proto_names and use_enum_numbers. This affects output serialization. Some examples:buf convert --type foo.Bar --from input.binpb --to output.yaml#use_proto_names=truebuf convert --type foo.Bar --from input.binpb --to -#format=yaml,use_enum_numbers=truebuf format would inadvertently mangle files that used the expanded Any syntax in option values.buf curl command has been updated to support the use of multiple schemas. This allows users to specify multiple --schema flags and/or to use both --schema and --reflect flags at the same time. The result is that additional sources can be consulted to resolve an element. This can be useful when the result of an RPC contains extensions or values in google.protobuf.Any messages that are not defined in the same schema that defines the RPC service.buf lint incorrectly reports error when (buf.validate.field).required is set for an optional field in proto3.buf lint will now verify that your protovalidate rules are valid. A single rule PROTOVALIDATE has been added to the DEFAULT group - given that protovalidate is net new, this does not represent a breaking change.buf beta price with the latest pricing information.buf.lock with dependencies with b1 or b3 digests. b1 and b3 digests will be deprecated in a future version. Run buf mod update to update dependency digests.buf build and other commands may fail when handling certain archives created on macOS that contain files with extended attributes.--path did not work with workspaces under certain scenarios.buf generate --exclude-path was not properly excluding paths for remote modules.buf curl had a user agent that did not properly place the extension as a suffix.buf beta price with the latest pricing information.buf build -o did not properly output files with the .txtpb extension in Protobuf text format.--http2-prior-knowledge flag when running buf curl against secure “https” URLs. This can be used with gRPC servers, that only support HTTP/2, when used with a network (layer 4) load balancer, that does not support protocol negotiation in TLS handshake.--path flag.. was incorrectly accepted as a value for the directories key in buf.work.yaml.txtpb format to handle the Protobuf text format. and automatically recognize .txtpb files as Protobuf text files. The txtpb format can now be used with all buf commands that take images as input or output, such as build, convert, and curl.buf mod update to block updates that will result in conflicting .proto files across dependencies.bin format with binpb format, and support the .binpb file extension. .binpb is now the canonical file extension for binary-encoded Protobuf data. The bin format and the .bin file extension continue to be accepted.go subdomain in .netrc. This was used as part of the remote generation alpha, which has been fully deprecated in favor of remote plugins and remote packages. See https://buf.build/blog/remote-packages-remote-plugins-approaching-v1 for more details.buf beta price with the latest pricing information.buf beta graph would not print modules within a workspace that had no dependencies or dependents.buf beta graph would print warnings for missing dependencies that were actually present.buf beta graph to print the dependency graph for a module in DOT format.--origin flag of buf beta studio-agent to https://buf.buildbuf beta registry template.buf beta registry plugin {create,deprecate,list,undeprecate,version} and replace with buf beta registry plugin {push,delete}.buf beta price with the latest pricing information.--emit-defaults flag to buf curl to emit default values in JSON-encoded responses.buf curl by default.--create flag to buf push to create a repository if it does not exist. The user is also required to specify the visibility using --create-visibility.github-actions error format to print errors in a form parseable by GitHub Actions.buf build and buf generate where the use of type filtering (via --type flags) would cause the resulting image to have no source code info, even when --exclude-source-info was not specified. The main impact of the bug was that generated code would be missing comments.buf curl when using --user or --netrc that would cause a malformed Authorization header to be sent.buf mod --clear-cache once after upgrading to remove data stored in the previous module cache.buf beta registry {plugin,template} {deprecate,undeprecate}.--user and --netrc flags to buf curl, providing the same behavior as the flags of the same name in the cURL tool.DocumentationPath in the module on buf push.README.md and README.markdown, for module documentation. The default source for module documentation is buf.md. If buf.md is missing, README.md or README.markdown is used as fallback sources.buf beta stats command to print statistics about a given source or module.buf beta price with the latest pricing information.buf beta price command to help users of the BSR figure out how much a module will cost to store on the BSR under the Teams or Pro plans.protoc-gen-buf-lint that prevented it from reporting lint errors for unused imports.buf format where indents would be produced on certain empty lines.buf alpha registry token create command. Tokens must be created through the BSR UI.BUF_ALPHA_ENABLE_WASM environment variable. This feature is under evaluation, and may change at any time. If you are interested in WASM Protobuf plugins, reach out to us.buf generate with v1beta1 config files.--type flag with buf build or buf generate.buf format where C-style block comments in which every line includes a prefix (usually “*”) would be incorrectly indented.--private-network flag to buf beta studio-agent to support handling CORS requests from Studio on private networks that set the Access-Control-Request-Private-Network header.buf generate --include-types with buf generate --type for consistency. --include-types is now deprecated but continues to work, consistent with our compatibility guarantee.google.protobuf.Any messages in option values when filtering on type, e.g. with buf build --type or buf generate --type.protoc path in buf.gen.yaml when using protoc's built-in plugins via the new protoc_path option.buf.gen.yaml. You can now do e.g. path: ["go, "run", ./cmd/protoc-gen-foo] in addition to path: protoc-gen-foo.buf mod init, e.g. buf mod init buf.build/owner/foobar.php_metadata_namespace file option in managed mode.buf generate when remote plugins from multiple BSR instances are being used at once.BUF_TOKEN environment variable to accept tokens for multiple BSR instances. Both TOKEN and TOKEN1@BSRHOSTNAME1,TOKEN2@BSRHOSTNAME2,... are now valid values for BUF_TOKEN.buf beta convert in favor of the now-stable buf convert.buf curl command to invoke RPCs via Connect, gRPC, or gRPC-Webobjc_class_prefix option in managed mode, allowing a default value for objc_class_prefix for all files, except and override, which both behave similarly to other except and override options. Specifying an empty default value is equivalent to having managed mode on in previous versions.ruby_package option in managed mode, allowing except and override, in the same style as objc_class_prefix. Leaving ruby_package unspecified has the same effect as having mananged mode enabled in previous versions.buf generate now batches remote plugin generation calls for improved performance.optimize_for option in managed mode, allowing a default value for optimize_for for all files, except and override, which both behave similarly to other except and override options. Specifying an optimize_for value in the earlier versions is equivalent to having a optimize_for with that value as default.enabled: false now no longer fails buf generate and instead prints a warning log and ignores managed mode options.csharp_namespace option to managed mode, allowing except, which excludes modules from managed mode, and override, which specifies csharp_namespace values per module, overriding the default value. By default, when managed mode is enabled, csharp_namespace is set to the package name with each package sub-name capitalized.buf convert to stable, keep buf beta convert aliased in the beta command.Types filter to buf generate command to specify types (message, enum, service) that should be included in the image. When specified, the resulting image will only include descriptors to describe the requested types.New compiler that is faster and uses less memory than the outgoing one.
The new compiler also addresses a few bugs where Buf would accept proto sources that protoc would reject:
Push lint and breaking configuration to the registry.
Include LICENSE file in the module on buf push.
Formatter better edits/preserves whitespace around inline comments.
Formatter correctly indents multi-line block (C-style) comments.
Formatter now indents trailing comments at the end of an indented block body (including contents of message and array literals and elements in compact options) the same as the rest of the body (instead of out one level, like the closing punctuation).
Formatter uses a compact, single-line representation for array and message literals in option values that are sufficiently simple (single scalar element or field).
buf beta convert flags have changed from --input to --from and --output/-o to --to
fully qualified type names now must be parsed to the input argument and --type flag separately
--origin flag of buf beta studio-agent to https://studio.buf.build--timeout flag of buf beta studio-agent to 0 (no timeout). Before it was 2m (the default for all the other buf commands).plugin: key in buf.gen.yaml.buf format.junit format errors with --error-format.--draft flag to buf push.buf beta registry draft {list,delete} commands.// buf:lint:ignore comment ignores did not work for the ENUM_FIRST_VALUE_ZERO rule.buf beta studio-agent command to support the upcoming Buf Studio.protoc 3.20.1 support.buf would fail if two or more roots contained a file with the same name, but with different file types (i.e. a regular file vs. a directory).PACKAGE_SERVICE_NO_DELETE to detect deleted services.buf beta registry track.buf beta registry branch.buf beta registry repository update command which supports updating repository visibility (public vs private). As with all beta commands, this is likely to change in the future.--config flag to be set when targeting a module within a workspace.buf format's file option order so that default file options are sorted before custom options.buf format to write adjacent string literals across multiple lines.buf format so that the output directory (if any) is created if and only if the input is successfully formatted.--exit-code flag to buf format to exit with a non-zero exit code if the files were not already formatted.buf format command to format .proto files.command-line-arguments pseudo-package when building binaries and re-introduce checking for proper usage of private packages.--type flag to the build command to create filtered images containing only the specified types and their required dependencies.buf registry login.buf beta convert.buf registry login.buf mod open that opens a module's homepage in a browser.buf completion command to generate auto-completion scripts in commonly used shells.--disable-symlinks flag to the breaking, build, export, generate, lint, ls-files, push commands. By default, the CLI will follow symlinks except on Windows, and this disables following symlinks.--include-wkt flag to buf generate. When this flag is specified alongside --include-imports, this will result in the Well-Known Types being generated as well. Most language runtimes have the Well-Known Types included as part of the core library, making generating the Well-Known Types separately undesirable.buf protoc. This was a pre-v1.0 demonstration to show that buf compilation produces equivalent results to mainline protoc, however buf is working on building a better Protobuf future that provides easier mechanics than our former protoc-based world. buf protoc itself added no benefit over mainline protoc beyond being considerably faster and allowing parallel compilation. If protoc is required, move back to mainline protoc until you can upgrade to buf. See #915 for more details.buf registry login to properly check the user provided token without the token being overridden by the CLI interceptor.buf config init command in favor of buf mod init.buf config ls-breaking-rules command in favor of buf mod ls-breaking-rules.buf config ls-lint-rules command in favor of buf mod ls-lint-rules.buf config migrate-v1beta1 command in favor of buf beta migrate-v1beta1.buf beta decode command to decode message with provided image source and message type.--config flag for workspaces.v1beta1 to v1.default, except and override to java_package_prefix.b3 digest.protoc 3.19.4 support.branch field from buf.lock.protoc 3.19.3 support.PACKAGE_NO_IMPORT_CYCLE lint rule to detect package import cycles.buf beta registry {plugin,template} {deprecate,undeprecate}.digest, and created_at fields from the buf.lock. This will temporarily create a new commit when pushing the same contents to an existing repository, since the ModulePin has been reduced down.--track flag to buf pushbuf beta registry commit list to allow a track to be specified.buf beta registry track {list,delete} commands.buf.compiler_version parameter in the CodeGeneratorRequest to “(unknown)”.buf mod update was unable to resolve dependencies from different remotes.buf login message.buf generate fails when the same plugin was specified more than once in a single invocation.name, lint, and breaking configuration encoded in the buf.yaml. When this change is deployed, users will observe the following:v0.43.0 or before will notice mismatched digest errors similar to the one described in https://github.com/bufbuild/buf/issues/661.v0.44.0 or after will have their module cache invalidated, but it will repair itself automatically.buf.lock (across all versions) will reflect the new b3- digest values for new commits.--exclude-path flag to buf breaking, buf build, buf export, buf generate, and buf lint commands. This allows users to exclude specific paths when running commands.GetModulePackages endpoint to return a repeated ModulePackage message that now includes package description with the package name.Oneof to the Message structure for documentation.protoc 3.19.1 support.buf generate where multiple insertion points are defined in the same file.buf ls-files when given an image as an input, imports were being printed, even without the --include-imports flag.buf commands against and file input based on their current working directory, for example, buf lint foo/bar.proto, where foo/bar.proto is a path to protobuf file on disk.buf beta registry repository deprecate and buf beta registry repository undeprecate.--include-imports for remote plugins.buf config migrate-v1beta1 fails when files cannot be renamed.buf registry login panics when an existing .netrc entry exists.buf generate could fail when used with large numbers of plugins and files on systems with low file limits.buf protoc --version flag back. This was accidentally removed.protoc 3.18.1 support.--as-import-paths flag to ls-files that strips local directory paths and prints file paths as they are imported.protoc.--include-imports flag to ls-files.protoc 3.18.0 support.recurse_submodules=true.This is our first v1.0 release candidate. This release largely concentrates on erroring for already-deprecated commands and flags.
At Buf, we take compatibility very seriously. When we say v1.0, we mean it - we hope buf will be stable on v1 for the next decade, and if there is something we want to change, it is our responsibility to make sure that we don't break you, not your responsibility to change because of us. We have learned a lot about buf usage in the last two years of our beta, and have deprecated flags and commands as we go, but for v1.0, we are removing the deprecated items to make sure we have a clean setup going forward.
All commands and flags have been printing warnings for a long time, and have an easy migration path. Simply update the command or flag, and you'll be good to go:
buf login command in favor of buf registry login.buf logout command in favor of buf registry logout.buf mod init command in favor of buf config init.--name and --dep flags in buf config init.--log-level global flag.--version from stderr to stdout.--help and help from stderr to stdout.buf.yaml, buf.gen.yaml, buf.work.yaml) is now required.buf beta config init command in favor of buf config init.buf beta mod export command in favor of buf export.buf beta mod init command in favor of buf config init.buf beta mod update command in favor of buf mod update.buf beta mod clear-cache command in favor of buf mod clear-cache.buf beta push command in favor of buf push.buf check breaking command in favor of buf breaking.buf check lint command in favor of buf lint.buf check ls-lint-checkers command in favor of buf config ls-lint-rules.buf check ls-breaking-checkers command in favor of buf config ls-breaking-rules.--file flag on buf build in favor of the --path flag.--file flag on buf lint in favor of the --path flag.--file flag on buf breaking in favor of the --path flag.--file flag on buf generate in favor of the --path flag.--file flag on buf export in favor of the --path flag.--source flag on buf build in favor of the first positional parameter.--source-config flag on buf build in favor of the --config flag.--input flag on buf lint in favor of the first positional parameter.--input-config flag on buf lint in favor of the --config flag.--input flag on buf breaking in favor of the first positional parameter.--input-config flag on buf breaking in favor of the --config flag.--against-input flag on buf breaking in favor of the --against flag.--against-input-config flag on buf breaking in favor of the --against-config flag.--input flag on buf generate in favor of the first positional parameter.--input-config flag on buf generate in favor of the --config flag.--input flag on buf ls-files in favor of the first positional parameter.--input-config flag on buf ls-files in favor of the --config flag.buf image build command in favor of buf build.buf image convert command.buf beta image convert command.buf experimental image convert command.protoc-gen-buf-check-breaking and protoc-gen-buf-check-lint, which have been moved to protoc-gen-buf-breaking and protoc-gen-buf-lint.In January 2021 (v0.34.0), protoc-gen-buf-check-breaking and protoc-gen-buf-check-lint were deprecated and scheduled for removal for v1.0. In August 2021 (v0.52.0), we began returning error for every invocation of protoc-gen-buf-check-breaking and protoc-gen-buf-check-lint. This release completes the deletion process.
The only migration necessary is to change your installation and invocation from protoc-gen-buf-check-breaking to protoc-gen-buf-breaking and protoc-gen-buf-check-lint to protoc-gen-buf-lint. These can be installed in the exact same manner, whether from GitHub Releases, Homebrew, AUR, or direct Go installation:
# instead of go get github.com/bufbuild/buf/cmd/protoc-gen-buf-check-breaking go get github.com/bufbuild/buf/cmd/protoc-gen-buf-breaking # instead of curl -sSL https://github.com/bufbuild/buf/releases/download/v0.57.0/protoc-gen-buf-check-breaking-Linux-x86_64 curl -sSL https://github.com/bufbuild/buf/releases/download/v0.57.0/protoc-gen-buf-breaking-Linux-x86_64
ENUM_ZERO_VALUE_SUFFIX comment ignores from the enum level.buf generate --output was not being respected in 0.55.0.version: is not set in buf.yaml. This is one of the few breaking changes we must make before v1.0 to guarantee stability for the future. If you do not have a version set, simply add version: v1beta1 to the top of your buf.yaml.BUF_TOKEN for authentication. buf will now look for a token in the BUF_TOKEN environment variable, falling back to .netrc as set via buf login.--verbose (-v) flag.--debug flag to print out debug logging.java_package_prefix support to managed mode.:main was appended for errors containing references to modules.buf generate --include-imports would end up generating files for certain imports twice.buf.mod and buf.yaml are present. buf.mod was briefly used as the new default name for buf.yaml, but we've reverted back to buf.yaml.Return error for all invocations of protoc-gen-buf-check-breaking and protoc-gen-buf-check-lint.
As one of the few changes buf will ever make, protoc-gen-buf-check-breaking and protoc-gen-buf-check-lint were deprecated and scheduled for removal for v1.0 in January 2021. In preparation for v1.0, instead of just printing out a message notifying users of this, these commands now return an error for every invocation and will be completely removed when v1.0 is released.
The only migration necessary is to change your installation and invocation from protoc-gen-buf-check-breaking to protoc-gen-buf-breaking and protoc-gen-buf-check-lint to protoc-gen-buf-lint. These can be installed in the exact same manner, whether from GitHub Releases, Homebrew, AUR, or direct Go installation:
# instead of go get github.com/bufbuild/buf/cmd/protoc-gen-buf-check-breaking go get github.com/bufbuild/buf/cmd/protoc-gen-buf-breaking # instead of curl -sSL https://github.com/bufbuild/buf/releases/download/v0.52.0/protoc-gen-buf-check-breaking-Linux-x86_64 curl -sSL https://github.com/bufbuild/buf/releases/download/v0.52.0/protoc-gen-buf-breaking-Linux-x86_64
There is no change in functionality.
v\d+alpha and v\d+beta as packages with valid versions. These will be considered unstable packages for the purposes of linting and breaking change detection if ignore_unstable_packages is set.buf generate --include-imports that also generates all imports except for the Well-Known Types.PACKAGE category was used and ignore_unstable_packages was set.FIELD_SAME_TYPE breaking change rule into FIELD_SAME_TYPE, FIELD_WIRE_COMPATIBLE_TYPE, FIELD_WIRE_JSON_COMPATIBLE_TYPE in v1. See https://github.com/bufbuild/buf/pull/400 for details.buf export.-c on git parent command instead of --config on git fetch.ruby_package to managed mode.buf export. buf export will export the files from the specified input (default ".") to the given directory in a manner that is buildable by protoc without any -I flags. It also has options --exclude-imports, which excludes imports (and won't result in a buildable set of files), and --path, which filters to the specific paths.git init && git fetch rather than git clone. git clone is limited to local branches on the remote, whereas git fetch we can fetch any references on the remote including remote branches.php_namespace managed mode handling.java_string_check_utf8 managed mode handling.buf login and buf logout to login and logout from the Buf Schema Registry.buf largely works on Windows.buf.mod to buf.yaml. Note that both continue to work.buf.work to buf.work.yaml. Note that both continue to work.buf beta push to buf push. Note that buf beta push continues to work.buf beta mod commands to buf mod. Note that all buf beta mod commands continue to work.--only flag to buf mod update.buf.yaml contains dependencies that are not represented in the buf.lock file.--version flag to buf config ls-{breaking,lint}-rules.SYNTAX_SPECIFIED lint rule to BASIC, DEFAULT categories for v1 configuration.IMPORT_USED lint rule to BASIC, DEFAULT categories for v1 configuration.objc_class_prefix, csharp_namespace.buf protoc -I by a directory separator.protoc plugins when using buf generate or buf protoc. Note that Windows remains officially unsupported as we have not set up testing, but largely works.protoc 3.17.3 support.buf.yaml to buf.mod. Note that buf.yaml continues to work.v1 configuration specification.v1 configuration specification.v1 module configuration specification in beta - please continue to use v1beta1 until the v1 configuration specification is rolled out.buf config migrate-v1beta1.protoc namespace resolution diff change.buf:lint:ignore directives as valid comments for the COMMENT_.* lint rules.protoc 3.17.1 support.protoc.arm64 to aarch64 to match the output of uname -m on Linux.MESSAGE_SAME_REQUIRED_FIELDS breaking change rule. This checks to make sure no required fields are added or deleted from existing messages.FileAnnotation errors.buf beta registry tag {create,list} commands.push via buf beta push -t.buf lint and buf breaking.buf beta push doesn't create a new commit if the content of the push is the same as the latest commit on the branch.buf protoc would error if a plugin returned an empty error string.protoc version for compatibility to 3.15.2. The --experimental_allow_proto3_optional flag is no longer set for versions >=3.15.go_package values for the Well-Known Types now point at google.golang.org/protobuf instead of github.com/golang/protobuf.Allows comment ignores of the form // buf:lint:ignore ID to be cascaded upwards for specific rules.
ENUM_VALUE_PREFIX, ENUM_VALUE_UPPER_SNAKE_CASE, both the enum value and the enum are checked.FIELD_LOWER_SNAKE_CASE, FIELD_NO_DESCRIPTOR, both the field and message are checked.ONEOF_LOWER_SNAKE_CASE, both the oneof and message are checked.RPC_NO_CLIENT_STREAMING, RPC_NO_SERVER_STREAMING, RPC_PASCAL_CASE, RPC_REQUEST_RESPONSE_UNIQUE, both the method and service are checked.RPC_REQUEST_STANDARD_NAME, RPC_RESPONSE_STANDARD_NAME, the input/output type, method, and service are checked.opt in buf.gen.yaml files to be either a single string, or a list of strings. Both of the following forms are accepted, and result in foo=bar,baz,bat:version: v1beta1 plugins: - name: foo out: out opt: foo=bar,baz,bat
version: v1beta1 plugins: - name: foo out: out opt: - foo=bar - baz - bat
buf check lint to buf lint.buf check breaking to buf breaking.buf check ls-lint-checkers to buf config ls-lint-rules.buf check ls-breaking-checkers to buf config ls-breaking-rules.protoc-gen-buf-check-lint to protoc-gen-buf-lint.protoc-gen-buf-check-breaking to protoc-gen-buf-breaking.buf beta config init.All previous commands continue to work in a backwards-compatible manner, and the previous protoc-gen-buf-check-lint and protoc-gen-buf-check-breaking binaries continue to be available at the same paths, however deprecation messages are printed.
strategy option to buf.gen.yaml generation configuration. This allows selecting either plugin invocations with files on a per-directory basis, or plugin invocations with all files at once. See the generation documentation for more details.SourceCodeInfo for map fields within nested messages could be dropped.breaking.ignore_unstable_packages = true.buf commands.breaking.ignore_unstable_packages option to allow ignoring of unstable packages when running buf check breaking. See the documentation for more details.allow_alias option that add new aliases to a given number will no longer be considered breaking by ENUM_VALUE_SAME_NAME. See the documentation for more details.--experimental_allow_proto3_optional was not set when proxying to protoc for the builtin plugins via buf generate or buf protoc. This flag is now set for protoc versions >= 3.12.--file flag to --path and allow --path to take both files and directories, instead of just files with the old --file. This flag is used to filter the actual Protobuf files built under an input for most commands. You can now do for example buf generate --path proto/foo to only generate stubs for the files under proto/foo. Note that the --file flag continues to work, but prints a deprecation message.buf generate.git:// protocol handling.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.-o flag is no longer required for buf build, instead defaulting to the OS equivalent of /dev/null.--source flag on buf build has been deprecated in favor of passing the input as the first argument.--source-config flag on buf build has been moved to --config.--input flag on buf check lint has been deprecated in favor of passing the input as the first argument.--input-config flag on buf check lint has been moved to --config.--input flag on buf check breaking has been deprecated in favor of passing the input as the first argument.--input-config flag on buf check breaking has been moved to --config.--against-input flag on buf check breaking has been moved to --against.--against-input-config flag on buf check breaking has been moved to --against-config.--input flag on buf generate has been deprecated in favor of passing the input as the first argument.--input-config flag on buf generate has been moved to --config.--input flag on buf ls-files has been deprecated in favor of passing the input as the first argument.--input-config flag on buf ls-files has been moved to --config.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.
subdir option for archive and git Inputs. This allows placement of the buf.yaml configuration file in directories other than the base of your repository. You then can check against this subdirectory using, for example, buf check breaking --against-input https://github.com/foo/bar.git#subdir=proto.buf help generate documentation.buf beta generate out of beta to buf generate. This command now uses a template of configured plugins to generate stubs. See buf help generate for more details.buf protoc and buf beta generate.v1beta1. See buf.build/docs/faq for more details.protoc version for buf protoc to be 3.13.0.experimental parent command to beta. The command buf experimental image convert continues to work, but is deprecated in favor of buf beta image convert.buf beta generate.buf protoc.optional fields in proto3 would cause the ONEOF_LOWER_SNAKE_CASE lint checker to fail.--.*_opt to buf protoc for builtin plugins were not properly propagated.--.*_opt flags, --.*_opt flags with commas, or --.*_out flags with options that contained commas, would not be properly added.--by-dir flag to buf protoc that parallelizes generation per directory, resulting in a 25-75% reduction in the time taken to generate stubs for medium to large file sets.protoc command. This is a substitute for protoc that uses Buf's internal compiler.ENUM_FIRST_VALUE_ZERO lint checker to the OTHER category.buf experimental image convert command to convert to/from binary/JSON images (#87).buf check lint --input https://github.com/bufbuild/buf.git#ref=fa74aa9c4161304dfa83db4abc4a0effe886d253.depth input option when specifying git inputs with ref. This allows the user to configure the depth at which to clone the repository when looking for the ref. If specifying a ref, this defaults to 50. Otherwise, this defaults to 1.buf check lint --input https://github.com/bufbuild/buf.git and it will automatically choose the default branch as an input.allow_comment_ignores lint configuration option and buf:lint:ignore ID leading comment annotation (#73).--file flag to buf image build to only add specific files and their imports to outputted images. To exclude imports, use --exclude-imports.zip as a source format. Buf can now read zip files, either locally or remotely, for image building, linting, and breaking change detection.zstd as a compression format. Buf can now read and write Image files that are compressed using zstandard, and can read tarballs compressed with zstandard.bingz, jsongz, targz are now deprecated. Instead, use format=bin,compression=gzip, format=json,compression=gzip, or format=tar,compression=gzip. The formats bingz, jsongz, targz will continue to work forever and will not be broken, but will print a deprecation warning and we recommend updating. Automatic file extension parsing continues to work the same as well.git binary instead of go-git for internal clones. This also enables using your system git credential management for git repositories cloned using https or ssh. See https://buf.build/docs/inputs#authentication for more details... resulted in an error.--experimental-git-clone to use the git binary for git clones.recurse_submodules option for git inputs. Example: https://github.com/foo/bar.git#branch=master,recurse_submodules=trueImage was non-deterministic.SourceCodeInfo for the Well-Known Types was not included on an outputted Image when requested.--timeout flag.tag option for git inputs.git to the Docker container for local filesystem clones.path as the file path key instead of filename.allow_alias set and duplicate enum values present resulted in a system error.ENUM_VALUE_SAME_NUMBER checker being replaced with the ENUM_VALUE_SAME_NAME checker, except this new checker is not in the WIRE category.buf check lint --error-format=config-ignore-yaml to print out current lint errors in a format that can be copied into a configuration file.buf binary.Initial beta release.