Merge pull request #17710 from Homebrew/help_bash

Library/Homebrew/brew.sh

@@ -127,6 +127,9 @@ case "$1" in
     exit 0
     ;;
 esac
+
+source "${HOMEBREW_LIBRARY}/Homebrew/help.sh"
+
 # functions that take multiple arguments or handle multiple commands.
 # doesn't need a default case as other arguments handled elsewhere.
 # shellcheck disable=SC2249
@@ -162,6 +165,10 @@ case "$@" in
     source "${HOMEBREW_LIBRARY}/Homebrew/list.sh"
     homebrew-list "$@" && exit 0
     ;;
+  # falls back to cmd/help.rb on a non-zero return
+  help | "")
+    homebrew-help "$@" && exit 0
+    ;;
 esac
 
 #####
@@ -683,6 +690,7 @@ HOMEBREW_USER_AGENT_CURL="${HOMEBREW_USER_AGENT} ${curl_name_and_version// //}"
 HOMEBREW_CURL_SPEED_LIMIT=100
 HOMEBREW_CURL_SPEED_TIME=5
 
+export HOMEBREW_HELP_MESSAGE
 export HOMEBREW_VERSION
 export HOMEBREW_MACOS_ARM_DEFAULT_PREFIX
 export HOMEBREW_LINUX_DEFAULT_PREFIX

Library/Homebrew/global.rb

@@ -3,6 +3,8 @@
 
 require_relative "startup"
 
+HOMEBREW_HELP_MESSAGE = ENV.fetch("HOMEBREW_HELP_MESSAGE").freeze
+
 HOMEBREW_API_DEFAULT_DOMAIN = ENV.fetch("HOMEBREW_API_DEFAULT_DOMAIN").freeze
 HOMEBREW_BOTTLE_DEFAULT_DOMAIN = ENV.fetch("HOMEBREW_BOTTLE_DEFAULT_DOMAIN").freeze
 HOMEBREW_BREW_DEFAULT_GIT_REMOTE = ENV.fetch("HOMEBREW_BREW_DEFAULT_GIT_REMOTE").freeze

Library/Homebrew/help.rb

@@ -7,48 +7,16 @@ require "commands"
 module Homebrew
   # Helper module for printing help output.
   module Help
-    # NOTE: Keep the length of vanilla `--help` less than 25 lines!
-    #       This is because the default Terminal height is 25 lines. Scrolling sucks
-    #       and concision is important. If more help is needed we should start
-    #       specialising help like the gem command does.
-    # NOTE: Keep lines less than 80 characters! Wrapping is just not cricket.
-    HOMEBREW_HELP = <<~EOS
-      Example usage:
-        brew search TEXT|/REGEX/
-        brew info [FORMULA|CASK...]
-        brew install FORMULA|CASK...
-        brew update
-        brew upgrade [FORMULA|CASK...]
-        brew uninstall FORMULA|CASK...
-        brew list [FORMULA|CASK...]
-
-      Troubleshooting:
-        brew config
-        brew doctor
-        brew install --verbose --debug FORMULA|CASK
-
-      Contributing:
-        brew create URL [--no-fetch]
-        brew edit [FORMULA|CASK...]
-
-      Further help:
-        brew commands
-        brew help [COMMAND]
-        man brew
-        https://docs.brew.sh
-    EOS
-    private_constant :HOMEBREW_HELP
-
     def self.help(cmd = nil, empty_argv: false, usage_error: nil, remaining_args: [])
       if cmd.nil?
         # Handle `brew` (no arguments).
         if empty_argv
-          $stderr.puts HOMEBREW_HELP
+          $stderr.puts HOMEBREW_HELP_MESSAGE
           exit 1
         end
 
         # Handle `brew (-h|--help|--usage|-?|help)` (no other arguments).
-        puts HOMEBREW_HELP
+        puts HOMEBREW_HELP_MESSAGE
         exit 0
       end
 
@@ -57,7 +25,7 @@ module Homebrew
 
       # Display command-specific (or generic) help in response to `UsageError`.
       if usage_error
-        $stderr.puts path ? command_help(cmd, path, remaining_args:) : HOMEBREW_HELP
+        $stderr.puts path ? command_help(cmd, path, remaining_args:) : HOMEBREW_HELP_MESSAGE
         $stderr.puts
         onoe usage_error
         exit 1
@@ -83,7 +51,7 @@ module Homebrew
 
       output ||= if output.blank?
         opoo "No help text in: #{path}" if Homebrew::EnvConfig.developer?
-        HOMEBREW_HELP
+        HOMEBREW_HELP_MESSAGE
       end
 
       output

Library/Homebrew/help.sh

@@ -0,0 +1,48 @@
+#:  * `help`
+#:
+#:  Outputs the usage instructions for `brew`.
+#:
+
+# NOTE: Keep the length of vanilla `--help` less than 25 lines!
+#       This is because the default Terminal height is 25 lines. Scrolling sucks
+#       and concision is important. If more help is needed we should start
+#       specialising help like the gem command does.
+# NOTE: Keep lines less than 80 characters! Wrapping is just not cricket.
+HOMEBREW_HELP_MESSAGE=$(
+  cat <<'EOS'
+Example usage:
+  brew search TEXT|/REGEX/
+  brew info [FORMULA|CASK...]
+  brew install FORMULA|CASK...
+  brew update
+  brew upgrade [FORMULA|CASK...]
+  brew uninstall FORMULA|CASK...
+  brew list [FORMULA|CASK...]
+
+Troubleshooting:
+  brew config
+  brew doctor
+  brew install --verbose --debug FORMULA|CASK
+
+Contributing:
+  brew create URL [--no-fetch]
+  brew edit [FORMULA|CASK...]
+
+Further help:
+  brew commands
+  brew help [COMMAND]
+  man brew
+  https://docs.brew.sh
+EOS
+)
+
+homebrew-help() {
+  if [[ -z "$*" ]]
+  then
+    echo "${HOMEBREW_HELP_MESSAGE}" >&2
+    exit 1
+  fi
+
+  echo "${HOMEBREW_HELP_MESSAGE}"
+  return 0
+}