From 17bfef29f2d6eeb72569c13df9a6801ecf60e9a2 Mon Sep 17 00:00:00 2001
From: Mike McQuaid <mike@mikemcquaid.com>
Date: Fri, 7 Feb 2025 13:23:52 +0000
Subject: [PATCH] brew.sh: improve HOMEBREW_FORCE_BREW_WRAPPER error message

Rather than just explaining what is happening, let's explain a bit more
why this is happening and how to fix it.
---
 Library/Homebrew/brew.sh | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Library/Homebrew/brew.sh b/Library/Homebrew/brew.sh
index 8f936dfc55..ee48f55738 100644
--- a/Library/Homebrew/brew.sh
+++ b/Library/Homebrew/brew.sh
@@ -186,27 +186,36 @@ source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
 # (i.e. not defined above this line e.g. formulae or --cellar).
 if [[ -z "${HOMEBREW_NO_FORCE_BREW_WRAPPER:-}" && -n "${HOMEBREW_FORCE_BREW_WRAPPER:-}" ]]
 then
+  HOMEBREW_FORCE_BREW_WRAPPER_WITHOUT_BREW="${HOMEBREW_FORCE_BREW_WRAPPER%/brew}"
   if [[ -z "${HOMEBREW_BREW_WRAPPER:-}" ]]
   then
     odie <<EOS
-HOMEBREW_FORCE_BREW_WRAPPER was set to
-  ${HOMEBREW_FORCE_BREW_WRAPPER}
-but HOMEBREW_BREW_WRAPPER was unset. This indicates that you are running
-  ${HOMEBREW_BREW_FILE}
-directly but should instead run
-  ${HOMEBREW_FORCE_BREW_WRAPPER}
+conflicting Homebrew wrapper configuration!
+HOMEBREW_FORCE_BREW_WRAPPER was set to ${HOMEBREW_FORCE_BREW_WRAPPER}
+but   HOMEBREW_BREW_WRAPPER was unset.
+
+$(bold "Ensure you run ${HOMEBREW_FORCE_BREW_WRAPPER} directly (not ${HOMEBREW_BREW_FILE})")!
+
+Manually setting your PATH can interfere with Homebrew wrappers.
+Ensure your shell configuration contains:
+  eval "\$(${HOMEBREW_BREW_FILE} shellenv)"
+or that ${HOMEBREW_FORCE_BREW_WRAPPER_WITHOUT_BREW} comes before ${HOMEBREW_PREFIX}/bin in your PATH:
+  export PATH="${HOMEBREW_FORCE_BREW_WRAPPER_WITHOUT_BREW}:${HOMEBREW_PREFIX}/bin:\$PATH"
 EOS
   elif [[ "${HOMEBREW_FORCE_BREW_WRAPPER}" != "${HOMEBREW_BREW_WRAPPER}" ]]
   then
     odie <<EOS
-HOMEBREW_FORCE_BREW_WRAPPER was set to
-  ${HOMEBREW_FORCE_BREW_WRAPPER}
-but HOMEBREW_BREW_WRAPPER was set to
-  ${HOMEBREW_BREW_WRAPPER}
-This indicates that you are running
-  ${HOMEBREW_BREW_FILE}
-directly but should instead run:
-  ${HOMEBREW_FORCE_BREW_WRAPPER}
+conflicting Homebrew wrapper configuration!
+HOMEBREW_FORCE_BREW_WRAPPER was set to ${HOMEBREW_FORCE_BREW_WRAPPER}
+but HOMEBREW_BREW_WRAPPER   was set to ${HOMEBREW_BREW_WRAPPER}
+
+$(bold "Ensure you run ${HOMEBREW_FORCE_BREW_WRAPPER} directly (not ${HOMEBREW_BREW_FILE})")!
+
+Manually setting your PATH can interfere with Homebrew wrappers.
+Ensure your shell configuration contains:
+  eval "\$(${HOMEBREW_BREW_FILE} shellenv)"
+or that ${HOMEBREW_FORCE_BREW_WRAPPER_WITHOUT_BREW} comes before ${HOMEBREW_PREFIX}/bin in your PATH:
+  export PATH="${HOMEBREW_FORCE_BREW_WRAPPER_WITHOUT_BREW}:${HOMEBREW_PREFIX}/bin:\$PATH"
 EOS
   fi
 fi