Merge pull request #20044 from Homebrew/show-env-var-associations

EricFromCanada · web-flow · commit ab1c3ed5f86b · 2025-06-04T01:11:58.000Z
parser: show related environment variable in switch description
diff --git a/Library/Homebrew/cli/parser.rb b/Library/Homebrew/cli/parser.rb
@@ -208,11 +208,15 @@ def switch(*names, description: nil, replacement: nil, env: nil, depends_on: nil
         return if global_switch
 
         description = option_description(description, *names, hidden:)
-        process_option(*names, description, type: :switch, hidden:) unless disable
-
+        env, counterpart = env
+        if env && @non_global_processed_options.any?
+          affix = counterpart ? " and `#{counterpart}` is passed." : "."
+          description += " Enabled by default if `$HOMEBREW_#{env.upcase}` is set#{affix}"
+        end
         if replacement || disable
           description += " (#{disable ? "disabled" : "deprecated"}#{"; replaced by #{replacement}" if replacement})"
         end
+        process_option(*names, description, type: :switch, hidden:) unless disable
 
         @parser.public_send(method, *names, *wrap_option_desc(description)) do |value|
           # This odeprecated should stick around indefinitely.
diff --git a/Library/Homebrew/cmd/bundle.rb b/Library/Homebrew/cmd/bundle.rb
@@ -73,11 +73,10 @@ class Bundle < AbstractCommand
                description: "`install` prints output from commands as they are run. " \
                             "`check` lists all missing dependencies."
         switch "--no-upgrade",
-               env:         :bundle_no_upgrade,
                description: "`install` does not run `brew upgrade` on outdated dependencies. " \
                             "`check` does not check for outdated dependencies. " \
-                            "Note they may still be upgraded by `brew install` if needed. " \
-                            "This is enabled by default if `$HOMEBREW_BUNDLE_NO_UPGRADE` is set."
+                            "Note they may still be upgraded by `brew install` if needed.",
+               env:         :bundle_no_upgrade
         switch "--upgrade",
                description: "`install` runs `brew upgrade` on outdated dependencies, " \
                             "even if `$HOMEBREW_BUNDLE_NO_UPGRADE` is set."
@@ -87,18 +86,15 @@ class Bundle < AbstractCommand
         switch "--install",
                description: "Run `install` before continuing to other operations e.g. `exec`."
         switch "--services",
-               env:         :bundle_services,
-               description: "Temporarily start services while running the `exec` or `sh` command. " \
-                            "This is enabled by default if `$HOMEBREW_BUNDLE_SERVICES` is set."
+               description: "Temporarily start services while running the `exec` or `sh` command.",
+               env:         :bundle_services
         switch "-f", "--force",
                description: "`install` runs with `--force`/`--overwrite`. " \
                             "`dump` overwrites an existing `Brewfile`. " \
                             "`cleanup` actually performs its cleanup operations."
         switch "--cleanup",
-               env:         :bundle_install_cleanup,
-               description: "`install` performs cleanup operation, same as running `cleanup --force`. " \
-                            "This is enabled by default if `$HOMEBREW_BUNDLE_INSTALL_CLEANUP` is set and " \
-                            "`--global` is passed."
+               description: "`install` performs cleanup operation, same as running `cleanup --force`.",
+               env:         [:bundle_install_cleanup, "--global"]
         switch "--all",
                description: "`list` all dependencies."
         switch "--formula", "--brews",
@@ -114,14 +110,12 @@ class Bundle < AbstractCommand
         switch "--vscode",
                description: "`list`, `dump` or `cleanup` VSCode (and forks/variants) extensions."
         switch "--no-vscode",
-               env:         :bundle_dump_no_vscode,
-               description: "`dump` without VSCode (and forks/variants) extensions. " \
-                            "This is enabled by default if `$HOMEBREW_BUNDLE_DUMP_NO_VSCODE` is set."
+               description: "`dump` without VSCode (and forks/variants) extensions.",
+               env:         :bundle_dump_no_vscode
         switch "--describe",
-               env:         :bundle_dump_describe,
                description: "`dump` adds a description comment above each line, unless the " \
-                            "dependency does not have a description. " \
-                            "This is enabled by default if `$HOMEBREW_BUNDLE_DUMP_DESCRIBE` is set."
+                            "dependency does not have a description.",
+               env:         :bundle_dump_describe
         switch "--no-restart",
                description: "`dump` does not add `restart_service` to formula lines."
         switch "--zap",
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
@@ -33,8 +33,8 @@ class InstallCmd < AbstractCommand
                description: "If brewing fails, open an interactive debugging session with access to IRB " \
                             "or a shell inside the temporary build directory."
         switch "--display-times",
-               env:         :display_install_times,
-               description: "Print install times for each package at the end of the run."
+               description: "Print install times for each package at the end of the run.",
+               env:         :display_install_times
         switch "-f", "--force",
                description: "Install formulae without checking for previously installed keg-only or " \
                             "non-migrated versions. When installing casks, overwrite existing files " \
@@ -44,9 +44,9 @@ class InstallCmd < AbstractCommand
         switch "-n", "--dry-run",
                description: "Show what would be installed, but do not actually install anything."
         switch "--ask",
-               env:         :ask,
                description: "Ask for confirmation before downloading and installing formulae. " \
-                            "Print bottles and dependencies download size and install size."
+                            "Print download and install sizes of bottles and dependencies.",
+               env:         :ask
         [
           [:switch, "--formula", "--formulae", {
             description: "Treat all named arguments as formulae.",
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
@@ -32,12 +32,10 @@ class Outdated < AbstractCommand
                             "formula is outdated. Otherwise, the repository's HEAD will only be checked for " \
                             "updates when a new stable or development version has been released."
         switch "-g", "--greedy",
-               env:         :upgrade_greedy,
-               description: "Also include outdated casks with `auto_updates true` or `version :latest`."
-
+               description: "Also include outdated casks with `auto_updates true` or `version :latest`.",
+               env:         :upgrade_greedy
         switch "--greedy-latest",
                description: "Also include outdated casks including those with `version :latest`."
-
         switch "--greedy-auto-updates",
                description: "Also include outdated casks including those with `auto_updates true`."
 
diff --git a/Library/Homebrew/cmd/reinstall.rb b/Library/Homebrew/cmd/reinstall.rb
@@ -32,16 +32,16 @@ class Reinstall < AbstractCommand
                description: "If brewing fails, open an interactive debugging session with access to IRB " \
                             "or a shell inside the temporary build directory."
         switch "--display-times",
-               env:         :display_install_times,
-               description: "Print install times for each package at the end of the run."
+               description: "Print install times for each package at the end of the run.",
+               env:         :display_install_times
         switch "-f", "--force",
                description: "Install without checking for previously installed keg-only or " \
                             "non-migrated versions."
         switch "-v", "--verbose",
                description: "Print the verification and post-install steps."
         switch "--ask",
                description: "Ask for confirmation before downloading and upgrading formulae. " \
-                            "Print bottles and dependencies download size, install and net install size.",
+                            "Print download, install and net install sizes of bottles and dependencies.",
                env:         :ask
         [
           [:switch, "--formula", "--formulae", { description: "Treat all named arguments as formulae." }],
diff --git a/Library/Homebrew/cmd/shellenv.rb b/Library/Homebrew/cmd/shellenv.rb
@@ -13,18 +13,20 @@ class Shellenv < AbstractCommand
         description <<~EOS
           Valid shells: bash|csh|fish|pwsh|sh|tcsh|zsh
 
-          Print export statements. When run in a shell, this installation of Homebrew will be added to your `PATH`, `MANPATH`, and `INFOPATH`.
+          Print export statements. When run in a shell, this installation of Homebrew will be added to your
+          `$PATH`, `$MANPATH`, and `$INFOPATH`.
 
           The variables `$HOMEBREW_PREFIX`, `$HOMEBREW_CELLAR` and `$HOMEBREW_REPOSITORY` are also exported to avoid
           querying them multiple times.
           To help guarantee idempotence, this command produces no output when Homebrew's `bin` and `sbin` directories
-          are first and second respectively in your `PATH`. Consider adding evaluation of this command's output to
+          are first and second respectively in your `$PATH`. Consider adding evaluation of this command's output to
           your dotfiles (e.g. `~/.bash_profile` or ~/.zprofile` on macOS and ~/.bashrc` or ~/.zshrc` on Linux) with:
             `eval "$(brew shellenv)"`
 
           The shell can be specified explicitly with a supported shell name parameter. Unknown shells will output
           POSIX exports.
         EOS
+
         named_args :shell
       end
     end
diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
@@ -29,8 +29,8 @@ class UpgradeCmd < AbstractCommand
                description: "If brewing fails, open an interactive debugging session with access to IRB " \
                             "or a shell inside the temporary build directory."
         switch "--display-times",
-               env:         :display_install_times,
-               description: "Print install times for each package at the end of the run."
+               description: "Print install times for each package at the end of the run.",
+               env:         :display_install_times
         switch "-f", "--force",
                description: "Install formulae without checking for previously installed keg-only or " \
                             "non-migrated versions. When installing casks, overwrite existing files " \
@@ -41,7 +41,7 @@ class UpgradeCmd < AbstractCommand
                description: "Show what would be upgraded, but do not actually upgrade anything."
         switch "--ask",
                description: "Ask for confirmation before downloading and upgrading formulae. " \
-                            "Print bottles and dependencies download size, install and net install size.",
+                            "Print download, install and net install sizes of bottles and dependencies.",
                env:         :ask
         [
           [:switch, "--formula", "--formulae", {
diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb
@@ -43,7 +43,7 @@ class Audit < AbstractCommand
                description: "Only check formulae and casks that are currently installed."
         switch "--eval-all",
                description: "Evaluate all available formulae and casks, whether installed or not, to audit them. " \
-                            "Implied if `HOMEBREW_EVAL_ALL` is set."
+                            "Implied if `$HOMEBREW_EVAL_ALL` is set."
         switch "--new",
                description: "Run various additional style checks to determine if a new formula or cask is eligible " \
                             "for Homebrew. This should be used when creating new formulae or casks and implies " \
diff --git a/Library/Homebrew/dev-cmd/bump.rb b/Library/Homebrew/dev-cmd/bump.rb
@@ -118,7 +118,7 @@ def run
           else
             raise UsageError,
                   "`brew bump` without named arguments needs `--installed` or `--eval-all` passed or " \
-                  "`HOMEBREW_EVAL_ALL` set!"
+                  "`$HOMEBREW_EVAL_ALL` set!"
           end
 
           if args.start_with
diff --git a/Library/Homebrew/dev-cmd/determine-test-runners.rb b/Library/Homebrew/dev-cmd/determine-test-runners.rb
@@ -21,7 +21,8 @@ class DetermineTestRunners < AbstractCommand
                             "dependents.",
                env:         :eval_all
         switch "--dependents",
-               description: "Determine runners for testing dependents. Requires `--eval-all` or `HOMEBREW_EVAL_ALL`.",
+               description: "Determine runners for testing dependents. " \
+                            "Requires `--eval-all` or `$HOMEBREW_EVAL_ALL` to be set.",
                depends_on:  "--eval-all"
 
         named_args max: 2
diff --git a/Library/Homebrew/dev-cmd/edit.rb b/Library/Homebrew/dev-cmd/edit.rb
@@ -9,10 +9,9 @@ module DevCmd
     class Edit < AbstractCommand
       cmd_args do
         description <<~EOS
-          Open a <formula>, <cask> or <tap> in the editor set by `EDITOR` or `HOMEBREW_EDITOR`,
+          Open a <formula>, <cask> or <tap> in the editor set by `$EDITOR` or `$HOMEBREW_EDITOR`,
           or open the Homebrew repository for editing if no argument is provided.
         EOS
-
         switch "--formula", "--formulae",
                description: "Treat all named arguments as formulae."
         switch "--cask", "--casks",
diff --git a/Library/Homebrew/dev-cmd/irb.rb b/Library/Homebrew/dev-cmd/irb.rb
@@ -44,8 +44,8 @@ class Irb < AbstractCommand
         switch "--examples",
                description: "Show several examples."
         switch "--pry",
-               env:         :pry,
-               description: "Use Pry instead of IRB. Implied if `HOMEBREW_PRY` is set."
+               description: "Use Pry instead of IRB.",
+               env:         :pry
       end
 
       # work around IRB modifying ARGV.
diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb
@@ -23,7 +23,7 @@ class Linkage < AbstractCommand
                description: "For every library that a keg references, print its dylib path followed by the " \
                             "binaries that link to it."
         switch "--cached",
-               description: "Print the cached linkage values stored in `HOMEBREW_CACHE`, set by a previous " \
+               description: "Print the cached linkage values stored in `$HOMEBREW_CACHE`, set by a previous " \
                             "`brew linkage` run."
 
         named_args :installed_formula
diff --git a/Library/Homebrew/dev-cmd/livecheck.rb b/Library/Homebrew/dev-cmd/livecheck.rb
@@ -13,7 +13,7 @@ class LivecheckCmd < AbstractCommand
         description <<~EOS
           Check for newer versions of formulae and/or casks from upstream.
           If no formula or cask argument is passed, the list of formulae and
-          casks to check is taken from `HOMEBREW_LIVECHECK_WATCHLIST` or
+          casks to check is taken from `$HOMEBREW_LIVECHECK_WATCHLIST` or
           `~/.homebrew/livecheck_watchlist.txt`.
         EOS
         switch "--full-name",
diff --git a/Library/Homebrew/dev-cmd/sh.rb b/Library/Homebrew/dev-cmd/sh.rb
@@ -13,11 +13,11 @@ class Sh < AbstractCommand
           Enter an interactive shell for Homebrew's build environment. Use years-battle-hardened
           build logic to help your `./configure && make && make install`
           and even your `gem install` succeed. Especially handy if you run Homebrew
-          in an Xcode-only configuration since it adds tools like `make` to your `PATH`
+          in an Xcode-only configuration since it adds tools like `make` to your `$PATH`
           which build systems would not find otherwise.
         EOS
         flag   "--env=",
-               description: "Use the standard `PATH` instead of superenv's when `std` is passed."
+               description: "Use the standard `$PATH` instead of superenv's when `std` is passed."
         flag   "-c=", "--cmd=",
                description: "Execute commands in a non-interactive shell."
 
diff --git a/Library/Homebrew/dev-cmd/unbottled.rb b/Library/Homebrew/dev-cmd/unbottled.rb
@@ -23,7 +23,7 @@ class Unbottled < AbstractCommand
                description: "Print the `homebrew/core` commits where bottles were lost in the last week."
         switch "--eval-all",
                description: "Evaluate all available formulae and casks, whether installed or not, to check them. " \
-                            "Implied if `HOMEBREW_EVAL_ALL` is set."
+                            "Implied if `$HOMEBREW_EVAL_ALL` is set."
 
         conflicts "--dependents", "--total", "--lost"
 
@@ -68,7 +68,7 @@ def run
           all = args.eval_all?
           if args.total?
             if !all && !Homebrew::EnvConfig.eval_all?
-              raise UsageError, "`brew unbottled --total` needs `--eval-all` passed or `HOMEBREW_EVAL_ALL` set!"
+              raise UsageError, "`brew unbottled --total` needs `--eval-all` passed or `$HOMEBREW_EVAL_ALL` set!"
             end
 
             all = true
@@ -119,7 +119,7 @@ def formulae_all_installs_from_args(all)
         elsif args.dependents?
           if !args.eval_all? && !Homebrew::EnvConfig.eval_all?
             raise UsageError,
-                  "`brew unbottled --dependents` needs `--eval-all` passed or `HOMEBREW_EVAL_ALL` set!"
+                  "`brew unbottled --dependents` needs `--eval-all` passed or `$HOMEBREW_EVAL_ALL` set!"
           end
 
           formulae = all_formulae = Formula.all(eval_all: args.eval_all?)
@@ -136,7 +136,7 @@ def formulae_all_installs_from_args(all)
           if analytics.blank?
             raise UsageError,
                   "default sort by analytics data requires " \
-                  "`HOMEBREW_NO_GITHUB_API` and `HOMEBREW_NO_ANALYTICS` to be unset"
+                  "`$HOMEBREW_NO_GITHUB_API` and `$HOMEBREW_NO_ANALYTICS` to be unset."
           end
 
           formulae = analytics["items"].filter_map do |i|
diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb
@@ -15,7 +15,7 @@ class UpdateTest < AbstractCommand
           If no options are passed, use `origin/master` as the start commit.
         EOS
         switch "--to-tag",
-               description: "Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags."
+               description: "Set `$HOMEBREW_UPDATE_TO_TAG` to test updating between tags."
         switch "--keep-tmp",
                description: "Retain the temporary directory containing the new repository clone."
         flag   "--commit=",
diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
@@ -463,7 +463,7 @@ module EnvConfig
         default_text: "`~/.ssh/config`",
       },
       HOMEBREW_SUDO_THROUGH_SUDO_USER:           {
-        description: "If set, Homebrew will use the `SUDO_USER` environment variable to define the user to " \
+        description: "If set, Homebrew will use the `$SUDO_USER` environment variable to define the user to " \
                      "`sudo`(8) through when running `sudo`(8).",
         boolean:     true,
       },
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
@@ -133,7 +133,7 @@ If no search term is provided, all locally available formulae are listed.
 ## CUSTOM EXTERNAL COMMANDS
 
 Homebrew, like `git`(1), supports external commands. These are executable
-scripts that reside somewhere in the `PATH`, named `brew-`<cmdname> or
+scripts that reside somewhere in the `$PATH`, named `brew-`<cmdname> or
 `brew-`<cmdname>`.rb`, which can be invoked like `brew` <cmdname>. This
 allows you to create your own commands without modifying Homebrew's internals.
 
@@ -184,7 +184,7 @@ files:
 
 User-specific environment files take precedence over prefix-specific files and
 prefix-specific files take precedence over system-wide files (unless
-`HOMEBREW_SYSTEM_ENV_TAKES_PRIORITY` is set, see below).
+`$HOMEBREW_SYSTEM_ENV_TAKES_PRIORITY` is set, see below).
 
 Note that these files do not support shell variable expansion e.g. `$HOME` or
 command execution e.g. `$(cat file)`.
diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish
diff --git a/completions/zsh/_brew b/completions/zsh/_brew
diff --git a/docs/Manpage.md b/docs/Manpage.md
diff --git a/manpages/brew.1 b/manpages/brew.1
