format.md

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": "."},
)

2. Try it with bazel run //path/to:prettier -- --help.
3. Register it with format_multirun:

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

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

languages

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

languages(name, c, cc, css, cuda, go, graphql, html, java, javascript, jsonnet, kotlin, markdown,
          protocol_buffer, python, rust, scala, shell, sql, starlark, swift, terraform, yaml)

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.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
c	a clang-format binary, or any other tool that has a matching command-line interface.	Label	optional	None
cc	a clang-format binary, or any other tool that has a matching command-line interface.	Label	optional	None
css	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
cuda	a clang-format binary, or any other tool that has a matching command-line interface.	Label	optional	None
go	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.	Label	optional	None
graphql	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
html	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
java	a java-format binary, or any other tool that has a matching command-line interface.	Label	optional	None
javascript	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
jsonnet	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.	Label	optional	None
kotlin	a ktfmt binary, or any other tool that has a matching command-line interface.	Label	optional	None
markdown	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
protocol_buffer	a buf binary, or any other tool that has a matching command-line interface.	Label	optional	None
python	a ruff binary, or any other tool that has a matching command-line interface.	Label	optional	None
rust	a rustfmt binary, or any other tool that has a matching command-line interface.	Label	optional	None
scala	a scalafmt binary, or any other tool that has a matching command-line interface.	Label	optional	None
shell	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.	Label	optional	None
sql	a prettier binary, or any other tool that has a matching command-line interface.	Label	optional	None
starlark	a buildifier binary, or any other tool that has a matching command-line interface.	Label	optional	None
swift	a swiftformat binary, or any other tool that has a matching command-line interface.	Label	optional	None
terraform	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.	Label	optional	None
yaml	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.	Label	optional	None

format_multirun

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

format_multirun(name, jobs, print_command, disable_git_attribute_checks, kwargs)

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.

PARAMETERS

Name	Description	Default Value
name	name of the resulting target, typically "format"	none
jobs	how many language formatters to spawn in parallel, ideally matching how many CPUs are available	4
print_command	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.	False
disable_git_attribute_checks	Set to True to disable honoring .gitattributes filters	False
kwargs	attributes named for each language; see languages	none

format_test

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

format_test(name, srcs, workspace, no_sandbox, disable_git_attribute_checks, tags, kwargs)

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.

PARAMETERS

Name	Description	Default Value
name	name of the resulting target, typically "format"	none
srcs	list of files to verify formatting. Required when no_sandbox is False.	None
workspace	a file in the root directory to verify formatting. Required when no_sandbox is True. Typically //:WORKSPACE or //:MODULE.bazel may be used.	None
no_sandbox	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.	False
disable_git_attribute_checks	Set to True to disable honoring .gitattributes filters	False
tags	tags to apply to generated targets. In 'no_sandbox' mode, ["no-sandbox", "no-cache", "external"] are added to the tags.	[]
kwargs	attributes named for each language; see languages	none