From a84e4f0aaf3d4cacd88145c3f16f768e1cfcfc6c Mon Sep 17 00:00:00 2001
From: Edwin Kofler <edwin@kofler.dev>
Date: Fri, 26 May 2023 23:06:16 -0700
Subject: [PATCH] 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                       | 30 ++++++++++++++++++++++++++++++
 docs/guide/getting-started.md |  8 +++++++-
 2 files changed, 37 insertions(+), 1 deletion(-)

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= . "<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!