man: include global options with customized descriptions

Library/Homebrew/cli/parser.rb

@@ -144,8 +144,9 @@ def parse(cmdline_args = ARGV)
         @parser
       end
 
-      def global_option?(name)
-        Homebrew::CLI::Parser.global_options.key?(name.to_sym)
+      def global_option?(name, desc)
+        Homebrew::CLI::Parser.global_options.key?(name.to_sym) &&
+          Homebrew::CLI::Parser.global_options[name.to_sym].last == desc
       end
 
       def generate_help_text

Library/Homebrew/cmd/commands.rb

@@ -12,7 +12,7 @@ def commands_args
 
         Show lists of built-in and external commands.
       EOS
-      switch "--quiet",
+      switch :quiet,
              description: "List only the names of commands without category headers."
       switch "--include-aliases",
              depends_on:  "--quiet",

Library/Homebrew/cmd/upgrade.rb

@@ -47,7 +47,7 @@ def upgrade_args
       switch "--display-times",
              env:         :display_install_times,
              description: "Print install times for each formula at the end of the run."
-      switch "--dry-run",
+      switch "-n", "--dry-run",
              description: "Show what would be upgraded, but do not actually upgrade anything."
       conflicts "--build-from-source", "--force-bottle"
       formula_options

Library/Homebrew/dev-cmd/man.rb

@@ -181,7 +181,7 @@ def cmd_arg_parser(cmd_path)
   def cmd_parser_manpage_lines(cmd_parser)
     lines = [format_usage_banner(cmd_parser.usage_banner_text)]
     lines += cmd_parser.processed_options.map do |short, long, _, desc|
-      next if !long.nil? && cmd_parser.global_option?(cmd_parser.option_to_name(long))
+      next if !long.nil? && cmd_parser.global_option?(cmd_parser.option_to_name(long), desc)
 
       generate_option_doc(short, long, desc)
     end.reject(&:blank?)

docs/Manpage.md

@@ -79,6 +79,8 @@ Display the path to the file being used when invoking `brew` *`cmd`*.
 
 Show lists of built-in and external commands.
 
+* `-q`, `--quiet`:
+  List only the names of commands without category headers.
 * `--include-aliases`:
   Include aliases of internal commands.
 
@@ -168,6 +170,10 @@ also print SHA-256 checksums.
   Fetch HEAD version instead of stable version.
 * `--devel`:
   Fetch development version instead of stable version.
+* `-f`, `--force`:
+  Remove a previously cached version and re-fetch.
+* `-v`, `--verbose`:
+  Do a verbose VCS checkout, if the URL represents a VCS. This is useful for seeing if an existing VCS cache has been updated.
 * `--retry`:
   Retry if downloading fails or re-download if the checksum of a previously cached version no longer matches.
 * `--deps`:
@@ -216,6 +222,8 @@ If *`formula`* is provided, show summary of information about *`formula`*.
   Print JSON of formulae that are currently installed.
 * `--all`:
   Print JSON of all available formulae.
+* `-v`, `--verbose`:
+  Show more verbose analytics data for *`formula`*.
 
 ### `install` [*`options`*] *`formula`*
 
@@ -225,6 +233,8 @@ the command.
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
 the installed formulae or, every 30 days, for all formulae.
 
+* `-d`, `--debug`:
+  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
 * `--env`:
   If `std` is passed, use the standard build environment instead of superenv. If `super` is passed, use superenv even if the formula specifies the standard build environment.
 * `--ignore-dependencies`:
@@ -251,6 +261,10 @@ the installed formulae or, every 30 days, for all formulae.
   Prepare the formula for eventual bottling during installation, skipping any post-install steps.
 * `--bottle-arch`:
   Optimise bottles for the specified architecture rather than the oldest architecture supported by the version of macOS the bottles are built on.
+* `-f`, `--force`:
+  Install without checking for previously installed keg-only or non-migrated versions.
+* `-v`, `--verbose`:
+  Print the verification and postinstall steps.
 * `--display-times`:
   Print install times for each formula at the end of the run.
 * `-i`, `--interactive`:
@@ -271,6 +285,8 @@ automatically when you install formulae but can be useful for DIY installations.
   Delete files that already exist in the prefix while linking.
 * `-n`, `--dry-run`:
   List files which would be linked or deleted by `brew link --overwrite` without actually linking or deleting any files.
+* `-f`, `--force`:
+  Allow keg-only formulae to be linked.
 
 ### `list`, `ls` [*`options`*] [*`formula`*]
 
@@ -316,6 +332,9 @@ no formula is provided.
 Migrate renamed packages to new names, where *`formula`* are old names of
 packages.
 
+* `-f`, `--force`:
+  Treat installed *`formula`* and provided *`formula`* as if they are from the same taps and migrate them anyway.
+
 ### `missing` [*`options`*] [*`formula`*]
 
 Check the given *`formula`* kegs for missing dependencies. If no *`formula`* are
@@ -342,6 +361,10 @@ List installed formulae that have an updated version available. By default,
 version information is displayed in interactive shells, and suppressed
 otherwise.
 
+* `-q`, `--quiet`:
+  List only the names of outdated kegs (takes precedence over `--verbose`).
+* `-v`, `--verbose`:
+  Include detailed version information.
 * `--json`:
   Print output in JSON format. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>
 * `--fetch-HEAD`:
@@ -376,12 +399,18 @@ installed with, plus any appended brew formula options.
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
 the reinstalled formulae or, every 30 days, for all formulae.
 
+* `-d`, `--debug`:
+  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
 * `-s`, `--build-from-source`:
   Compile *`formula`* from source even if a bottle is available.
 * `--force-bottle`:
   Install from a bottle if it exists for the current or newest version of macOS, even if it would not normally be used for installation.
 * `--keep-tmp`:
   Retain the temporary files created during installation.
+* `-f`, `--force`:
+  Install without checking for previously installed keg-only or non-migrated versions.
+* `-v`, `--verbose`:
+  Print the verification and postinstall steps.
 * `--display-times`:
   Print install times for each formula at the end of the run.
 
@@ -493,6 +522,8 @@ If no *`tap`* names are provided, display brief statistics for all installed tap
 
 Uninstall *`formula`*.
 
+* `-f`, `--force`:
+  Delete all installed versions of *`formula`*.
 * `--ignore-dependencies`:
   Don't fail uninstall, even if *`formula`* is a dependency of any installed formulae.
 
@@ -549,6 +580,8 @@ specified, upgrade only the given *`formula`* kegs (unless they are pinned; see
 Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
 the upgraded formulae or, every 30 days, for all formulae.
 
+* `-d`, `--debug`:
+  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
 * `-s`, `--build-from-source`:
   Compile *`formula`* from source even if a bottle is available.
 * `--force-bottle`:
@@ -559,9 +592,13 @@ the upgraded formulae or, every 30 days, for all formulae.
   Set a successful exit status even if pinned formulae are not upgraded.
 * `--keep-tmp`:
   Retain the temporary files created during installation.
+* `-f`, `--force`:
+  Install without checking for previously installed keg-only or non-migrated versions.
+* `-v`, `--verbose`:
+  Print the verification and postinstall steps.
 * `--display-times`:
   Print install times for each formula at the end of the run.
-* `--dry-run`:
+* `-n`, `--dry-run`:
   Show what would be upgraded, but do not actually upgrade anything.
 
 ### `uses` [*`options`*] *`formula`*

manpages/brew.1

@@ -76,6 +76,10 @@ Display the path to the file being used when invoking \fBbrew\fR \fIcmd\fR\.
 Show lists of built\-in and external commands\.
 .
 .TP
+\fB\-q\fR, \fB\-\-quiet\fR
+List only the names of commands without category headers\.
+.
+.TP
 \fB\-\-include\-aliases\fR
 Include aliases of internal commands\.
 .
@@ -190,6 +194,14 @@ Fetch HEAD version instead of stable version\.
 Fetch development version instead of stable version\.
 .
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+Remove a previously cached version and re\-fetch\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Do a verbose VCS checkout, if the URL represents a VCS\. This is useful for seeing if an existing VCS cache has been updated\.
+.
+.TP
 \fB\-\-retry\fR
 Retry if downloading fails or re\-download if the checksum of a previously cached version no longer matches\.
 .
@@ -261,13 +273,21 @@ Print JSON of formulae that are currently installed\.
 \fB\-\-all\fR
 Print JSON of all available formulae\.
 .
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Show more verbose analytics data for \fIformula\fR\.
+.
 .SS "\fBinstall\fR [\fIoptions\fR] \fIformula\fR"
 Install \fIformula\fR\. Additional options specific to \fIformula\fR may be appended to the command\.
 .
 .P
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the installed formulae or, every 30 days, for all formulae\.
 .
 .TP
+\fB\-d\fR, \fB\-\-debug\fR
+If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.
+.
+.TP
 \fB\-\-env\fR
 If \fBstd\fR is passed, use the standard build environment instead of superenv\. If \fBsuper\fR is passed, use superenv even if the formula specifies the standard build environment\.
 .
@@ -320,6 +340,14 @@ Prepare the formula for eventual bottling during installation, skipping any post
 Optimise bottles for the specified architecture rather than the oldest architecture supported by the version of macOS the bottles are built on\.
 .
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+Install without checking for previously installed keg\-only or non\-migrated versions\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print the verification and postinstall steps\.
+.
+.TP
 \fB\-\-display\-times\fR
 Print install times for each formula at the end of the run\.
 .
@@ -345,6 +373,10 @@ Delete files that already exist in the prefix while linking\.
 \fB\-n\fR, \fB\-\-dry\-run\fR
 List files which would be linked or deleted by \fBbrew link \-\-overwrite\fR without actually linking or deleting any files\.
 .
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+Allow keg\-only formulae to be linked\.
+.
 .SS "\fBlist\fR, \fBls\fR [\fIoptions\fR] [\fIformula\fR]"
 List all installed formulae\.
 .
@@ -409,6 +441,10 @@ Print only one or a specified number of commits\.
 .SS "\fBmigrate\fR [\fIoptions\fR] \fIformula\fR"
 Migrate renamed packages to new names, where \fIformula\fR are old names of packages\.
 .
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+Treat installed \fIformula\fR and provided \fIformula\fR as if they are from the same taps and migrate them anyway\.
+.
 .SS "\fBmissing\fR [\fIoptions\fR] [\fIformula\fR]"
 Check the given \fIformula\fR kegs for missing dependencies\. If no \fIformula\fR are provided, check all kegs\. Will exit with a non\-zero status if any kegs are found to be missing dependencies\.
 .
@@ -435,6 +471,14 @@ Show options for all available formulae\.
 List installed formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
 .
 .TP
+\fB\-q\fR, \fB\-\-quiet\fR
+List only the names of outdated kegs (takes precedence over \fB\-\-verbose\fR)\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Include detailed version information\.
+.
+.TP
 \fB\-\-json\fR
 Print output in JSON format\. Currently the default and only accepted value for \fIversion\fR is \fBv1\fR\. See the docs for examples of using the JSON output: \fIhttps://docs\.brew\.sh/Querying\-Brew\fR
 .
@@ -466,6 +510,10 @@ Uninstall and then install \fIformula\fR using the same options it was originall
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the reinstalled formulae or, every 30 days, for all formulae\.
 .
 .TP
+\fB\-d\fR, \fB\-\-debug\fR
+If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.
+.
+.TP
 \fB\-s\fR, \fB\-\-build\-from\-source\fR
 Compile \fIformula\fR from source even if a bottle is available\.
 .
@@ -478,6 +526,14 @@ Install from a bottle if it exists for the current or newest version of macOS, e
 Retain the temporary files created during installation\.
 .
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+Install without checking for previously installed keg\-only or non\-migrated versions\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print the verification and postinstall steps\.
+.
+.TP
 \fB\-\-display\-times\fR
 Print install times for each formula at the end of the run\.
 .
@@ -607,6 +663,10 @@ Print a JSON representation of \fItap\fR\. Currently the default and only accept
 Uninstall \fIformula\fR\.
 .
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+Delete all installed versions of \fIformula\fR\.
+.
+.TP
 \fB\-\-ignore\-dependencies\fR
 Don\'t fail uninstall, even if \fIformula\fR is a dependency of any installed formulae\.
 .
@@ -658,6 +718,10 @@ Upgrade outdated, unpinned formulae using the same options they were originally
 Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the upgraded formulae or, every 30 days, for all formulae\.
 .
 .TP
+\fB\-d\fR, \fB\-\-debug\fR
+If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.
+.
+.TP
 \fB\-s\fR, \fB\-\-build\-from\-source\fR
 Compile \fIformula\fR from source even if a bottle is available\.
 .
@@ -678,11 +742,19 @@ Set a successful exit status even if pinned formulae are not upgraded\.
 Retain the temporary files created during installation\.
 .
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+Install without checking for previously installed keg\-only or non\-migrated versions\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print the verification and postinstall steps\.
+.
+.TP
 \fB\-\-display\-times\fR
 Print install times for each formula at the end of the run\.
 .
 .TP
-\fB\-\-dry\-run\fR
+\fB\-n\fR, \fB\-\-dry\-run\fR
 Show what would be upgraded, but do not actually upgrade anything\.
 .
 .SS "\fBuses\fR [\fIoptions\fR] \fIformula\fR"