Skip to main content
Version: 1.0.x

format

Produce a multi-formatter that aggregates formatter tools.

Some formatter tools may be installed by multitool. These are noted in the API docs below.

Note: Under --enable_bzlmod, rules_lint installs multitool automatically. WORKSPACE users must install it manually; see the snippet on the releases page.

Other formatter binaries may be declared in your repository. You can test that they work by running them directly with bazel run.

For example, to add Prettier:

  1. Add to your BUILD.bazel file:
load("@npm//:prettier/package_json.bzl", prettier = "bin")

prettier.prettier_binary(
    name = "prettier",
    # Allow the binary to be run outside bazel
    env = {"BAZEL_BINDIR": "."},
)
  1. Try it with bazel run //path/to:prettier -- --help.
  2. Register it with format_multirun:
load("@aspect_rules_lint//format:defs.bzl", "format_multirun")

format_multirun(
    name = "format",
    javascript = ":prettier",
    ... more languages
)

Rules

languages​

Language attributes that may be passed to format_multirun or format_test.

Files with matching extensions from GitHub Linguist will be formatted for the given language.

Some languages have dialects:

- `javascript` includes TypeScript, TSX, and JSON.
- `css` includes Less and Sass.

Do not call the languages rule directly, it exists only to document the attributes.

Example usage (generated):

load("@aspect_rules_lint//format:defs.bzl", "languages")

languages(
    # A unique name for this target.
    name = "",
)

name​

Required name.

A unique name for this target.

javascript​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

markdown​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

css​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

graphql​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

html​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

python​

Optional label. Default: None

a ruff binary, or any other tool that has a matching command-line interface.

starlark​

Optional label. Default: None

a buildifier binary, or any other tool that has a matching command-line interface.

jsonnet​

Optional label. Default: None

a jsonnetfmt binary, or any other tool that has a matching command-line interface. Use @aspect_rules_lint//format:jsonnetfmt to choose the built-in tool.

terraform​

Optional label. Default: None

a terraform-fmt binary, or any other tool that has a matching command-line interface. Use @aspect_rules_lint//format:terraform to choose the built-in tool.

kotlin​

Optional label. Default: None

a ktfmt binary, or any other tool that has a matching command-line interface.

java​

Optional label. Default: None

a java-format binary, or any other tool that has a matching command-line interface.

scala​

Optional label. Default: None

a scalafmt binary, or any other tool that has a matching command-line interface.

swift​

Optional label. Default: None

a swiftformat binary, or any other tool that has a matching command-line interface.

go​

Optional label. Default: None

a gofmt binary, or any other tool that has a matching command-line interface. Use @aspect_rules_lint//format:gofumpt to choose the built-in tool.

sql​

Optional label. Default: None

a prettier binary, or any other tool that has a matching command-line interface.

shell​

Optional label. Default: None

a shfmt binary, or any other tool that has a matching command-line interface. Use @aspect_rules_lint//format:shfmt to choose the built-in tool.

protocol_buffer​

Optional label. Default: None

a buf binary, or any other tool that has a matching command-line interface.

c​

Optional label. Default: None

a clang-format binary, or any other tool that has a matching command-line interface.

cc​

Optional label. Default: None

a clang-format binary, or any other tool that has a matching command-line interface.

cuda​

Optional label. Default: None

a clang-format binary, or any other tool that has a matching command-line interface.

yaml​

Optional label. Default: None

a yamlfmt binary, or any other tool that has a matching command-line interface. Use @aspect_rules_lint//format:yamlfmt to choose the built-in tool.

rust​

Optional label. Default: None

a rustfmt binary, or any other tool that has a matching command-line interface.

Macros and Functions

format_multirun​

Create a multirun binary for the given languages.

Intended to be used with bazel run to update source files in-place.

This macro produces a target named [name].check which does not edit files, rather it exits non-zero if any sources require formatting.

To check formatting with bazel test, use format_test instead.

Example usage (generated):

load("@aspect_rules_lint//format:defs.bzl", "format_multirun")

format_multirun(
    # name of the resulting target, typically "format"
    name = "",
)

name​

Required.

name of the resulting target, typically "format"

jobs​

Optional. Default: 4

how many language formatters to spawn in parallel, ideally matching how many CPUs are available

Optional. Default: False

whether to print a progress message before calling the formatter of each language. Note that a line is printed for a formatter even if no files of that language are to be formatted.

disable_git_attribute_checks​

Optional. Default: False

Set to True to disable honoring .gitattributes filters

kwargs​

Optional.

attributes named for each language; see languages

format_test​

Create test for the given formatters.

Intended to be used with bazel test to verify files are formatted. This is not recommended, because it is either non-hermetic or requires listing all source files.

To format with bazel run, see format_multirun.

Example usage (generated):

load("@aspect_rules_lint//format:defs.bzl", "format_test")

format_test(
    # name of the resulting target, typically "format"
    name = "",
)

name​

Required.

name of the resulting target, typically "format"

srcs​

Optional. Default: None

list of files to verify formatting. Required when no_sandbox is False.

workspace​

Optional. Default: None

a file in the root directory to verify formatting. Required when no_sandbox is True. Typically //:WORKSPACE or //:MODULE.bazel may be used.

no_sandbox​

Optional. Default: False

Set to True to enable formatting all files in the workspace. This mode causes the test to be non-hermetic and it cannot be cached. Read the documentation in /docs/formatting.md.

disable_git_attribute_checks​

Optional. Default: False

Set to True to disable honoring .gitattributes filters

tags​

Optional. Default: []

tags to apply to generated targets. In 'no_sandbox' mode, ["no-sandbox", "no-cache", "external"] are added to the tags.

kwargs​

Optional.

attributes named for each language; see languages

Last updated on by Greg Magolan