The configurations for
trunk check and
trunk fmt are governed by the
lint section of
trunk.yaml. Here's an example of what a fully-featured
lint section looks like:
lint: # list of linters to run using trunk enabled: - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] - [email protected] disabled: - rufo - tflint ignore: - linters: [ALL] paths: # Generated files - a/proto/code_pb* # Test data - b/test_data/** - linters: [eslint] paths: - c/run.ts threshold: - linters: [clang-tidy] level: high triggers: - linters: - ansible-lint paths: - ansible # A directory targets: - ansible # A directory
Test your config changes
Normally when you run
trunk check or
trunk fmt it runs only on files you've changed. We've made it easy to test how a linter will behave in your repo. As you're tuning your linter configuration simply run check with the
--sample flag. When sampling trunk will find applicable files for the linters you've enabled and show you how the linter will behave against of sampling of inputs.
|all linters on 5 files|
|a specific linter with 7 files|
|all linters on a specific file|
trunk may run multiple linters on a single file, and may not run each linter on the full number of requested samples (if not enough applicable files can be found).
Tuning your linters
Most linters offer some form of configuration. Trunk uses the native configuration setup of all the tools it runs. No need to learn a new config language or hunt for specific ways to tune a linter inside trunk. Whether it's
eslint, or any other linter, all the documentation you'll find online about it is still applicable. We're proud to stand on the shoulders of giants and believe that the open source communities building these tools know best how they should work. Our goal is simply to make it as easy as possible for you to adopt these tools.
Check out our configs repository for always-up-to-date linter configs and some tips on how to structure your linters and repo.
If you'd like, trunk also supports migrating any linter configurations from the root of your repository into a
.trunk/configs folder. These config files will be symlinked in during any
trunk check run. Note that if you're using an IDE Extension like clangd with an LSP that relies on those configs being in the root, you will need to create an additional symlink from the hidden config to the workspace root.
If you find that you want to tweak how trunk runs a given linter, you may want to consult the documentation on overriding defaults and the various linter settings; for example, hold-the-line is enabled by default for most linters, but can be disabled like so:
lint: definitions: - name: pylint hold_the_line: false disable_upstream: true
Disabling hold-the-line for a linter will require that all issues found by said linter be fixed before changes to that file can be landed.
Disabling the upstream for a linter will elide the execution of the linter on the upstream.
Trunk only runs linters listed in the
enabled section; linters which are defined in
linters but are not listed in
enabled are not run.
When enabling a linter, you must specify a version for the linter:
lint: enabled: # enabling a version with a linter - [email protected] - [email protected] - [email protected] - [email protected]
Custom linters are slightly different; see those docs to learn more.
Note:You can also ask trunk to detect new linters and upgrade existing linters to their latest respective
versions by running
trunk upgrade check.
Trunk will continuously monitor your repository and make recommendations of additional new tools to run on your codebase. You can tell trunk not to recommend a specific linter by adding it to the disabled list.
lint: disabled: # disabled a linter tells trunk not to recommend it during upgrade scans - rufo - tflint
Installing additional packages
We support installing additional packages along with your linter. For example, Pylint supports adding plugins which are installable as pip packages. For example, if you want to run the plugin
pylint-django as part of your setup, you need to tell trunk to install the package:
lint: enabled: - [email protected]: packages: - [email protected] ...
By default trunk will install hermetic versions of runtimes required by the linters you have chosen. If you need to peg to a specific runtime version or you want to use the version installed on your system, consult the runtimes documentation.
Some files are never meant to be checked, such as generated code. To ignore them, use the
lint: ignore: - linters: [ALL] paths: # Ignore generated files - src/generated/** # Test data - test/test_data
Every entry in
ignore defines both a set of linters and a set of paths to ignore.
|linters||List of linters (i.e. |
|paths||List of glob paths, relative to the root of the repo, to ignore|
git-aware, which means it ignores
gitignored files by default.
All issue severities are considered blocking by default. In cases where you might want to slowly try out a new linter, we provide a mechanism to set specific thresholds for each linter.
lint: threshold: - linters: [clang-tidy] level: high
Every entry in
threshold defines a set of linters and the severity threshold that is considered blocking. In this example, we're saying that only
high lint issues should be considered blocking for
|linters||List of linters (e.g. |
|level||Threshold at which issues are considered blocking. One of : |
Some linters do not operate on individual files. Instead you must lint your entire repo at once. The way this is handled in trunk is to set up a trigger rule.
Trigger rules work on 3 principles:
- Input(s) that trigger the linters. These can be files, directories, or extended globs.
- Linter(s) to run when a triggered file is modified.
- Targets(s) to pass to the linters (can be files or directories).
An example for ansible-lint:
lint: enabled: - [email protected] triggers: - linters: - ansible-lint paths: - ansible # A directory targets: - ansible # A directory
Triggered linters will also be run when executing trunk check with --everything so long as a file exists that matches one of the listed paths.
You may use "." as a target to run on the entire repo instead of an isolated directory.
By default, trunk only lints files up to 4 MiB in size. To override this globally, specify a
lint: default_max_file_size: 1048576 # Bytes
To override this for a specific linter, specify a
max_file_size in its definition:
lint: definitions: - name: prettier max_file_size: 2097152 # Bytes
Hold the line mode
Trunk supports two values here:
word. When using
line mode, any modified line will result in all issues on that line showing up as
new issues. When using
word mode, Trunk will then run further analysis on modified sections of files to try to find more issues that should be
existing rather than
lint: hold_the_line_mode: word
Updated 29 days ago