format

Produce a multi-formatter that aggregates formatters.

Some formatter tools are automatically provided by default in rules_lint. These are listed as defaults in the API docs below.

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, your BUILD.bazel file should contain:

load("@npm//:prettier/package_json.bzl", prettier = "bin")

prettier.prettier_binary(
    name = "prettier",
    # Allow the binary to be run outside bazel
    env = {"BAZEL_BINDIR": "."},
)

and you can test it with bazel run //path/to:prettier -- --help.

Then you can register it with format_multirun:

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

format_multirun(
    name = "format",
    javascript = ":prettier",
)

Macros and Functions

format_multirun

Create a multirun binary for the given formatters.

Intended to be used with bazel run to update source files in-place. To check formatting with bazel test, see format_test.

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

Tools are provided by default for some languages. These come from the @multitool repo. Under --enable_bzlmod, rules_lint creates this automatically. WORKSPACE users will have to set this up manually. See the release install snippet for an example.

Set any attribute to False to turn off that language altogether, rather than use a default tool.

Note that javascript is a special case which also formats TypeScript, TSX, JSON, CSS, and HTML.

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

print_command

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.

kwargs

Optional.

attributes named for each language, providing Label of a tool that formats it

format_test

Create test for the given formatters.

Intended to be used with bazel test to verify files are formatted. 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.

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, providing Label of a tool that formats it