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