Show install status in which-formula

- Help users identify already-installed providers in command searches
- Preserve plain formula output for non-TTY consumers
- Share `executables.txt` fetching and parsing across Bash commands
- Keep Bash formatting helpers aligned with their Ruby counterparts
- Limit added integration coverage to core command behaviour
- Avoid creating repo-root `Cellar` in command specs

Author: MikeMcQuaid

AGENTS.md

@@ -27,7 +27,7 @@ When running Ruby directly (e.g. `ruby -e ...`, `gem`, profiling tools), never u
 ### Development Flow
 
 - Write new code (using Sorbet `sig` type signatures and `typed: strict` for new files).
-- Write new tests (avoid more than one `:integration_test` per file for speed). Try `typed: true` as a baseline but revert to `typed: false` if there are not easily fixable errors.
+- Write new tests (avoid more than one `:integration_test` per command for speed; add another only for essential core functionality in essential non-developer commands). Try `typed: true` as a baseline but revert to `typed: false` if there are not easily fixable errors.
   Write fast tests by preferring a single `expect` per unit test and combine expectations in a single test when it is an integration test or has non-trivial `before` for test setup.
 - When adding or tightening tests, verify them with a red/green cycle using the exact `--only=file:line` target for the example you changed.
 - Formula classes created in specs may be frozen; avoid stubbing class methods on them with RSpec mocks and prefer instance-level stubs or test setup that does not require class-method stubbing.
@@ -59,3 +59,4 @@ When running Ruby directly (e.g. `ruby -e ...`, `gem`, profiling tools), never u
 9. Inline new or existing methods as methods or local variables unless they are reused 2+ times or needed for unit tests.
 10. Avoid `T.must`; prefer explicit nil checks or APIs that return non-nil values.
 11. Keep `extend/os/*` prepends as thin as possible; put the `prepend` in the OS-specific `linux` or `macos` file rather than the shared `extend/os/*` loader with an inline `if`, and prefer putting substantive logic in shared code outside `extend/` when practical so it can be tested on all platforms instead of relying on `:needs_linux` or `:needs_macos` specs.
+12. When Bash logic mirrors Ruby logic, keep both implementations in sync and add two-way comments naming the matching Ruby and Bash locations; keep matching helper filenames aligned where practical.

Library/Homebrew/brew.sh

@@ -229,7 +229,7 @@ esac
 ##### Next, define all other helper functions.
 #####
 
-source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
+source "${HOMEBREW_LIBRARY}/Homebrew/utils.sh"
 
 check-run-command-as-root() {
   [[ "${EUID}" == 0 || "${UID}" == 0 ]] || return

Library/Homebrew/cmd/exec.sh

@@ -1,7 +1,7 @@
 # Documentation defined in Library/Homebrew/cmd/exec.rb
 
 # shellcheck disable=SC2154
-source "${HOMEBREW_LIBRARY}/Homebrew/cmd/which-formula.sh"
+source "${HOMEBREW_LIBRARY}/Homebrew/utils/executables.sh"
 
 exec-formula-name() {
   local formula="$1"
@@ -151,35 +151,20 @@ homebrew-exec() {
     download_and_cache_executables_file >&2
 
     local -a matching_formulae=()
-    local cmds_text line selected_formula formula
+    local selected_formula formula
     selected_formula=""
     # Some executables are provided by multiple formulae. Prefer an already
     # installed provider to avoid unnecessary installs; otherwise use the first
     # provider listed by the database.
-    while read -r line
+    while read -r formula
     do
-      [[ "${line}" == *:* ]] || continue
-
-      # `executables.txt` lines are `formula(version):exe exe...`. Use Bash's
-      # prefix/suffix removal instead of splitting with `IFS`, so executable
-      # lists are kept as one string for whole-word matching below.
-      formula="${line%%:*}"
-      cmds_text="${line#*:}"
-      [[ -z "${formula}" ]] && continue
-      [[ -z "${cmds_text}" ]] && continue
-
-      # Padding both sides with spaces avoids matching `foo` inside `foobar`.
-      if [[ " ${cmds_text} " == *" ${executable} "* ]]
-      then
-        formula="${formula%\(*}"
-        matching_formulae+=("${formula}")
+      matching_formulae+=("${formula}")
 
-        if [[ -z "${selected_formula}" ]] && exec-formula-installed "${formula}"
-        then
-          selected_formula="${formula}"
-        fi
+      if [[ -z "${selected_formula}" ]] && exec-formula-installed "${formula}"
+      then
+        selected_formula="${formula}"
       fi
-    done <"${DATABASE_FILE}" 2>/dev/null
+    done < <(formulae_containing_executable "${executable}")
 
     [[ "${#matching_formulae[@]}" -gt 0 ]] || odie "No Homebrew formula found for \`${executable}\`."
 

Library/Homebrew/cmd/setup-ruby.sh

@@ -4,7 +4,7 @@
 # HOMEBREW_BREW_FILE is set by extend/ENV/super.rb
 # shellcheck disable=SC2154
 homebrew-setup-ruby() {
-  source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
+  source "${HOMEBREW_LIBRARY}/Homebrew/utils.sh"
   source "${HOMEBREW_LIBRARY}/Homebrew/utils/ruby.sh"
   setup-ruby-path
 

Library/Homebrew/cmd/update.sh

@@ -11,6 +11,7 @@
 # HOMEBREW_FORCE_BREWED_CURL, HOMEBREW_FORCE_BREWED_GIT,
 # HOMEBREW_SYSTEM_CURL_TOO_OLD, HOMEBREW_USER_AGENT_CURL are set by brew.sh
 # shellcheck disable=SC2154
+source "${HOMEBREW_LIBRARY}/Homebrew/utils/executables.sh"
 source "${HOMEBREW_LIBRARY}/Homebrew/utils/lock.sh"
 
 macos_version_name() {
@@ -419,20 +420,16 @@ fetch_api_file() {
     echo "Checking if we need to fetch ${filename}..."
   fi
 
-  JSON_URLS=()
-  if [[ -n "${HOMEBREW_API_DOMAIN}" && "${HOMEBREW_API_DOMAIN}" != "${HOMEBREW_API_DEFAULT_DOMAIN}" ]]
-  then
-    JSON_URLS=("${HOMEBREW_API_DOMAIN}/${filename}")
-  fi
-
-  JSON_URLS+=("${HOMEBREW_API_DEFAULT_DOMAIN}/${filename}")
-  for json_url in "${JSON_URLS[@]}"
+  local arg json_url
+  while read -r json_url
   do
     time_cond=()
-    if [[ -s "${cache_path}" ]]
-    then
-      time_cond=("--time-cond" "${cache_path}")
-    fi
+    while read -r arg
+    do
+      time_cond+=("${arg}")
+    done < <(api_time_cond_args "${cache_path}")
+    # Keep curl request handling in sync with `download_and_cache_executables_file`
+    # in Library/Homebrew/utils/executables.sh.
     curl \
       "${CURL_DISABLE_CURLRC_ARGS[@]}" \
       --fail --compressed --silent \
@@ -443,7 +440,7 @@ fetch_api_file() {
       "${json_url}"
     curl_exit_code=$?
     [[ ${curl_exit_code} -eq 0 ]] && break
-  done
+  done < <(api_urls "${filename}")
 
   if [[ -n ${is_formula_file} ]] && [[ -f "${api_cache}/formula_names.txt" ]]
   then
@@ -479,6 +476,7 @@ fetch_api_file() {
 }
 
 homebrew-update() {
+  local arg
   local option
   local DIR
   local UPSTREAM_BRANCH
@@ -652,16 +650,11 @@ EOS
   fi
 
   # HOMEBREW_CURLRC is optionally defined in the user environment.
-  # shellcheck disable=SC2153
-  if [[ -z "${HOMEBREW_CURLRC}" ]]
-  then
-    CURL_DISABLE_CURLRC_ARGS=(-q)
-  elif [[ "${HOMEBREW_CURLRC}" == /* ]]
-  then
-    CURL_DISABLE_CURLRC_ARGS=(-q --config "${HOMEBREW_CURLRC}")
-  else
-    CURL_DISABLE_CURLRC_ARGS=()
-  fi
+  CURL_DISABLE_CURLRC_ARGS=()
+  while read -r arg
+  do
+    CURL_DISABLE_CURLRC_ARGS+=("${arg}")
+  done < <(api_curlrc_args)
 
   # only allow one instance of brew update
   lock update
@@ -1042,7 +1035,8 @@ EOS
   # Update executables.txt if the user has ever run `brew which-formula` before.
   if [[ -n "${HOMEBREW_FETCH_EXECUTABLES_TXT}" ]]
   then
-    fetch_api_file "internal/executables.txt" "${update_failed_file}"
+    ohai "Downloading executables.txt"
+    fetch_api_file "${HOMEBREW_EXECUTABLES_TXT_ENDPOINT}" "${update_failed_file}"
   fi
 
   if [[ -f "${update_failed_file}" ]]

Library/Homebrew/cmd/which-formula.sh

@@ -1,72 +1,7 @@
 # Documentation defined in Library/Homebrew/cmd/which-formula.rb
 
-# HOMEBREW_CACHE is set by utils/ruby.sh
-# HOMEBREW_LIBRARY is set by bin/brew
-# HOMEBREW_API_DEFAULT_DOMAIN HOMEBREW_CURL_SPEED_LIMIT  HOMEBREW_CURL_SPEED_TIME HOMEBREW_USER_AGENT_CURL are set by brew.sh
 # shellcheck disable=SC2154
-ENDPOINT="internal/executables.txt"
-DATABASE_FILE="${HOMEBREW_CACHE}/api/${ENDPOINT}"
-
-is_formula_installed() {
-  local name="$1"
-  if [[ -d "${HOMEBREW_CELLAR}/${name}" ]]
-  then
-    return 0
-  else
-    return 1
-  fi
-}
-
-is_file_fresh() {
-  if [[ -n "${HOMEBREW_MACOS}" ]]
-  then
-    STAT_PRINTF=("/usr/bin/stat" "-f")
-  else
-    STAT_PRINTF=("/usr/bin/stat" "-c")
-  fi
-
-  local file_mtime
-  local current_time
-  local auto_update_secs
-
-  file_mtime=$("${STAT_PRINTF[@]}" %m "${DATABASE_FILE}")
-  current_time=$(date +%s)
-  auto_update_secs=${HOMEBREW_API_AUTO_UPDATE_SECS:-450}
-
-  [[ $((current_time - auto_update_secs)) -lt ${file_mtime} ]]
-}
-
-download_and_cache_executables_file() {
-  source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
-  if [[ -s "${DATABASE_FILE}" ]] && ([[ -n "${HOMEBREW_SKIP_UPDATE}" ]] || is_file_fresh)
-  then
-    return
-  else
-    local url
-    url="${HOMEBREW_API_DEFAULT_DOMAIN}/${ENDPOINT}"
-
-    if [[ -n "${CI}" ]]
-    then
-      max_time=""
-      retries="3"
-    else
-      max_time=10
-      retries=0
-    fi
-    mkdir -p "${DATABASE_FILE%/*}"
-    ${HOMEBREW_CURL} \
-      --compressed \
-      --speed-limit "${HOMEBREW_CURL_SPEED_LIMIT}" --speed-time "${HOMEBREW_CURL_SPEED_TIME}" \
-      --location --remote-time --output "${DATABASE_FILE}" \
-      ${max_time:+--max-time "${max_time}"} \
-      ${retries:+--retry "${retries}" --retry-delay 0 --retry-max-time 60} \
-      --user-agent "${HOMEBREW_USER_AGENT_CURL}" \
-      "${url}"
-    touch "${DATABASE_FILE}"
-
-    git config --file="${HOMEBREW_REPOSITORY}/.git/config" --bool homebrew.commandnotfound true 2>/dev/null
-  fi
-}
+source "${HOMEBREW_LIBRARY}/Homebrew/utils/executables.sh"
 
 homebrew-which-formula() {
   local args=()
@@ -105,19 +40,11 @@ homebrew-which-formula() {
     download_and_cache_executables_file
 
     local formulae=()
-    local formula cmds_text
-
-    while IFS=':' read -r formula cmds_text
+    local formula
+    while read -r formula
     do
-      [[ -z "${formula}" ]] && continue
-      [[ -z "${cmds_text}" ]] && continue
-
-      if [[ " ${cmds_text} " == *" ${cmd} "* ]]
-      then
-        formula="${formula%\(*}"
-        formulae+=("${formula}")
-      fi
-    done <"${DATABASE_FILE}" 2>/dev/null
+      formulae+=("${formula}")
+    done < <(formulae_containing_executable "${cmd}")
 
     [[ ${#formulae[@]} -eq 0 ]] && return 1
 
@@ -126,7 +53,7 @@ homebrew-which-formula() {
       local filtered_formulae=()
       for formula in "${formulae[@]}"
       do
-        if ! is_formula_installed "${formula}"
+        if [[ ! -d "${HOMEBREW_CELLAR}/${formula}" ]]
         then
           filtered_formulae+=("${formula}")
         fi
@@ -147,7 +74,10 @@ homebrew-which-formula() {
         echo "Try: brew install <selected formula>"
       fi
     else
-      printf '%s\n' "${formulae[@]}"
+      for formula in "${formulae[@]}"
+      do
+        print_formula_install_status "${formula}"
+      done
     fi
   done
 }

Library/Homebrew/extend/kernel.rb

@@ -86,6 +86,7 @@ def quiet_system(cmd, argv0 = nil, *args)
   # Find a command.
   #
   # @api public
+  # Keep in sync with `which` in Library/Homebrew/utils.sh.
   sig { params(cmd: String, path: PATH::Elements).returns(T.nilable(Pathname)) }
   def which(cmd, path = ENV.fetch("PATH"))
     PATH.new(path).each do |p|

Library/Homebrew/list.sh

@@ -17,7 +17,7 @@ homebrew-list() {
   then
     tty=1
     ls_args+=("-Cq")
-    source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
+    source "${HOMEBREW_LIBRARY}/Homebrew/utils.sh"
     ls_env+=("COLUMNS=$(columns)")
   fi