asdf

extendable version manager

Supported languages include Ruby, Node.js, Elixir and more. Supporting a new language is as simple as this plugin API.

SETUP

Copy-paste the following into command line:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.3.0

Depending on your OS, run the following

# For Ubuntu or other linux distros
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc

# OR for Mac OSX
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bash_profile
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bash_profile

If you use zsh or any other shell, replace .bashrc with the config file for the respective shell.

For fish, you can use the following:

echo 'source ~/.asdf/asdf.fish' >> ~/.config/fish/config.fish
mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions

For most plugins, it is good if you have installed the following packages OR their equivalent on your OS

• OS X: Install these via homebrew coreutils automake autoconf openssl libyaml readline libxslt libtool unixodbc
• Ubuntu: automake autoconf libreadline-dev libncurses-dev libssl-dev libyaml-dev libxslt-dev libffi-dev libtool unixodbc-dev
• Fedora: automake autoconf readline-devel ncurses-devel openssl-devel libyaml-devel libxslt-devel libffi-devel libtool unixODBC-devel

That's all ~! You are ready to use asdf

---

USAGE

Manage plugins

Plugins are how asdf understands how to handle different packages. Below is a list of plugins for languages. There is a super-simple API for supporting more languages.

Language	Repository	CI Status
Clojure	vic/asdf-clojure
Crystal	marciogm/asdf-crystal
D (DMD)	sylph01/asdf-dmd
Elixir	asdf-vm/asdf-elixir
Elm	vic/asdf-elm
Erlang	asdf-vm/asdf-erlang
Go	kennyp/asdf-golang
Gradle	rfrancis/asdf-gradle
Haskell	vic/asdf-haskell
Idris	vic/asdf-idris
Julia	rkyleg/asdf-julia
LFE	vic/asdf-lfe
Link (system tools)	vic/asdf-link
Lua	Stratus3D/asdf-lua
LuaJIT	smashedtoatoms/asdf-luaJIT
MongoDB	sylph01/asdf-mongodb
Nim	rfrancis/asdf-nim
Node.js	asdf-vm/asdf-nodejs
OCaml	vic/asdf-ocaml
OpenResty	smashedtoatoms/asdf-openresty
Packer	gozer/asdf-packer
PHP	odarriba/asdf-php
Postgres	smashedtoatoms/asdf-postgres
Python	tuvistavie/asdf-python
Racket	vic/asdf-racket
Rebar	Stratus3D/asdf-rebar
Redis	smashedtoatoms/asdf-redis
Riak	smashedtoatoms/asdf-riak
Ruby	asdf-vm/asdf-ruby
Rust	code-lever/asdf-rust
SBT	lerencao/asdf-sbt
Scala	mtatheonly/asdf-scala
Swift	fcrespo82/asdf-swift
Terraform	neerfri/asdf-terraform

Add a plugin

asdf plugin-add <name> <git-url>
# asdf plugin-add erlang https://github.com/asdf-vm/asdf-erlang.git

List installed plugins

asdf plugin-list
# asdf plugin-list

Remove a plugin

asdf plugin-remove <name>
# asdf plugin-remove erlang

Update plugins

asdf plugin-update --all

If you want to update a specific package, just say so.

asdf plugin-update <name>
# asdf plugin-update erlang

Manage versions

asdf install <name> <version>
# asdf install erlang 17.3

asdf current <name>
# asdf current erlang
# 17.3 (set by /Users/kim/.tool-versions)

asdf uninstall <name> <version>
# asdf uninstall erlang 17.3

If a plugin supports downloading & compiling from source, you can also do this ref:foo (replace foo with the branch/tag/commit). You'll have to use the same name when uninstalling too.

Lists installed versions

asdf list <name>
# asdf list erlang

List all available versions

asdf list-all <name>
# asdf list-all erlang

View current version

asdf current <name>
# asdf current erlang
# 17.3 (set by /Users/kim/.tool-versions)

Set current version

asdf global <name> <version>
asdf local <name> <version>
# asdf global elixir 1.2.4

global writes the version to $HOME/.tool-versions.

local writes the version to $PWD/.tool-versions, creating it if needed.

Alternatively, if you want to set a version only for the current shell session or for executing just a command under a particular tool version, you can set an environment variable like ASDF_${TOOL}_VERSION.

The following example runs tests on an Elixir project with version 1.4.0. The version format is the same supported by the .tool-versions file.

ASDF_ELIXIR_VERSION=1.4.0 mix test

The .tool-versions file

Add a .tool-versions file to your project dir and versions of those tools will be used. Global defaults can be set in the file $HOME/.tool-versions

This is what a .tool-versions file looks like:

ruby 2.2.0
nodejs 0.12.3

The versions can be in the following format:

• 0.12.3 - an actual version. Plugins that support downloading binaries, will download binaries.
• ref:v1.0.2-a or ref:39cb398vb39 - tag/commit/branch to download from github and compile
• path:/src/elixir - a path to custom compiled version of a tool to use. For use by language developers and such.
• system - this keyword causes asdf to passthrough to the version of the tool on the system that is not managed by asdf.

To install all the tools defined in a .tool-versions file run the asdf install command with no other arguments in the directory containing the .tool-versions file.

You can view/modify the file by hand or use asdf local and asdf global to manage it.

The $HOME/.asdfrc config file

Add a .asdfrc file to your home directory and asdf will use the settings specified in the file. The file should be formatted like this:

legacy_version_file = yes

Settings

• legacy_version_file - defaults to no. If set to yes it will cause plugins that support this feature to read the version files used by other version managers (e.g. .ruby-version in the case of Ruby's rbenv).

Docker images

The asdf-alpine and asdf-ubuntu projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps.

Development

To develop the project, you can simply git clone the master branch. If you want to try out your changes without making change to your installed asdf, you can set the $ASDF_DIR variable to the path where you cloned the repository, and temporarily prepend the bin and shims directory of the directory to your path.

We use bats for testing, so make sure bats test/ passes after you made your changes.

Credits

Me (@HashNuke), High-fever, cold, cough.

Copyright 2014 to the end of time (MIT License)

Maintainers

• @HashNuke
• @tuvistavie
• @Stratus3D
• @vic

---

Read the ballad.