fix: Introduce ASDF_FORCE_PREPEND variable on POSIX entrypoint

This variable forces the prepending of the asdf directories to the PATH
variable. It does this by removing existing asdf entries in PATH,
including an optimization for Bash and Zsh shells.

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" ;;

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 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= . "<path-to-asdf-directory>/asdf.sh"`.
+:::
+
 Restart your shell so that `PATH` changes take effect. Opening a new terminal tab will usually do it.
 
 ## Core Installation Complete!