Configuration
Let's look at how to configure
trunk tools
.Tools are configured in the
tools
section of trunk.yaml
. As with other settings, you can override these values in your User YAML.tools:
auto_sync: false # whether shims should be hot-reloaded off config changes.
enabled:
disabled:
- gt
definitions:
- name: gh
download: gh
known_good_version: 2.27.0
environment:
- name: PATH
list: ["${tool}/bin"]
shims: [gh]
Like with actions and linters, we have a (versioned)
enabled
section and a disabled
section, which can be manipulated using trunk tools enable/disable
. There is also a list of definitions
, which are merged across your trunk.yaml
, user.yaml
, as well as any plugins that you use.auto_sync
controls whether or not trunk
automatically installs your tools for you when your config changes. This defaults to true
. Note that the daemon must be running with the monitor in order for this to function properly.Each tool definition shares a set of attributes -
name
: the name of the tool. Must be unique.known_good_version
: This is a default version to initialize the tool at. Required.shims
: this is a list of binaries exposed by the tool. Each of these will correspond to one identically named executable installed in .trunk/tools.
In the most common case, there is exactly one shim matching the name of the tool. We'll discuss other cases below.environment
: You can specify an environment for the tool. We provide the ${tool}
template argument that resolves to the installation directory of the tool. By default, we prepend this to $PATH
within the shim script, so this is used to locate the binary. For legacy reasons, ${linter}
also resolves to this directory.Otherwise, if the tool has a
runtime
attribute, the runtime's environment is merged in (discussed in the examples below).Broadly speaking, there are 3 kinds of tools - download, package, and runtime-based tools. We'll look at each one in turn:
Download-based tools are straightforward: They reference a named download configuration in the global
downloads
section. Here is an example:downloads:
- name: gh
downloads:
- os:
linux: linux
cpu:
x86_64: amd64
arm_64: arm64
url: https://github.com/cli/cli/releases/download/v${version}/gh_${version}_${os}_${cpu}.tar.gz
strip_components: 1
- os:
windows: windows
cpu:
x86_64: amd64
arm_64: arm64
url: https://github.com/cli/cli/releases/download/v${version}/gh_${version}_${os}_${cpu}.zip
strip_components: 1
# macOS releases since 2.28.0 started using .zip instead of .tar.gz
- os:
macos: macOS
cpu:
x86_64: amd64
arm_64: arm64
url: https://github.com/cli/cli/releases/download/v${version}/gh_${version}_${os}_${cpu}.zip
strip_components: 1
version: ">=2.28.0"
- os:
macos: macOS
cpu:
x86_64: amd64
arm_64: arm64
url: https://github.com/cli/cli/releases/download/v${version}/gh_${version}_${os}_${cpu}.tar.gz
strip_components: 1
tools:
definitions:
- name: gh
download: gh
known_good_version: 2.27.0
environment:
- name: PATH
list: ["${tool}/bin"]
shims: [gh]
Note that for the downloaded archive, the binary named
gh
is inside the bin
directory, so we use the environment to point the $PATH
there.Package-based tools depend on specified
package
and runtime
attributes. Here is an example of configuring mypy
as a tool:tools:
definitions:
- name: mypy
runtime: python
package: mypy
shims: [mypy]
known_good_version: 0.931
extra_packages:
- types-[email protected]
- types-request
extra_packages
behaves equivalently to a package file like requirements.txt
for Python or package.json
for Node. They can be optionally pinned at versions.The version of the primary package (in this case,
mypy
) is specified in the tools.enabled
. So to enable the mypy
tool at 1.4.0
, list it as - [email protected]
.Runtime-based tools are a special case that are not explicitly defined. Rather, each runtime object exposes a set of
shims
(just like tool
definitions) that are automatically installed in the shims
directory for enabled runtimes. Thus you can run python
, pip
, etc as trunk
-managed tools.If this is disruptive to your workflow, you may disable runtime shims in the
tools.disabled
section by referring to the name of the runtime (go, node, python,...)
. Runtimes cannot be enabled or versioned via the tools.enabled
section, however.Last modified 1mo ago