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