Merge pull request #20361 from Homebrew/manpage-updates

EricFromCanada · web-flow · commit aecd2b344794 · 2025-08-02T11:47:31.000Z
Manpage: source wording &amp; formatting fixes
diff --git a/Library/Homebrew/cmd/--cache.rb b/Library/Homebrew/cmd/--cache.rb
@@ -29,8 +29,8 @@ def self.command_name = "--cache"
                description: "Show the cache file used when building from source."
         switch "--force-bottle",
                description: "Show the cache file used when pouring a bottle."
-        flag "--bottle-tag=",
-             description: "Show the cache file used when pouring a bottle for the given tag."
+        flag   "--bottle-tag=",
+               description: "Show the cache file used when pouring a bottle for the given tag."
         switch "--HEAD",
                description: "Show the cache file used when building from HEAD."
         switch "--formula", "--formulae",
diff --git a/Library/Homebrew/cmd/--prefix.rb b/Library/Homebrew/cmd/--prefix.rb
@@ -52,6 +52,7 @@ def self.command_name = "--prefix"
                description: "List files in Homebrew's prefix not installed by Homebrew."
         switch "--installed",
                description: "Outputs nothing and returns a failing status code if <formula> is not installed."
+
         conflicts "--unbrewed", "--installed"
 
         named_args :formula
diff --git a/Library/Homebrew/cmd/bundle.rb b/Library/Homebrew/cmd/bundle.rb
@@ -51,20 +51,20 @@ class Bundle < AbstractCommand
           `brew bundle remove` <name> [...]:
           Remove entries that match `name` from your `Brewfile`. Use `--formula`, `--cask`, `--tap`, `--mas`, `--whalebrew` or `--vscode` to remove only entries of the corresponding type. Passing `--formula` also removes matches against formula aliases and old formula names.
 
-          `brew bundle exec` [--check] <command>:
+          `brew bundle exec` [`--check`] <command>:
           Run an external command in an isolated build environment based on the `Brewfile` dependencies.
 
           This sanitized build environment ignores unrequested dependencies, which makes sure that things you didn't specify in your `Brewfile` won't get picked up by commands like `bundle install`, `npm install`, etc. It will also add compiler flags which will help with finding keg-only dependencies like `openssl`, `icu4c`, etc.
 
-          `brew bundle sh` [--check]:
+          `brew bundle sh` [`--check`]:
           Run your shell in a `brew bundle exec` environment.
 
-          `brew bundle env` [--check]:
+          `brew bundle env` [`--check`]:
           Print the environment variables that would be set in a `brew bundle exec` environment.
         EOS
-        flag "--file=",
-             description: "Read from or write to the `Brewfile` from this location. " \
-                          "Use `--file=-` to pipe to stdin/stdout."
+        flag   "--file=",
+               description: "Read from or write to the `Brewfile` from this location. " \
+                            "Use `--file=-` to pipe to stdin/stdout."
         switch "--global",
                description: "Read from or write to the `Brewfile` from `$HOMEBREW_BUNDLE_FILE_GLOBAL` (if set), " \
                             "`${XDG_CONFIG_HOME}/homebrew/Brewfile` (if `$XDG_CONFIG_HOME` is set), " \
@@ -80,11 +80,11 @@ class Bundle < AbstractCommand
         switch "--upgrade",
                description: "`install` runs `brew upgrade` on outdated dependencies, " \
                             "even if `$HOMEBREW_BUNDLE_NO_UPGRADE` is set."
-        flag "--upgrade-formulae=", "--upgrade-formula=",
-             description: "`install` runs `brew upgrade` on any of these comma-separated formulae, " \
-                          "even if `$HOMEBREW_BUNDLE_NO_UPGRADE` is set."
+        flag   "--upgrade-formulae=", "--upgrade-formula=",
+               description: "`install` runs `brew upgrade` on any of these comma-separated formulae, " \
+                            "even if `$HOMEBREW_BUNDLE_NO_UPGRADE` is set."
         switch "--install",
-               description: "Run `install` before continuing to other operations e.g. `exec`."
+               description: "Run `install` before continuing to other operations, e.g. `exec`."
         switch "--services",
                description: "Temporarily start services while running the `exec` or `sh` command.",
                env:         :bundle_services
diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb
@@ -12,6 +12,7 @@ class HelpCmd < AbstractCommand
           Outputs the usage instructions for `brew` <command>.
           Equivalent to `brew --help` <command>.
         EOS
+
         named_args [:command]
       end
 
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
@@ -134,12 +134,14 @@ class InstallCmd < AbstractCommand
         end
         formula_options
         [
-          [:switch, "--cask", "--casks", { description: "Treat all named arguments as casks." }],
+          [:switch, "--cask", "--casks", {
+            description: "Treat all named arguments as casks.",
+          }],
           [:switch, "--[no-]binaries", {
             description: "Disable/enable linking of helper executables (default: enabled).",
             env:         :cask_opts_binaries,
           }],
-          [:switch, "--require-sha",  {
+          [:switch, "--require-sha", {
             description: "Require all casks to have a checksum.",
             env:         :cask_opts_require_sha,
           }],
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
@@ -54,7 +54,7 @@ class List < AbstractCommand
                description: "List formulae and/or casks in long format. " \
                             "Has no effect when a formula or cask name is passed as an argument."
         switch "-r",
-               description: "Reverse the order of the formulae and/or casks sort to list the oldest entries first. " \
+               description: "Reverse the order of formula and/or cask sorting to list the oldest entries first. " \
                             "Has no effect when a formula or cask name is passed as an argument."
         switch "-t",
                description: "Sort formulae and/or casks by time modified, listing most recently modified first. " \
diff --git a/Library/Homebrew/cmd/reinstall.rb b/Library/Homebrew/cmd/reinstall.rb
@@ -44,7 +44,9 @@ class Reinstall < AbstractCommand
                             "Print download, install and net install sizes of bottles and dependencies.",
                env:         :ask
         [
-          [:switch, "--formula", "--formulae", { description: "Treat all named arguments as formulae." }],
+          [:switch, "--formula", "--formulae", {
+            description: "Treat all named arguments as formulae.",
+          }],
           [:switch, "-s", "--build-from-source", {
             description: "Compile <formula> from source even if a bottle is available.",
           }],
@@ -74,12 +76,14 @@ class Reinstall < AbstractCommand
         end
         formula_options
         [
-          [:switch, "--cask", "--casks", { description: "Treat all named arguments as casks." }],
+          [:switch, "--cask", "--casks", {
+            description: "Treat all named arguments as casks.",
+          }],
           [:switch, "--[no-]binaries", {
             description: "Disable/enable linking of helper executables (default: enabled).",
             env:         :cask_opts_binaries,
           }],
-          [:switch, "--require-sha",  {
+          [:switch, "--require-sha", {
             description: "Require all casks to have a checksum.",
             env:         :cask_opts_require_sha,
           }],
diff --git a/Library/Homebrew/cmd/services.rb b/Library/Homebrew/cmd/services.rb
@@ -22,7 +22,7 @@ class Services < AbstractCommand
           Manage background services with macOS' `launchctl`(1) daemon manager or
           Linux's `systemctl`(1) service manager.
 
-          If `sudo` is passed, operate on `/Library/LaunchDaemons` or `/usr/lib/systemd/system`  (started at boot).
+          If `sudo` is passed, operate on `/Library/LaunchDaemons` or `/usr/lib/systemd/system` (started at boot).
           Otherwise, operate on `~/Library/LaunchAgents` or `~/.config/systemd/user` (started at login).
 
           [`sudo`] `brew services` [`list`] (`--json`) (`--debug`):
@@ -51,15 +51,24 @@ class Services < AbstractCommand
           [`sudo`] `brew services cleanup`:
           Remove all unused services.
         EOS
-        flag "--file=", description: "Use the service file from this location to `start` the service."
-        flag "--sudo-service-user=", description: "When run as root on macOS, run the service(s) as this user."
-        flag "--max-wait=", description: "Wait at most this many seconds for `stop` to finish stopping a service. " \
-                                         "Defaults to 60. Set this to zero (0) seconds to wait indefinitely."
-        switch "--all", description: "Run <subcommand> on all services."
-        switch "--json", description: "Output as JSON."
-        switch "--no-wait", description: "Don't wait for `stop` to finish stopping the service."
-        switch "--keep", description: "When stopped, don't unregister the service from launching at login (or boot)."
+        flag   "--file=",
+               description: "Use the service file from this location to `start` the service."
+        flag   "--sudo-service-user=",
+               description: "When run as root on macOS, run the service(s) as this user."
+        flag   "--max-wait=",
+               description: "Wait at most this many seconds for `stop` to finish stopping a service. " \
+                            "Defaults to 60. Set this to zero (0) seconds to wait indefinitely."
+        switch "--all",
+               description: "Run <subcommand> on all services."
+        switch "--json",
+               description: "Output as JSON."
+        switch "--no-wait",
+               description: "Don't wait for `stop` to finish stopping the service."
+        switch "--keep",
+               description: "When stopped, don't unregister the service from launching at login (or boot)."
+
         conflicts "--max-wait=", "--no-wait"
+
         named_args %w[list info run start stop kill restart cleanup]
       end
 
diff --git a/Library/Homebrew/cmd/tab.rb b/Library/Homebrew/cmd/tab.rb
@@ -17,7 +17,6 @@ class TabCmd < AbstractCommand
           To prevent removal, mark the formula as installed on request;
           to allow removal, mark the formula as not installed on request.
         EOS
-
         switch "--installed-on-request",
                description: "Mark <installed_formula> or <installed_cask> as installed on request."
         switch "--no-installed-on-request",
diff --git a/Library/Homebrew/cmd/unalias.rb b/Library/Homebrew/cmd/unalias.rb
@@ -11,6 +11,7 @@ class Unalias < AbstractCommand
         description <<~EOS
           Remove aliases.
         EOS
+
         named_args :alias, min: 1
       end
 
diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
@@ -103,7 +103,7 @@ class UpgradeCmd < AbstractCommand
             description: "Disable/enable linking of helper executables (default: enabled).",
             env:         :cask_opts_binaries,
           }],
-          [:switch, "--require-sha",  {
+          [:switch, "--require-sha", {
             description: "Require all casks to have a checksum.",
             env:         :cask_opts_require_sha,
           }],
diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -83,6 +83,7 @@ class BumpFormulaPr < AbstractCommand
                     description: "Exclude these Python packages when finding resources."
         comma_array "--bump-synced=",
                     hidden: true
+
         conflicts "--dry-run", "--write-only"
         conflicts "--no-audit", "--strict"
         conflicts "--no-audit", "--online"
diff --git a/Library/Homebrew/dev-cmd/cat.rb b/Library/Homebrew/dev-cmd/cat.rb
@@ -13,7 +13,6 @@ class Cat < AbstractCommand
         description <<~EOS
           Display the source of a <formula> or <cask>.
         EOS
-
         switch "--formula", "--formulae",
                description: "Treat all named arguments as formulae."
         switch "--cask", "--casks",
diff --git a/Library/Homebrew/dev-cmd/contributions.rb b/Library/Homebrew/dev-cmd/contributions.rb
@@ -15,28 +15,24 @@ class Contributions < AbstractCommand
       MAX_REPO_COMMITS = 1000
 
       cmd_args do
-        usage_banner "`contributions` [--user=<email|username>] [<--repositories>`=`] [<--csv>]"
+        usage_banner "`contributions` [`--user=`] [`--repositories=`] [`--from=`] [`--to=`] [`--csv`]"
         description <<~EOS
           Summarise contributions to Homebrew repositories.
         EOS
-
+        comma_array "--user=",
+                    description: "Specify a comma-separated list of GitHub usernames or email addresses to find " \
+                                 "contributions from. Omitting this flag searches Homebrew maintainers."
         comma_array "--repositories",
                     description: "Specify a comma-separated list of repositories to search. " \
                                  "Supported repositories: #{SUPPORTED_REPOS.map { |t| "`#{t}`" }.to_sentence}. " \
                                  "Omitting this flag, or specifying `--repositories=primary`, searches only the " \
-                                 "main repositories: brew,core,cask. " \
-                                 "Specifying `--repositories=all`, searches all repositories. "
-        flag "--from=",
-             description: "Date (ISO-8601 format) to start searching contributions. " \
-                          "Omitting this flag searches the last year."
-
-        flag "--to=",
-             description: "Date (ISO-8601 format) to stop searching contributions."
-
-        comma_array "--user=",
-                    description: "Specify a comma-separated list of GitHub usernames or email addresses to find " \
-                                 "contributions from. Omitting this flag searches maintainers."
-
+                                 "main repositories: `brew`, `core`, `cask`. " \
+                                 "Specifying `--repositories=all` searches all repositories. "
+        flag   "--from=",
+               description: "Date (ISO 8601 format) to start searching contributions. " \
+                            "Omitting this flag searches the past year."
+        flag   "--to=",
+               description: "Date (ISO 8601 format) to stop searching contributions."
         switch "--csv",
                description: "Print a CSV of contributions across repositories over the time period."
       end
diff --git a/Library/Homebrew/dev-cmd/dispatch-build-bottle.rb b/Library/Homebrew/dev-cmd/dispatch-build-bottle.rb
@@ -35,6 +35,7 @@ class DispatchBuildBottle < AbstractCommand
                description: "Use Debian Wheezy container for building the bottle on Linux."
 
         conflicts "--linux", "--linux-self-hosted"
+
         named_args :formula, min: 1
       end
 
diff --git a/Library/Homebrew/dev-cmd/formula-analytics.rb b/Library/Homebrew/dev-cmd/formula-analytics.rb
@@ -17,19 +17,19 @@ class FormulaAnalytics < AbstractCommand
                description: "Query from the specified days ago until the present. The default is 30 days."
         switch "--install",
                description: "Output the number of specifically requested installations or installation as " \
-                            "dependencies of the formula. This is the default."
+                            "dependencies of formulae. This is the default."
+        switch "--install-on-request",
+               description: "Output the number of specifically requested installations of formulae."
         switch "--cask-install",
                description: "Output the number of installations of casks."
-        switch "--install-on-request",
-               description: "Output the number of specifically requested installations of the formula."
         switch "--build-error",
-               description: "Output the number of build errors for the formulae."
+               description: "Output the number of build errors for formulae."
         switch "--os-version",
-               description: "Output OS versions."
+               description: "Output the number of events by OS name and version."
         switch "--homebrew-devcmdrun-developer",
-               description: "Output devcmdrun/HOMEBREW_DEVELOPER."
+               description: "Output the number of devcmdrun/HOMEBREW_DEVELOPER events."
         switch "--homebrew-os-arch-ci",
-               description: "Output OS/Architecture/CI."
+               description: "Output the number of OS/Architecture/CI events."
         switch "--homebrew-prefixes",
                description: "Output Homebrew prefixes."
         switch "--homebrew-versions",
@@ -47,10 +47,12 @@ class FormulaAnalytics < AbstractCommand
                             "Homebrew/homebrew-core formulae."
         switch "--setup",
                description: "Install the necessary gems, require them and exit without running a query."
+
         conflicts "--install", "--cask-install", "--install-on-request", "--build-error", "--os-version",
                   "--homebrew-devcmdrun-developer", "--homebrew-os-arch-ci", "--homebrew-prefixes",
                   "--homebrew-versions", "--brew-command-run", "--brew-command-run-options", "--brew-test-bot-test"
         conflicts "--json", "--all-core-formulae-json", "--setup"
+
         named_args :none
       end
 
diff --git a/Library/Homebrew/dev-cmd/generate-analytics-api.rb b/Library/Homebrew/dev-cmd/generate-analytics-api.rb
@@ -22,8 +22,7 @@ class GenerateAnalyticsApi < AbstractCommand
 
       cmd_args do
         description <<~EOS
-          Generates analytics API data files for formulae.brew.sh.
-
+          Generates analytics API data files for <#{HOMEBREW_API_WWW}>.
           The generated files are written to the current directory.
         EOS
 
diff --git a/Library/Homebrew/dev-cmd/generate-cask-api.rb b/Library/Homebrew/dev-cmd/generate-cask-api.rb
@@ -21,8 +21,8 @@ class GenerateCaskApi < AbstractCommand
           Generate `homebrew/cask` API data files for <#{HOMEBREW_API_WWW}>.
           The generated files are written to the current directory.
         EOS
-
-        switch "-n", "--dry-run", description: "Generate API data without writing it to files."
+        switch "-n", "--dry-run",
+               description: "Generate API data without writing it to files."
 
         named_args :none
       end
diff --git a/Library/Homebrew/dev-cmd/generate-cask-ci-matrix.rb b/Library/Homebrew/dev-cmd/generate-cask-ci-matrix.rb
@@ -28,7 +28,6 @@ class GenerateCaskCiMatrix < AbstractCommand
           Generate a GitHub Actions matrix for a given pull request URL or list of cask names.
           For internal use in Homebrew taps.
         EOS
-
         switch "--url",
                description: "Treat named argument as a pull request URL."
         switch "--cask", "--casks",
@@ -45,6 +44,7 @@ class GenerateCaskCiMatrix < AbstractCommand
         conflicts "--syntax-only", "--new"
 
         named_args [:cask, :url], min: 0
+
         hide_from_man_page!
       end
 
diff --git a/Library/Homebrew/dev-cmd/generate-formula-api.rb b/Library/Homebrew/dev-cmd/generate-formula-api.rb
@@ -20,8 +20,8 @@ class GenerateFormulaApi < AbstractCommand
           Generate `homebrew/core` API data files for <#{HOMEBREW_API_WWW}>.
           The generated files are written to the current directory.
         EOS
-
-        switch "-n", "--dry-run", description: "Generate API data without writing it to files."
+        switch "-n", "--dry-run",
+               description: "Generate API data without writing it to files."
 
         named_args :none
       end
diff --git a/Library/Homebrew/dev-cmd/generate-man-completions.rb b/Library/Homebrew/dev-cmd/generate-man-completions.rb
@@ -16,6 +16,7 @@ class GenerateManCompletions < AbstractCommand
         description <<~EOS
           Generate Homebrew's manpages and shell completions.
         EOS
+
         named_args :none
       end
 
diff --git a/Library/Homebrew/dev-cmd/livecheck.rb b/Library/Homebrew/dev-cmd/livecheck.rb
@@ -25,7 +25,7 @@ class LivecheckCmd < AbstractCommand
         switch "--installed",
                description: "Check formulae and casks that are currently installed."
         switch "--newer-only",
-               description: "Show the latest version only if it's newer than the formula/cask."
+               description: "Show the latest version only if it's newer than the current formula or cask version."
         switch "--json",
                description: "Output information in JSON format."
         switch "-r", "--resources",
diff --git a/Library/Homebrew/dev-cmd/release.rb b/Library/Homebrew/dev-cmd/release.rb
@@ -21,6 +21,7 @@ class Release < AbstractCommand
                description: "Create a major release."
         switch "--minor",
                description: "Create a minor release."
+
         conflicts "--major", "--minor"
 
         named_args :none
diff --git a/Library/Homebrew/dev-cmd/tap-new.rb b/Library/Homebrew/dev-cmd/tap-new.rb
@@ -17,7 +17,6 @@ class TapNew < AbstractCommand
         description <<~EOS
           Generate the template files for a new tap.
         EOS
-
         switch "--no-git",
                description: "Don't initialize a Git repository for the tap."
         flag   "--pull-label=",
diff --git a/Library/Homebrew/dev-cmd/update-license-data.rb b/Library/Homebrew/dev-cmd/update-license-data.rb
@@ -14,6 +14,7 @@ class UpdateLicenseData < AbstractCommand
         description <<~EOS
           Update SPDX license data in the Homebrew repository.
         EOS
+
         named_args :none
       end
 
diff --git a/Library/Homebrew/dev-cmd/vendor-gems.rb b/Library/Homebrew/dev-cmd/vendor-gems.rb
diff --git a/Library/Homebrew/dev-cmd/verify.rb b/Library/Homebrew/dev-cmd/verify.rb
diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
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
