buf.gen.example.yaml

# Buf v2 is NOT v1 - there are many breaking changes. See https://buf.build/docs/configuration/v2/buf-gen-yaml/
# Given this example workspace:
# workspace_root
# ├── buf.gen.yaml
# ├── buf.lock
# ├── buf.yaml
# └── proto
#    ├── location
#    │       └── location.proto
#    └── weather
#            └── weather.proto
version: v2
# 'clean', when set to true, deletes the directories, zip files, and/or jar files specified in the `out` field for
# all plugins before running code generation.
clean: true
# 'managed' contains the configuration for managed mode: https://buf.build/docs/generate/managed-mode
# It has three top-level keys: 'enabled', 'disable', and 'override'.
#
# When managed mode is enabled, it uses default values for certain file and field options during code
# generation. Options, accepted values, and defaults are documented here:
# https://buf.build/docs/generate/managed-mode#default-behavior
# The 'disable' key configures modules, paths, fields, and/or options that are excluded from managed
# mode's behavior. The 'override' key configures field and file option values that override the
# default values managed mode uses during code generation.
#
# In the case of options that combine with other options (for example java_package + java_package_prefix
# + java_package_suffix), they're all applied if possible. If not (for example when all three are set)
# then the last configuration rule wins.
managed:
  # 'enabled: true' turns managed mode on, 'enabled: false' ignores all managed mode options.
  enabled: true # default: false
  # 'disable' is a list of 'disable' rules managing either file options or field options.
  # A 'disable' rule must have at least one key set.
  disable:
    # Don't modify any files in buf.build/googleapis/googleapis
    - module: buf.build/googleapis/googleapis
    # Don't modify any files in the foo/v1 directory. This can be a path to a directory
    # or a .proto file. If it's a directory path, all .proto files in the directory are
    # ignored.
    - path: foo/v1
    # Ignore the csharp_namespace file option for all modules and files in the input.
    - file_option: csharp_namespace
    # Ignore the js_type field option for any file.
    - field_option: js_type
    # Ignore the foo.bar.Baz.field_name field.
    - field: foo.bar.Baz.field_name
    # Setting all 3 for file options: don't modify java_package and go_package (by disabling
    # setting the go_package_prefix) for files in foo/v1 in buf.build/acme/weather
    - module: buf.build/acme/weather
      path: foo/v1
      file_option: java_package
    # Setting all 4 for field options: disable js_type for all files that match the
    # module, path, and field name.
    - module: buf.build/acme/petapis
      field: foo.bar.Baz.field_name
      path: foo/v1
      field_option: js_type
  # 'override' is a list of 'override' rules for the list of field and file options that
  # managed mode handles.
  override:
    # When 'file_option' and 'value' are set, managed mode uses the value set with
    # this rule instead of the default value or sets it to this value if the default
    # value is none.
    #
    # Example: Modify the java_package options to <net>.<proto_package> for all files.
    # Also modify go_package_prefix to be company.com/foo/bar for all files.
    - file_option: java_package_prefix
      value: net
    - file_option: go_package_prefix
      value: company.com/foo/bar
    # When 'file_option', 'value', and 'module' are set, managed mode uses the value
    # set in this rule instead of the default value for all files in the specified module.
    # It sets it to this value if the default value is none.
    #
    # Example: Modify the java_package option to <com>.<proto_package>.<com> for all files
    # in buf.build/acme/petapis. Also modify go_package_prefix to be company.com/foo/baz
    # for all files in buf.build/acme/petapis.
    # These rules take precedence over the rule above.
    - file_option: java_package_prefix
      module: buf.build/acme/petapis
      value: com
    - file_option: java_package_suffix
      module: buf.build/acme/petapis
      value: com
    - file_option: go_package_prefix
      module: buf.build/acme/petapis
      value: company.com/foo/baz
    # When 'file_option', 'value', and 'path' are set, managed mode uses the value set
    # in this rule instead of the default value for the specific file path. If the path
    # is a directory, the rule affects all .proto files in the directory. Otherwise, it
    # only affects the specified .proto file.
    #
    # Example: For the file foo/bar/baz.proto, set java_package specifically to
    # "com.x.y.z". Also for the file foo/bar/baz.proto modify go_package_prefix to be
    # company.com/bar/baz.
    # This takes precedence over the previous rules above.
    - file_option: java_package
      path: foo/bar/baz.proto
      value: com.x.y.z
    - file_option: go_package_prefix
      path: foo/bar/baz.proto
      value: company.com/bar/baz
    # When 'field_option', 'value', and 'module' are set, managed mode uses the value
    # set in this rule instead of the default value for all files in the specified module.
    # It sets it to this value if the default value is none.
    #
    # Example: For all fields in the buf.build/acme/paymentapis module where the field is
    # one of the compatible types, set the 'js_type' to "JS_NORMAL".
    - field_option: js_type
      module: buf.build/acme/paymentapis
      value: JS_NORMAL
    # When 'field_option', 'value', and 'field' are set, managed mode uses the value set
    # in this rule instead of the default value of the specified field. It sets it to
    # this value if the default value is none.
    #
    # Example: Set the package1.Message2.field3 field 'js_type' value to "JS_STRING". You can
    # additionally specify the module and path, but the field name is sufficient.
    - field_option: js_type
      value: JS_STRING
      field: package1.Message2.field3
# 'plugins' is a list of plugin configurations used for buf generate.
#
# A 'plugin' configuration has 8 possible keys:
#  - one of (required):
#    - 'remote': remote plugin name (for example buf.build/protocolbuffers/go)
#    - 'protoc_builtin': a 'protoc' built-in plugin (for example 'cpp' for 'protoc-gen-cpp')
#    - 'local': a string or list of strings that point to a protoc plugin binary on your
#      '${PATH}'. If a list of strings is specified, the first is the binary name, and the
#      subsequent strings are considered arguments passed to the binary.
#  - 'out': <string> path to the file output, which is the same as v1 (required)
#  - 'opt': a list of plugin options, which is the same as v1 (optional)
#  - 'strategy': a string for the invocation strategy, which is the same as v1 (optional)
#  - 'include_imports': <boolean> (optional, precedence given to CLI flag)
#  - 'include_wkt': <boolean> (optional, precedence given to CLI flag)
plugins:
  # BSR remote plugin
  - remote: buf.build/protocolbuffers/go
    out: gen/proto
  # Built-in protoc plugin for C++
  - protoc_builtin: cpp
    protoc_path: /path/to/protoc
    out: gen/proto
  # Local binary plugin, search in ${PATH} by default
  - local: protoc-gen-validate
    out: gen/proto
  # Relative paths automatically work
  - local: path/to/protoc-gen-validate
    out: gen/proto
  # Absolute paths automatically work
  - local: /usr/bin/path/to/protoc-gen-validate
    out: gen/proto
  # Binary plugin with arguments and includes
  - local: ["go", "run", "google.golang.org/protobuf/cmd/protoc-gen-go"]
    out: gen/proto
    opt:
      - paths=source_relative
      - foo=bar
      - baz
    strategy: all
    include_imports: true
    include_wkt: true
# 'inputs' is a list of inputs that will be run for buf generate. It's a
# required key for v2 buf.gen.yaml and allows you to specify options based on the type
# of input (https://buf.build/docs/reference/inputs.md#source) being configured.
inputs:
  # Git repository
  - git_repo: github.com/acme/weather
    branch: dev
    subdir: proto
    depth: 30
  # BSR module with types and include, and exclude keys specified
  - module: buf.build/acme/weather:main
    types:
      - "foo.v1.User"
      - "foo.v1.UserService"
    # If empty, include all paths.
    paths:
      - a/b/c
      - a/b/d
    exclude_paths:
      - a/b/c/x.proto
      - a/b/d/y.proto
  # Local module at provided directory path
  - directory: x/y/z
  # Tarball at provided directory path. Automatically derives compression algorithm from
  # the file extension:
  # - '.tgz' and '.tar.gz' extensions automatically use Gzip
  # - '.tar.zst' automatically uses Zstandard.
  - tarball: a/b/x.tar.gz
  # Tarball with 'compression', 'strip_components', and 'subdir' keys set explicitly.
  # - 'strip_components=<int>' reads at the relative path and strips some number of
  #    components—in this example, 2.
  # - 'subdir=<string>' reads at the relative path and uses the subdirectory specified
  #    within the archive as the base directory—in this case, 'proto'.
  - tarball: c/d/x.tar.zst
    compression: zstd
    strip_components: 2
    subdir: proto
  # The same applies to 'zip' inputs. A 'zip' input is read at the relative path or http
  # location, and can set 'strip_components' and 'subdir' optionally.
  - zip_archive: https://github.com/googleapis/googleapis/archive/master.zip
    strip_components: 1
  # 'proto_file' is a path to a specific proto file. Optionally, you can include package
  # files as part of the files to be generated (the default is false).
  - proto_file: foo/bar/baz.proto
    include_package_files: true
  # We also support Buf images as inputs. Images can be any of the following formats:
  #  - 'binary_image'
  #  - 'json_image'
  #  - 'txt_image'
  #  - 'yaml_image'
  # Each image format also supports compression optionally.
  #
  # The example below is a binary Buf image with compression set for Gzip.
  - binary_image: image.binpb.gz
    compression: gzip