doc: please document "asdf global" replacement - how do i access the installed tools?

[alexanderankin]

How can we improve the documentation?

I used to use global a lot. Now i suppose I must litter my aliases file with things like this?

alias helm=~/.asdf/installs/helm/3.17.1/bin/helm

please help!

[Stratus3D]

Hi @alexanderankin can you please provide more context here?

No, you should not need to define aliases to use asdf-installed tools like helm. If you've configured asdf properly shims should already be on your $PATH and your shell should pick them up automatically. If that's not happening something is not configured right.

Try running this to see what is on your path for helm: type -a helm. An asdf shim path should be listed first.

[alexanderankin]

$ type -a helm
-bash: type: helm: not found
$ type asdf
asdf is /opt/homebrew/bin/asdf

[joaquinipar]

It's way more confusing than before. Why changing something that just works? 🤷‍♂️

[Stratus3D]

@alexanderankin so the shims directory is not on your path. Check step 2 instructions for your shell and make sure you've got code in your shells RC file to add the shims directory to your path. Once you get the shims directory on your path it should work.

[Beyarz]

Sounds like you're missing this

[alexanderankin]

very tricky migration and i did not understand it but it seems to have finally worked after changing this, building from source and putting asdf in my path elsewhere:

alexanderankin/dotfiles@812c362

commit 812c362f9bd82298459282b8692bbf66df26456e

Date:   Sat Mar 8 11:15:30 2025 -0500

    asdf

diff --git a/.bashrc b/.bashrc
index d1cf7d3..e94dbc7 100644
--- a/.bashrc
+++ b/.bashrc
@@ -176,8 +176,18 @@ test -f /usr/bin/terraform && complete -C /usr/bin/terraform terraform
 command -v rbenv > /dev/null && eval "$(rbenv init -)"
 
 
-[[ -f ~/.asdf/asdf.sh ]] && . ~/.asdf/asdf.sh
-[[ -f ~/.asdf/completions/asdf.bash ]] && . ~/.asdf/completions/asdf.bash
+# asdf was rewritten in go in version 0.16
+command -v asdf > /dev/null && {
+  export ASDF_DATA_DIR=~/.asdf
+  export PATH="$PATH:$ASDF_DATA_DIR/shims"
+} || {
+  alias setup_asdf="git clone https://github.com/asdf-vm/asdf.git ~/.asdf && cd ~/.asdf && make"
+  alias download_asdf="curl -fSsL 'https://api.github.com/repos/asdf-vm/asdf/releases' | jq .[0].assets[].browser_download_url -r"
+}
+
+# previous version of asdf were shell utilities:
+#[[ -f ~/.asdf/asdf.sh ]] && . ~/.asdf/asdf.sh
+#[[ -f ~/.asdf/completions/asdf.bash ]] && . ~/.asdf/completions/asdf.bash
 
 
 # add Pulumi to the PATH

the unfortunate part of this is that to update asdf i need to go TO my data dir, which i wish i didnt have to do, but oh well. worse would be if the next migration any more confusing.

[alexanderankin]

ok so shim is on the path and fresh install on new machine leads to "No version is set for command X" followed by lines: "Consider adding one of the following versions in your config file..."

[alexanderankin]

<sarcasm>is there some kind of evil plot to litter our computers with .tool-versions or is there a workaround/fork without this need?</sarcasm>

on a more serious note, is what global was doing was just putting .tool-versions in the home folder? so i can just cd and run "set" commands like i would "global" commands?

[andrecloutier]

on a more serious note, is what global was doing was just putting .tool-versions in the home folder?

That's my understanding of what the replacement to global does.

I noticed that in the link to your dotfile, you're setting export ASDF_DATA_DIR="~/.asdf". Note that this is not the same as export ASDF_DATA_DIR=~/.asdf. The last one is what you should be using if you insist on using ~ rather than export ASDF_DATA_DIR="$HOME/.asdf".

Also providing us the output of asdf info will help us troubleshoot the issue with you.

[obahareth]

asdf info
OS:
Darwin obahareth-m3-mbp.local 24.0.0 Darwin Kernel Version 24.0.0: Tue Sep 24 23:35:10 PDT 2024; root:xnu-11215.1.12~1/RELEASE_ARM64_T6031 arm64

SHELL:
fish, version 3.7.0

BASH VERSION:
3.2.57(1)-release

ASDF VERSION:
0.16.5

ASDF INTERNAL VARIABLES:
ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions
ASDF_DATA_DIR=/Users/obahareth/.asdf
ASDF_CONFIG_FILE=/Users/obahareth/.asdfrc

ASDF INSTALLED PLUGINS:
nodejs    https://github.com/asdf-vm/asdf-nodejs.git c5b7c40ea9ffc3470f44b6cf04a21e45dd6f81de
ruby      https://github.com/asdf-vm/asdf-ruby.git   c4c9674a7769dfe1cdadfcb40eddb3b15269ca22

Added to my path like so (I use fish)

set -x ASDF_DATA_DIR "/Users/obahareth/.asdf"
fish_add_path "/Users/obahareth/.asdf/shims"

I am having the issues due to losing the global command. I tried putting a .tool-versions in my home folder with ruby 3.4.1 as my default Ruby (this was working pre-upgrade). However each folder I access when I try to run ruby --version I get this:

ruby --version
No version is set for command ruby
Consider adding one of the following versions in your config file at /Users/obahareth/Development/current_folder/.tool-versions
ruby 3.3.0

This is my ~/.tool-versions file

cat $HOME/.tool-versions
ruby 3.4.1
nodejs 22.14.0

Also in my editors (VS Code, Cursor, Windsurf) where I was using my Ruby path and Bundler path broke and no longer works.

Settings like this in VS Code:

"standardRuby.commandPath": "/Users/obahareth/.asdf/shims/standardrb",
  "rubyLsp.rubyVersionManager": {
        "asdfExecutablePath": "/opt/homebrew/opt/asdf/libexec/bin/asdf",
        "identifier": "asdf"
    }

All of these were working fine before the upgrade.

EDIT:
I also tried the fish setup mentioned here without any change.
https://asdf-vm.com/guide/getting-started.html

[alexanderankin]

i had to do a lot of restarting my shell to make sure all the asdf's in it were the real new binary, maybe try fully uninstalling and installing by

curl -fSsL 'https://api.github.com/repos/asdf-vm/asdf/releases' | jq .[0].assets[].browser_download_url -r

wget and tar xvzf on the correct url for your system which is

https://github.com/asdf-vm/asdf/releases/download/v0.16.6/asdf-v0.16.6-darwin-amd64.tar.gz

from what i can tell

[alexanderankin]

the above command is part of my standard asdf setup on new computers:

command -v asdf > /dev/null && {
  export ASDF_DATA_DIR=~/.asdf
  export PATH="$PATH:$ASDF_DATA_DIR/shims"
} || {
  alias setup_asdf="git clone https://github.com/asdf-vm/asdf.git ~/.asdf && cd ~/.asdf && make" # i don't actually use this
  alias download_asdf="curl -fSsL 'https://api.github.com/repos/asdf-vm/asdf/releases' | jq .[0].assets[].browser_download_url -r"
}

[obahareth]

I think my Ruby install somehow broke with the asdf upgrade and I was affected by this:
#1910

[Stratus3D]

Hi everyone, sorry for the late reply here. There were a couple bugs that affected plugin management (see my comment here #1910 (comment)). These issues really affected the upgrade process to 0.16.x versions but they have all been fixed by the latest version (0.17.0), so please upgrade as soon as you can.

asdf global and asdf local have been replaced by asdf set. See the breaking changes on the upgrade guide for the reasoning on this - https://asdf-vm.com/guide/upgrading-to-v0-16.html#asdf-global-and-asdf-local-commands-have-been-replaced-with-asdf-set

Here is the mapping of old command to new:

• asdf global => asdf set --home
• asdf local => asdf set