From 4c012a41c6e59c8f2aa27115f5d6bcc0da671ed5 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sat, 13 Jul 2024 16:40:14 -0400 Subject: [PATCH] Port `brew help` (without arguments) to Bash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This provides a decent speedup: ``` $ hyperfine 'git checkout master; brew help' 'git checkout help_bash; brew help' Benchmark 1: git checkout master; brew help Time (mean ± σ): 506.4 ms ± 50.9 ms [User: 223.7 ms, System: 99.9 ms] Range (min … max): 454.6 ms … 634.1 ms 10 runs Benchmark 2: git checkout help_bash; brew help Time (mean ± σ): 109.5 ms ± 57.1 ms [User: 1 ``` and compares favourably to `pip3 help`: ``` $ hyperfine 'brew help' 'pip3 help' Benchmark 1: brew help Time (mean ± σ): 72.9 ms ± 15.9 ms [User: 4.9 ms, System: 6.3 ms] Range (min … max): 53.6 ms … 126.6 ms 31 runs Benchmark 2: pip3 help Time (mean ± σ): 171.5 ms ± 6.1 ms [User: 131.6 ms, System: 24.7 ms] Range (min … max): 164.2 ms … 189.3 ms 15 runs Summary brew help ran 2.35 ± 0.52 times faster than pip3 help ``` --- Library/Homebrew/brew.sh | 8 +++++++ Library/Homebrew/global.rb | 2 ++ Library/Homebrew/help.rb | 40 ++++--------------------------- Library/Homebrew/help.sh | 48 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 62 insertions(+), 36 deletions(-) create mode 100644 Library/Homebrew/help.sh diff --git a/Library/Homebrew/brew.sh b/Library/Homebrew/brew.sh index 99bbfebb06..30ff52cf42 100644 --- a/Library/Homebrew/brew.sh +++ b/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 diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb index e0a233b631..4c144cc6ed 100644 --- a/Library/Homebrew/global.rb +++ b/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 diff --git a/Library/Homebrew/help.rb b/Library/Homebrew/help.rb index 993ab55eeb..b6ce40666b 100644 --- a/Library/Homebrew/help.rb +++ b/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 diff --git a/Library/Homebrew/help.sh b/Library/Homebrew/help.sh new file mode 100644 index 0000000000..f2a9ccd886 --- /dev/null +++ b/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 +}