diff --git a/asdf.sh b/asdf.sh index a19265c0a..2c0dab70c 100644 --- a/asdf.sh +++ b/asdf.sh @@ -59,6 +59,36 @@ fi _asdf_bin="$ASDF_DIR/bin" _asdf_shims="${ASDF_DATA_DIR:-$HOME/.asdf}/shims" +# If ASDF_FORCE_PREPEND is set, remove any existing instances of asdf from PATH so +# the prepending done after is always at the frontmost part of the PATH. +if [ -n "${ASDF_FORCE_PREPEND+x}" ]; then + if [ -n "$BASH_VERSION" ] || [ -n "$ZSH_VERSION" ]; then + # shellcheck disable=SC3060 + case ":$PATH:" in + *":${_asdf_bin}:"*) PATH=${PATH//$_asdf_bin:/} ;; + esac + # shellcheck disable=SC3060 + case ":$PATH:" in + *":${_asdf_shims}:"*) PATH=${PATH//$_asdf_shims:/} ;; + esac + else + _path=${PATH}: + _new_path= + while [ -n "$_path" ]; do + _part=${_path%%:*} + _path=${_path#*:} + + if [ "$_part" = "$_asdf_bin" ] || [ "$_part" = "$_asdf_shims" ]; then + continue + fi + + _new_path="$_new_path${_new_path:+:}$_part" + done + PATH=$_new_path + unset -v _path _new_path _part + fi +fi + case ":$PATH:" in *":$_asdf_bin:"*) : ;; *) PATH="$_asdf_bin:$PATH" ;; diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 38d679c18..06c2839be 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -51,7 +51,9 @@ We highly recommend using the official `git` method. ## 3. Install asdf -There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system: +There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system. + +**macOS users, be sure to read the warning about `path_helper` at the end of this section.** ::: details Bash & Git @@ -359,6 +361,10 @@ export ASDF_DIR="/opt/asdf-vm" `asdf` scripts need to be sourced **after** you have set your `$PATH` and **after** you have sourced your framework (oh-my-zsh etc). +::: warning +On macOS, starting a Bash or Zsh shell automatically calls a utility called `path_helper`. `path_helper` has poor logic and rearranges items in `PATH` (and `MANPATH`) in a bad way. To workaround this, set the `ASDF_FORCE_PREPEND` variable before sourcing `asdf`, like so: `ASDF_FORCE_PREPEND= . "/asdf.sh"`. +::: + Restart your shell so that `PATH` changes take effect. Opening a new terminal tab will usually do it. ## Core Installation Complete!