In Pants, every formatter is (typically) also a linter, meaning that if you can run a tool with `./pants fmt`, you can run the same tool in check-only mode with `./pants lint`. Start by skimming [Add a linter](🔗) to familiarize yourself with how linters work.
This guide assumes that you are running a formatter that already exists outside of Pants as a stand-alone binary, such as running Black or Prettier.
If you are instead writing your own formatting logic inline, you can skip Step 1. In Step 4, you will not need to use `Process`.
Install your formatter
There are several ways for Pants to install your formatter. See [Installing tools](🔗). This example will use `ExternalTool` because there is already a pre-compiled binary for shfmt.
You will also likely want to register some options, like `--config`, `--skip`, and `--args`. Options are registered through a [`Subsystem`](🔗). If you are using `ExternalTool`, this is already a subclass of `Subsystem`. Otherwise, create a subclass of `Subsystem`. Then, set the class property `options_scope` to the name of the tool, e.g. `"shfmt"` or `"prettier"`. Finally, add options from `pants.option.option_types`.
Set up a `
FieldSet` and `FmtRequest`
As described in [Rules and the Target API](🔗), a `FieldSet` is a way to tell Pants which `Field`s you care about targets having for your plugin to work.
Usually, you should add a subclass of `SourcesField` to the class property `required_fields`, such as `ShellSourceField` or `PythonSourceField`. This means that your linter will run on any target with that sources field or a subclass of it.
Create a new dataclass that subclasses `FieldSet`:
Then, hook this up to a new subclass of `FmtRequest`.
Finally, register your new `FmtRequest` with a [`UnionRule`](🔗) so that Pants knows your formatter exists:
Create `
fmt` rules
You will need a rule for `fmt` which takes the `FmtRequest` from step 3 (e.g. `ShfmtRequest`) as a parameter and returns a `FmtResult`.
The `FmtRequest` has properties `.field_sets` and `.snapshot`, which store collections of the `FieldSet`s defined in step 2, and their sources. Each `FieldSet` corresponds to a single target. Pants will have already validated that there is at least one valid `FieldSet`, so you can expect `ShfmtRequest.field_sets` to have 1-n `FieldSet` instances.
If you have a `--skip` option, you should check if it was used at the beginning of your `fmt` and `lint` rules and, if so, to early return an empty `LintResults()` and return `FmtResult.skip()`.
If you used `ExternalTool` in step 1, you will use `Get(DownloadedExternalTool, ExternalToolRequest)` to ensure that the tool is fetched.
Use `Get(Digest, MergeDigests)` to combine the different inputs together, such as merging the source files and downloaded tool.
Finally, update your plugin's `register.py` to activate this file's rules. Note that we must register the rules added in Step 2, as well.
Now, when you run `./pants fmt ::` or `./pants lint ::`, your new formatter should run.
Add tests (optional)
Refer to [Testing rules](🔗).