asdf. A Developer's Best Friend
Jon Sully
4 Minutes
Who needs this tool? Everyone. That was easy!...
This post won’t be a particularly long one, I just want to introduce you all to the greatest not-super-popular (yet) tool on the planet. It’s called asdf and it’s an open source tool for version management of other tools. asdf is available on GitHub and to put it shortly, it allows you to have multiple versions of a single tool installed on your machine at the same time, using only the one you specifically want for any particular project. Let me run you through an example, and the reason I initially got asdf. Ruby.
When I first started with Ruby, I needed to install it. In their wisdom, my new coworkers at the time encouraged me to install Ruby through a version manager rather than having a base install for my operating system. Installing Ruby through asdf means that for any particular project, I do following:
cd ~/repos/my-new-project asdf local ruby 2.5.0
It pretty much does what it sounds like it does. I’m telling asdf that for this local directory (which includes children directories if you need), I want to use Ruby, and use version 2.5.0 of Ruby. Easy enough right? It’s particularly powerful when I have multiple versions of Ruby installed through asdf. Say I want to upgrade my project to a newer version of Ruby but I want to check to see if it’ll work. All I have to do is run sh>asdf local ruby 2.5.3 and from there on out, when I run sh>ruby on the command line, it will reference Ruby 2.5.3. That’s pretty standard usage for Ruby version managers, but what else can asdf do?
(It’s worth noting for Ruby specifically since there is also rvm and rbenv, you can tell asdf to use ‘legacy version files’, at which point it will use, respect, and write to, a .ruby-version file.)
The beauty of asdf is that it can version manage all of your tools at once. Do some Ruby projects but also do some .NET Core projects but also use the Node runtime sometimes? No problem, asdf can manage all of those for you. Say you’re starting a new project and implementing it with a .NET Core back end, React front end, and Postgres for your database. asdf’s got you.
asdf local nodejs 10.2.0 asdf local dotnet-core 2.2.100 asdf local postgres 11.1
but how expansive is the reach of asdf? Since support for languages and frameworks is achieved through the creation of open source plugins, the list is pretty long. See below.
What can it manage?
Here’s the beauty of asdf. At time of writing, here are all the languages/frameworks/tools that asdf can version-manage (directly off their page)
Who needs this tool
Everyone.
That was easy!
How to install it
If you’re on a macOS machine, you can feel free to follow the standard installation, but you can also follow the simpler: sh>brew install asdf
For everyone else, asdf does a great job of documentation and has a thorough README on their repository. Give it a read and follow the directions. I would highly recommend removing any current versions of tools that you intend to manage with asdf that you currently have installed directly on the operating system somewhere. asdf should be able to handle it if you don’t, but better safe than sorry.
Since asdf does a lot with mutating shell commands, be wary that you should probably restart your shell after you install
How to use it
I like to break asdf up into a few layers in my head. The first layer is plugins. These are the languages that your local instance of asdf supports version-controlling. Things like Ruby or .NET Core. In order to version control Ruby or .NET Core, you need to install the appropriate plugin. Luckily, installing plugins is super easy.
# Show all available plugins (the list above) asdf plugin-list-all 1password https://github.com/samtgarson/asdf-1password.git R https://github.com/iroddis/asdf-R.git adr-tools https://gitlab.com/td7x/asdf/adr-tools.git aks-engine https://github.com/robsonpeixoto/asdf-aks-engine.git alp https://github.com/asdf-community/asdf-alp.git argo https://github.com/sudermanjr/asdf-argo.git argocd https://github.com/beardix/asdf-argocd.git etc... # Install a plugin asdf plugin-add dotnet-core # or asdf plugin-add ruby
The next layer down is versions. This is where you install particular versions of that plugin/tool. It looks like this:
# Show all available versions for a particular plugin asdf list-all ruby 1.8.5-p52 1.8.5-p113 1.8.5-p114 1.8.5-p115 1.8.5-p231 1.8.6 1.8.6-p36 1.8.6-p110 1.8.6-p111 1.8.6-p114 1.8.6-p230 etc.. (to current) asdf list-all dotnet-core 1.1.14 1.1.14 2.1.202 2.2.207 2.1.806 3.0.103 3.1.300 5.0.100-preview.4.20258.7 # Install a particular version(s) asdf install ruby 2.5.0 # or asdf install ruby 2.5.3 # or asdf install dotnet-core 2.2.100
Finally, the last layer is bindings, although that name comes exclusively from me and is not in their documentation. It’s at this layer where you tell asdf which tool and version to use in a particular project directory.
# List current bindings for directory asdf current nodejs 10.16.3 (set by /Users/somebody/repos/proj-name/.tool-versions) ruby No version set for ruby; please run `asdf <global | local> ruby <version>` # Bind up some tools/versions asdf local ruby 2.5.0 # and/or asdf local node 10.2.0
That’s all there is to it! Enjoy your modular and extensible multi-tool version management!
Other things
asdf does support global defaults for the plugins you have installed. If you set those, they will manifest into a .tool-versions file at your sh>$HOME directory. I do not recommend setting global defaults. It can lead to confusion later. Be intentional about the tools and versions you use 😊