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:
- 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": "."},
)
- Try it with
bazel run //path/to:prettier -- --help
. - 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
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.
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