Tools: asdf

asdf is a tool version manager that integrates with your shell and automatically executes the correct tool version based on your configuration (which is specified in the .tool-versions file.)

The classic use case is that you want to seamlessly execute the correct tool version without futzing with your setup each time you switch projects. It’s a huge time saver and you can commit the .tool-versions file into source control for easy team coordination.

NOTE: asdf does not manage environment variables.

Resources

Official documentation: https://asdf-vm.com/

Fig has a useful quick reference: https://fig.io/manual/asdf

Concepts

• Core: The base asdf installation provides a minimal framework.
• Plugins: You will need to install a plugin for each tool that you want to manage.
• Versions: For each plugin you can install multiple versions of the tool.
• Configuration: The tool version executed is determined by the configuration specified in the .tool-versions file.

Installing

This assumes you use Homebrew on a Mac (check the official doc for alternate approaches).

First install the dependencies (you may already have these):

• brew install coreutils curl git

And then install asdf itself:

• brew install asdf

Finally, integrate with your shell (zsh in my case):

• Be sure to check the asdf documentation first, but in my case I ran the following command:
• echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc
• Which added the following line to my .zshrc file:
• . /opt/homebrew/opt/asdf/libexec/asdf.sh

Core

The asdf core only provides a framework for the execution of plugins. You will need to install a plugin for each tool that you wish to use.

A sample of the core asdf commands:

• asdf list display the list of plugins and versions installed. The version that will be used based on your current directory will be indicated by an asterisk.
• asdf shim-versions <command> lists the plugins and versions that provide shims for a particular command, e.g. asdf shim-versions go
• asdf info displays environment info useful for debugging along with a list of all plugins that are installed

Plugins

For each tool that you wish to use through asdf you will need to install a plugin.

Some plugin commands:

• asdf plugin-list-all list all available plugins.
• asdf plugin list list plugins installed on your system.
• asdf plugin list --urls if you want to know where they were installed from.
• asdf plugin add <name> <git-url> add a plugin.
• asdf plugin update <name> update a plugin.
• asdf plugin update --all update all plugins.
• asdf plugin remove <name> remove a plugin.

Plugins I use

Add plugins using the asdf plugin add <name> <git-url> command.

• ruby: https://github.com/asdf-vm/asdf-ruby.git
• golang: https://github.com/nklmilojevic/asdf-hugo.git
• nodejs: https://github.com/asdf-vm/asdf-nodejs.git
• hugo: https://github.com/nklmilojevic/asdf-hugo.git

Versions

Once a plugin is installed you will then need to install specific versions of that tool.

Some version commands:

• asdf install <name> <version> to install a specific version of a tool. E.g. asdf install golang 1.19.3
• asdf install golang latest to install the latest version of a tool
• asdf install golang latest:1.19 to install the latest stable version of a tool
• asdf list <name> to list installed versions of a specific tool

Configuration

asdf will use the tool version specified in the .tool-versions file in the current directory. If the .tool-versions file does not exist in the current directory, or if there is no entry for the tool, asdf will cascade up the directory tree until it finds the first matching entry. If not matching entry is found, it will use the latest installed version of the tool.

In this way, the .tool-versions file in the root directory acts as a set of defaults. You can set the version by editing the .tool-versions file directly or using the asdf global <name> <version> command. You can tell asdf to use the latest installed tool version by using latest for the <version>.

You would normally have a .tool-versions file at the base of a project and this file should be committed to version control to ensure all team members are using the agreed version of the various tools.

asdf has the ability to use the system installed version of a tool by indicating system as the version. Of course, this only applies to tools that are installed using asdf. Tools that are not installed using asdf would naturally default to the system installed version.

Here is an example .tool-versions file:

# asdf tool versions
golang 1.21.1
hugo 0.119.0
nodejs 20.5.0
ruby 3.2.2