Skip to main content
Version: 2.19.x (prerelease)

buf

A linter and formatter for Protocol Buffers (https://github.com/bufbuild/buf).

Backend: pants.backend.codegen.protobuf.lint.buf

Config section: [buf]

Basic options​

format_skip​

--[no-]buf-format-skip
PANTS_BUF_FORMAT_SKIP
default: False

If true, don't use Buf when running scie-pants-linux-x86_64 fmt and scie-pants-linux-x86_64 lint.

lint_skip​

--[no-]buf-lint-skip
PANTS_BUF_LINT_SKIP
default: False

If true, don't use Buf when running scie-pants-linux-x86_64 lint.

format_args​

--buf-format-args="[<shell_str>, <shell_str>, ...]"
PANTS_BUF_FORMAT_ARGS
default: []

Arguments to pass directly to Buf, e.g. --buf-args='--error-format json'.

lint_args​

--buf-lint-args="[<shell_str>, <shell_str>, ...]"
PANTS_BUF_LINT_ARGS
default: []

Arguments to pass directly to Buf, e.g. --buf-args='--error-format json'.

Advanced options​

version​

--buf-version=<str>
PANTS_BUF_VERSION
default: v1.3.0

Use this version of Buf.

known_versions​

--buf-known-versions="['<str>', '<str>', ...]"
PANTS_BUF_KNOWN_VERSIONS
default: 
[
  "v1.3.0|linux_arm64 |fbfd53c501451b36900247734bfa4cbe86ae05d0f51bc298de8711d5ee374ee5|13940828",
  "v1.3.0|linux_x86_64|e29c4283b1cd68ada41fa493171c41d7605750d258fcd6ecdf692a63fae95213|15267162",
  "v1.3.0|macos_arm64 |147985d7f2816a545792e38b26178ff4027bf16cd3712f6e387a4e3692a16deb|15391890",
  "v1.3.0|macos_x86_64|3b6bd2e5a5dd758178aee01fb067261baf5d31bfebe93336915bfdf7b21928c4|15955291"
]

Known versions to verify downloads against.

Each element is a pipe-separated string of version|platform|sha256|length or version|platform|sha256|length|url_override, where:

  • version is the version string
  • platform is one of [linux_arm64,linux_x86_64,macos_arm64,macos_x86_64]
  • sha256 is the 64-character hex representation of the expected sha256
digest of the download file, as emitted by `shasum -a 256`
  • length is the expected length of the download file in bytes, as emitted by
`wc -c`
  • (Optional) url_override is a specific url to use instead of the normally
generated url for this version

E.g., 3.1.2|macos_x86_64|6d0f18cd84b918c7b3edd0203e75569e0c7caecb1367bbbe409b44e28514f5be|42813. and 3.1.2|macos_arm64 |aca5c1da0192e2fd46b7b55ab290a92c5f07309e7b0ebf4e45ba95731ae98291|50926|https://example.mac.org/bin/v3.1.2/mac-aarch64-v3.1.2.tgz.

Values are space-stripped, so pipes can be indented for readability if necessary.

url_template​

--buf-url-template=<str>
PANTS_BUF_URL_TEMPLATE
default: https://github.com/bufbuild/buf/releases/download/{version}/buf-{platform}.tar.gz

URL to download the tool, either as a single binary file or a compressed file (e.g. zip file). You can change this to point to your own hosted file, e.g. to work with proxies or for access via the filesystem through a file:$abspath URL (e.g. file:/this/is/absolute, possibly by templating the buildroot in a config file).

Use {version} to have the value from --version substituted, and {platform} to have a value from --url-platform-mapping substituted in, depending on the current platform. For example, https://github.com/.../protoc-&#123;version&#125;-&#123;platform&#125;.zip.

url_platform_mapping​

--buf-url-platform-mapping="{'key1': val1, 'key2': val2, ...}"
PANTS_BUF_URL_PLATFORM_MAPPING
default: 
{
  "linux_arm64": "Linux-aarch64",
  "linux_x86_64": "Linux-x86_64",
  "macos_arm64": "Darwin-arm64",
  "macos_x86_64": "Darwin-x86_64"
}

A dictionary mapping platforms to strings to be used when generating the URL to download the tool.

In --url-template, anytime the {platform} string is used, Pants will determine the current platform, and substitute {platform} with the respective value from your dictionary.

For example, if you define {"macos_x86_64": "apple-darwin", "linux_x86_64": "unknown-linux"}, and run Pants on Linux with an intel architecture, then {platform} will be substituted in the --url-template option with unknown-linux.

use_unsupported_version​

--buf-use-unsupported-version=<UnsupportedVersionUsage>
PANTS_BUF_USE_UNSUPPORTED_VERSION
one of: error, warning
default: error

What action to take in case the requested version of Buf is not supported.

Supported Buf versions: unspecified

config​

--buf-config=<file_option>
PANTS_BUF_CONFIG
default: None

Path to a config file understood by Buf (https://docs.buf.build/configuration/overview).

Setting this option will disable [buf].config_discovery. Use this option if the config is located in a non-standard location.

config_discovery​

--[no-]buf-config-discovery
PANTS_BUF_CONFIG_DISCOVERY
default: True

If true, Pants will include any relevant root config files during runs (buf.yaml). If the json format is preferred, the path to the buf.json file should be provided in the config option.

Use [buf].config instead if your config is in a non-standard location.

Deprecated options​

None