Merge pull request #20479 from Homebrew/inline-docs-updates

Messaging and comment adjustments

Library/Homebrew/api.rb

@@ -27,7 +27,7 @@ module Homebrew
         api_url = "#{HOMEBREW_API_DEFAULT_DOMAIN}/#{endpoint}"
         output = Utils::Curl.curl_output("--fail", api_url)
       end
-      raise ArgumentError, "No file found at #{Tty.underline}#{api_url}#{Tty.reset}" unless output.success?
+      raise ArgumentError, "No file found at: #{Tty.underline}#{api_url}#{Tty.reset}" unless output.success?
 
       cache[endpoint] = JSON.parse(output.stdout, freeze: true)
     rescue JSON::ParserError

Library/Homebrew/brew.sh

@@ -713,8 +713,8 @@ else
   then
     message="Please update your system curl or set HOMEBREW_CURL_PATH to a newer version.
 Minimum required version: ${HOMEBREW_MINIMUM_CURL_VERSION}
-Your curl version: ${curl_name_and_version##* }
+       Your curl version: ${curl_name_and_version##* }
-Your curl executable: $(type -p "${HOMEBREW_CURL}")"
+    Your curl executable: $(type -p "${HOMEBREW_CURL}")"
 
     if [[ -z ${HOMEBREW_CURL_PATH} ]]
     then
@@ -741,8 +741,8 @@ Your curl executable: $(type -p "${HOMEBREW_CURL}")"
   then
     message="Please update your system Git or set HOMEBREW_GIT_PATH to a newer version.
 Minimum required version: ${HOMEBREW_MINIMUM_GIT_VERSION}
-Your Git version: ${major}.${minor}.${micro}.${build}
+        Your Git version: ${major}.${minor}.${micro}.${build}
-Your Git executable: $(unset git && type -p "${HOMEBREW_GIT}")"
+     Your Git executable: $(unset git && type -p "${HOMEBREW_GIT}")"
     if [[ -z ${HOMEBREW_GIT_PATH} ]]
     then
       HOMEBREW_FORCE_BREWED_GIT="1"

Library/Homebrew/cask/artifact/abstract_uninstall.rb

@@ -389,7 +389,7 @@ module Cask
       end
 
       def uninstall_pkgutil(*pkgs, command: nil, **_)
-        ohai "Uninstalling packages with sudo; the password may be necessary:"
+        ohai "Uninstalling packages with `sudo` (which may request your password)..."
         pkgs.each do |regex|
           ::Cask::Pkg.all_matching(regex, command).each do |pkg|
             puts pkg.package_id

Library/Homebrew/cask/artifact/pkg.rb

@@ -35,7 +35,7 @@ module Cask
       private
 
       def run_installer(command: nil, verbose: false, **_options)
-        ohai "Running installer for #{cask} with sudo; the password may be necessary."
+        ohai "Running installer for #{cask} with `sudo` (which may request your password)..."
         unless path.exist?
           pkg = path.relative_path_from(cask.staged_path)
           pkgs = Pathname.glob(cask.staged_path/"**"/"*.pkg").map { |path| path.relative_path_from(cask.staged_path) }

Library/Homebrew/cask/staged.rb

@@ -25,7 +25,7 @@ module Cask
       full_paths = remove_nonexistent(paths)
       return if full_paths.empty?
 
-      ohai "Changing ownership of paths required by #{@cask} with sudo; the password may be necessary."
+      ohai "Changing ownership of paths required by #{@cask} with `sudo` (which may request your password)..."
       @command.run!("/usr/sbin/chown", args: ["-R", "--", "#{user}:#{group}", *full_paths],
                                        sudo: true)
     end

Library/Homebrew/cmd/deps.rb

@@ -88,8 +88,8 @@ module Homebrew
 
       sig { override.void }
       def run
-        raise UsageError, "`brew deps --os=all` is not supported" if args.os == "all"
+        raise UsageError, "`brew deps --os=all` is not supported." if args.os == "all"
-        raise UsageError, "`brew deps --arch=all` is not supported" if args.arch == "all"
+        raise UsageError, "`brew deps --arch=all` is not supported." if args.arch == "all"
 
         os, arch = T.must(args.os_arch_combinations.first)
         eval_all = args.eval_all?

Library/Homebrew/cmd/install.rb

@@ -181,7 +181,7 @@ module Homebrew
           # `build.rb`. Instead, `hide_from_man_page` and don't do anything with
           # this argument here.
           # This odisabled should stick around indefinitely.
-          odisabled "brew install --env", "`env :std` in specific formula files"
+          odisabled "`brew install --env`", "`env :std` in specific formula files"
         end
 
         args.named.each do |name|

Library/Homebrew/cmd/services.rb

@@ -25,27 +25,27 @@ module Homebrew
           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`):
+          [`sudo`] `brew services` [`list`] [`--json`] [`--debug`]:
           List information about all managed services for the current user (or root).
           Provides more output from Homebrew and `launchctl`(1) or `systemctl`(1) if run with `--debug`.
 
-          [`sudo`] `brew services info` (<formula>|`--all`|`--json`):
+          [`sudo`] `brew services info` (<formula>|`--all`) [`--json`]:
           List all managed services for the current user (or root).
 
-          [`sudo`] `brew services run` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services run` (<formula>|`--all`) [`--file=`]:
           Run the service <formula> without registering to launch at login (or boot).
 
-          [`sudo`] `brew services start` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services start` (<formula>|`--all`) [`--file=`]:
           Start the service <formula> immediately and register it to launch at login (or boot).
 
-          [`sudo`] `brew services stop` (`--keep`) (`--no-wait`|`--max-wait=`) (<formula>|`--all`):
+          [`sudo`] `brew services stop` [`--keep`] [`--no-wait`|`--max-wait=`] (<formula>|`--all`):
           Stop the service <formula> immediately and unregister it from launching at login (or boot),
           unless `--keep` is specified.
 
           [`sudo`] `brew services kill` (<formula>|`--all`):
           Stop the service <formula> immediately but keep it registered to launch at login (or boot).
 
-          [`sudo`] `brew services restart` (<formula>|`--all`|`--file=`):
+          [`sudo`] `brew services restart` (<formula>|`--all`) [`--file=`]:
           Stop (if necessary) and start the service <formula> immediately and register it to launch at login (or boot).
 
           [`sudo`] `brew services cleanup`:
@@ -58,15 +58,16 @@ module Homebrew
         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)."
+        switch "--all",
+               description: "Run <subcommand> on all services."
+        switch "--json",
+               description: "Output as JSON."
 
+        conflicts "--all", "--file"
         conflicts "--max-wait=", "--no-wait"
 
         named_args %w[list info run start stop kill restart cleanup]
@@ -112,7 +113,7 @@ module Homebrew
         ]
         if no_named_formula_commands.include?(subcommand)
           raise UsageError, "The `#{subcommand}` subcommand does not accept a formula argument!" if formulae.present?
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --all argument!" if args.all?
+          raise UsageError, "The `#{subcommand}` subcommand does not accept the `--all` argument!" if args.all?
         end
 
         if args.file
@@ -122,22 +123,22 @@ module Homebrew
             *Homebrew::Services::Commands::Restart::TRIGGERS,
           ]
           if file_commands.exclude?(subcommand)
-            raise UsageError, "The `#{subcommand}` subcommand does not accept the --file= argument!"
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--file=` argument!"
-          elsif args.all?
-            raise UsageError,
-                  "The `#{subcommand}` subcommand does not accept the --all and --file= arguments at the same time!"
           end
         end
 
         unless Homebrew::Services::Commands::Stop::TRIGGERS.include?(subcommand)
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --keep argument!" if args.keep?
+          raise UsageError, "The `#{subcommand}` subcommand does not accept the `--keep` argument!" if args.keep?
-          raise UsageError, "The `#{subcommand}` subcommand does not accept the --no-wait argument!" if args.no_wait?
+
+          if args.no_wait?
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--no-wait` argument!"
+          end
           if args.max_wait
-            raise UsageError, "The `#{subcommand}` subcommand does not accept the --max-wait= argument!"
+            raise UsageError, "The `#{subcommand}` subcommand does not accept the `--max-wait=` argument!"
           end
         end
 
-        opoo "The --all argument overrides provided formula argument!" if formulae.present? && args.all?
+        opoo "The `--all` argument overrides provided formula argument!" if formulae.present? && args.all?
 
         targets = if args.all?
           if subcommand == "start"

Library/Homebrew/cmd/upgrade.rb

@@ -126,7 +126,7 @@ module Homebrew
       sig { override.void }
       def run
         if args.build_from_source? && args.named.empty?
-          raise ArgumentError, "--build-from-source requires at least one formula"
+          raise ArgumentError, "`--build-from-source` requires at least one formula"
         end
 
         formulae, casks = args.named.to_resolved_formulae_to_casks

Library/Homebrew/compilers.rb

@@ -40,7 +40,7 @@ class CompilerFailure
     # Non-Apple compilers are in the format fails_with compiler => version
     if spec.is_a?(Hash)
       compiler, major_version = spec.first
-      raise ArgumentError, "The hash `fails_with` syntax only supports GCC" if compiler != :gcc
+      raise ArgumentError, "The `fails_with` hash syntax only supports GCC" if compiler != :gcc
 
       type = compiler
       # so fails_with :gcc => '7' simply marks all 7 releases incompatible

Library/Homebrew/completions/bash.erb

@@ -3,7 +3,7 @@
 #
 # - For changes to a command under `COMMANDS` or `DEVELOPER COMMANDS` sections):
 #   - Find the source file in `Library/Homebrew/[dev-]cmd/<command>.{rb,sh}`.
-#   - For `.rb` files, edit the `<command>_args` method.
+#   - For `.rb` files, edit the `cmd_args` block.
 #   - For `.sh` files, edit the top comment, being sure to use the line prefix
 #     `#:` for the comments to be recognized as documentation. If in doubt,
 #     compare with already documented commands.

Library/Homebrew/completions/fish.erb

@@ -3,7 +3,7 @@
 #
 # - For changes to a command under `COMMANDS` or `DEVELOPER COMMANDS` sections):
 #   - Find the source file in `Library/Homebrew/[dev-]cmd/<command>.{rb,sh}`.
-#   - For `.rb` files, edit the `<command>_args` method.
+#   - For `.rb` files, edit the `cmd_args` block.
 #   - For `.sh` files, edit the top comment, being sure to use the line prefix
 #     `#:` for the comments to be recognized as documentation. If in doubt,
 #     compare with already documented commands.

Library/Homebrew/completions/zsh.erb

@@ -3,7 +3,7 @@
 #
 # - For changes to a command under `COMMANDS` or `DEVELOPER COMMANDS` sections):
 #   - Find the source file in `Library/Homebrew/[dev-]cmd/<command>.{rb,sh}`.
-#   - For `.rb` files, edit the `<command>_args` method.
+#   - For `.rb` files, edit the `cmd_args` block.
 #   - For `.sh` files, edit the top comment, being sure to use the line prefix
 #     `#:` for the comments to be recognized as documentation. If in doubt,
 #     compare with already documented commands.

Library/Homebrew/dependency_collector.rb

@@ -169,7 +169,7 @@ class DependencyCollector
     when :maximum_macos then MacOSRequirement.new(tags, comparator: "<=")
     when :xcode         then XcodeRequirement.new(tags)
     else
-      raise ArgumentError, "Unsupported special dependency #{spec.inspect}"
+      raise ArgumentError, "Unsupported special dependency: #{spec.inspect}"
     end
   end
 

Library/Homebrew/dev-cmd/audit.rb

@@ -104,7 +104,7 @@ module Homebrew
 
       sig { override.void }
       def run
-        odeprecated "brew audit --token-conflicts" if args.token_conflicts?
+        odeprecated "`brew audit --token-conflicts`" if args.token_conflicts?
 
         Formulary.enable_factory_cache!
 
@@ -142,7 +142,7 @@ module Homebrew
 
             unless eval_all
               # This odisabled should probably stick around indefinitely.
-              odisabled "brew audit",
+              odisabled "`brew audit`",
                         "`brew audit --eval-all` or set `HOMEBREW_EVAL_ALL=1`"
             end
             no_named_args = true
@@ -154,8 +154,8 @@ module Homebrew
             if args.named.any? { |named_arg| named_arg.end_with?(".rb") }
               # This odisabled should probably stick around indefinitely,
               # until at least we have a way to exclude error on these in the CLI parser.
-              odisabled "brew audit [path ...]",
+              odisabled "`brew audit [path ...]`",
-                        "brew audit [name ...]"
+                        "`brew audit [name ...]`"
             end
 
             args.named.to_formulae_and_casks_with_taps

Library/Homebrew/dev-cmd/generate-cask-ci-matrix.rb

@@ -57,15 +57,15 @@ module Homebrew
         syntax_only = args.syntax_only?
 
         repository = ENV.fetch("GITHUB_REPOSITORY", nil)
-        raise UsageError, "The GITHUB_REPOSITORY environment variable must be set." if repository.blank?
+        raise UsageError, "The `$GITHUB_REPOSITORY` environment variable must be set." if repository.blank?
 
         tap = T.let(Tap.fetch(repository), Tap)
 
         unless syntax_only
           raise UsageError, "Either `--cask` or `--url` must be specified." if !args.casks? && !args.url?
-          raise UsageError, "Please provide a cask or url argument" if casks.blank? && pr_url.blank?
+          raise UsageError, "Please provide a `--cask` or `--url` argument." if casks.blank? && pr_url.blank?
         end
-        raise UsageError, "Only one url can be specified" if pr_url&.count&.> 1
+        raise UsageError, "Only one `--url` can be specified." if pr_url&.count&.> 1
 
         labels = if pr_url && (first_pr_url = pr_url.first)
           pr = GitHub::API.open_rest(first_pr_url)

Library/Homebrew/download_strategy.rb

@@ -1600,7 +1600,7 @@ class DownloadStrategyDetector
       detect_from_symbol(using)
     else
       raise TypeError,
-            "Unknown download strategy specification #{using.inspect}"
+            "Unknown download strategy specification: #{using.inspect}"
     end
   end
 

Library/Homebrew/extend/ENV/shared.rb

@@ -267,7 +267,7 @@ module SharedEnvExtension
         ohai "Using a Fortran compiler found at #{gfortran}"
       end
       if gfortran
-        puts "This may be changed by setting the FC environment variable."
+        puts "This may be changed by setting the `$FC` environment variable."
         self["FC"] = self["F77"] = gfortran
         flags = FC_FLAG_VARS
       end

Library/Homebrew/extend/os/mac/diagnostic.rb

@@ -417,7 +417,7 @@ module OS
             macOS won't move relative symlinks across volumes unless the target file already
             exists. Formulae known to be affected by this are Git and Narwhal.
 
-            You should set the "HOMEBREW_TEMP" environment variable to a suitable
+            You should set the `$HOMEBREW_TEMP` environment variable to a suitable
             directory on the same volume as your Cellar.
 
             #{support_tier_message(tier: 2)}

Library/Homebrew/formula_auditor.rb

@@ -791,7 +791,7 @@ module Homebrew
       formula_suffix = stable.version.patch.to_i
       throttled_rate = formula.livecheck.throttle
       if throttled_rate && formula_suffix.modulo(throttled_rate).nonzero?
-        problem "should only be updated every #{throttled_rate} releases on multiples of #{throttled_rate}"
+        problem "Should only be updated every #{throttled_rate} releases on multiples of #{throttled_rate}"
       end
 
       case (url = stable.url)

Library/Homebrew/formula_installer.rb

@@ -382,7 +382,7 @@ class FormulaInstaller
     check_installation_already_attempted
 
     if force_bottle? && !pour_bottle?
-      raise CannotInstallFormulaError, "--force-bottle passed but #{formula.full_name} has no bottle!"
+      raise CannotInstallFormulaError, "`--force-bottle` passed but #{formula.full_name} has no bottle!"
     end
 
     if Homebrew.default_prefix? &&
@@ -477,7 +477,7 @@ class FormulaInstaller
 
     raise CannotInstallFormulaError,
           "You must `brew unpin #{pinned_unsatisfied_deps * " "}` as installing " \
-          "#{formula.full_name} requires the latest version of pinned dependencies"
+          "#{formula.full_name} requires the latest version of pinned dependencies."
   end
 
   sig { params(_formula: Formula).returns(T.nilable(T::Boolean)) }

Library/Homebrew/formulary.rb

@@ -711,7 +711,7 @@ module Formulary
       if ALLOWED_URL_SCHEMES.exclude?(url_scheme)
         raise UnsupportedInstallationMethod,
               "Non-checksummed download of #{name} formula file from an arbitrary URL is unsupported! " \
-              "`brew extract` or `brew create` and `brew tap-new` to create a formula file in a tap " \
+              "Use `brew extract` or `brew create` and `brew tap-new` to create a formula file in a tap " \
               "on GitHub instead."
       end
       HOMEBREW_CACHE_FORMULA.mkpath

Library/Homebrew/install.rb

@@ -83,10 +83,10 @@ module Homebrew
         skip_link: false,
         overwrite: false
       )
-        # head-only without --HEAD is an error
+        # HEAD-only without --HEAD is an error
         if !head && formula.stable.nil?
           odie <<~EOS
-            #{formula.full_name} is a head-only formula.
+            #{formula.full_name} is a HEAD-only formula.
             To install it, run:
               brew install --HEAD #{formula.full_name}
           EOS

Library/Homebrew/language/python.rb

@@ -286,7 +286,7 @@ module Language
       def slice_resources!(resources_hash, resource_names)
         resource_names.map do |resource_name|
           resources_hash.delete(resource_name) do
-            raise ArgumentError, "Resource \"#{resource_name}\" is not defined in formula or is already used"
+            raise ArgumentError, "Resource \"#{resource_name}\" is not defined in formula or is already used."
           end
         end
       end

Library/Homebrew/livecheck/livecheck.rb

@@ -245,7 +245,7 @@ module Homebrew
         end
 
         # Use the `stable` version for comparison except for installed
-        # head-only formulae. A formula with `stable` and `head` that's
+        # HEAD-only formulae. A formula with `stable` and `head` that's
         # installed using `--head` will still use the `stable` version for
         # comparison.
         current = if formula

Library/Homebrew/patch.rb

@@ -24,7 +24,7 @@ module Patch
     when nil
       raise ArgumentError, "nil value for strip"
     else
-      raise ArgumentError, "Unexpected value #{strip.inspect} for strip"
+      raise ArgumentError, "Unexpected value for strip: #{strip.inspect}"
     end
   end
 end

Library/Homebrew/resource_auditor.rb

@@ -45,16 +45,16 @@ module Homebrew
 
     def audit_version
       if version.nil?
-        problem "missing version"
+        problem "Missing version"
       elsif owner.is_a?(Formula) && !version.to_s.match?(GitHubPackages::VALID_OCI_TAG_REGEX) &&
             (owner.core_formula? ||
             (owner.bottle_defined? && GitHubPackages::URL_REGEX.match?(owner.bottle_specification.root_url)))
-        problem "version #{version} does not match #{GitHubPackages::VALID_OCI_TAG_REGEX.source}"
+        problem "`version #{version}` does not match #{GitHubPackages::VALID_OCI_TAG_REGEX.source}"
       elsif !version.detected_from_url?
         version_text = version
         version_url = Version.detect(url, **specs)
         if version_url.to_s == version_text.to_s && version.instance_of?(Version)
-          problem "version #{version_text} is redundant with version scanned from URL"
+          problem "`version #{version_text}` is redundant with version scanned from URL"
         end
       end
     end
@@ -137,7 +137,7 @@ module Homebrew
       # TODO: try remove the OS/env conditional
       if Homebrew::SimulateSystem.simulating_or_running_on_macos? && spec_name == :stable &&
          owner.name != "ca-certificates" && curl_dep && !urls.find { |u| u.start_with?("http://") }
-        problem "should always include at least one HTTP mirror"
+        problem "Should always include at least one HTTP mirror"
       end
 
       return unless @online

Library/Homebrew/sandbox.rb

@@ -258,7 +258,7 @@ class Sandbox
     invalid_char = ['"', "'", "(", ")", "\n", "\\"].find do |c|
       path.to_s.include?(c)
     end
-    raise ArgumentError, "Invalid character #{invalid_char} in path: #{path}" if invalid_char
+    raise ArgumentError, "Invalid character '#{invalid_char}' in path: #{path}" if invalid_char
 
     case type
     when :regex   then "regex #\"#{path}\""

Library/Homebrew/service.rb

@@ -164,7 +164,7 @@ module Homebrew
         @keep_alive = { always: value }
       when Hash
         unless (value.keys - KEEP_ALIVE_KEYS).empty?
-          raise TypeError, "Service#keep_alive allows only #{KEEP_ALIVE_KEYS}"
+          raise TypeError, "Service#keep_alive only allows: #{KEEP_ALIVE_KEYS}"
         end
 
         @keep_alive = value

Library/Homebrew/services/cli.rb

@@ -43,7 +43,7 @@ module Homebrew
 
       # Check if formula has been found.
       def self.check!(targets)
-        raise UsageError, "Formula(e) missing, please provide a formula name or use --all" if targets.empty?
+        raise UsageError, "Formula(e) missing, please provide a formula name or use `--all`." if targets.empty?
 
         true
       end
@@ -71,7 +71,7 @@ module Homebrew
         Dir["#{System.path}homebrew.*.{plist,service}"].each do |file|
           next if running.include?(File.basename(file).sub(/\.(plist|service)$/i, ""))
 
-          puts "Removing unused service file #{file}"
+          puts "Removing unused service file: #{file}"
           rm file
           cleaned << file
         end
@@ -90,7 +90,7 @@ module Homebrew
       def self.run(targets, service_file = nil, verbose: false)
         if service_file.present?
           file = Pathname.new service_file
-          raise UsageError, "Provided service file does not exist" unless file.exist?
+          raise UsageError, "Provided service file does not exist." unless file.exist?
         end
 
         targets.each do |service|
@@ -119,7 +119,7 @@ module Homebrew
 
         if service_file.present?
           file = Pathname.new service_file
-          raise UsageError, "Provided service file does not exist" unless file.exist?
+          raise UsageError, "Provided service file does not exist." unless file.exist?
         end
 
         targets.each do |service|
@@ -373,11 +373,11 @@ module Homebrew
       end
 
       def self.install_service_file(service, file)
-        raise UsageError, "Formula `#{service.name}` is not installed" unless service.installed?
+        raise UsageError, "Formula `#{service.name}` is not installed." unless service.installed?
 
         unless service.service_file.exist?
           raise UsageError,
-                "Formula `#{service.name}` has not implemented #plist, #service or installed a locatable service file"
+                "Formula `#{service.name}` has not implemented #plist, #service or provided a locatable service file."
         end
 
         temp = Tempfile.new(service.service_name)
@@ -386,7 +386,7 @@ module Homebrew
 
           if sudo_service_user && System.launchctl?
             # set the username in the new plist file
-            ohai "Setting username in #{service.service_name} to #{System.user}"
+            ohai "Setting username in #{service.service_name} to: #{System.user}"
             plist_data = Plist.parse_xml(contents, marshal: false)
             plist_data["UserName"] = sudo_service_user
             plist_data.to_plist

Library/Homebrew/shims/shared/curl

@@ -35,5 +35,5 @@ fi
 try_exec_non_system "${HOMEBREW_CURL:-curl}" "$@"
 safe_exec "/usr/bin/curl" "$@"
 
-echo "Could not execute curl. Try HOMEBREW_FORCE_BREWED_CURL=1" >&2
+echo "Could not execute curl. Try setting HOMEBREW_FORCE_BREWED_CURL=1" >&2
 exit 1

Library/Homebrew/shims/shared/git

@@ -1,12 +1,12 @@
 #!/bin/bash -p
 
-# This script because we support $HOMEBREW_GIT, $HOMEBREW_SVN, etc., Xcode-only and
+# This script exists because we support $HOMEBREW_GIT, $HOMEBREW_SVN etc., and Xcode-only
-# no Xcode/CLT configurations. Order is careful to be what the user would want.
+# or no Xcode/CLT configurations. Order is careful to be what the user would want.
 
 # HOMEBREW_LIBRARY is set by bin/brew
 # SHIM_FILE is set by shims/utils.sh
 # HOMEBREW_GIT is set by brew.sh
-# HOMEBREW_SVN is from the user environment.
+# HOMEBREW_SVN is from the user environment
 # HOMEBREW_PREFIX is set by extend/ENV/super.rb
 # shellcheck disable=SC2154
 if [[ -z "${HOMEBREW_LIBRARY}" ]]

Library/Homebrew/test/formula_auditor_spec.rb

@@ -834,7 +834,7 @@ RSpec.describe Homebrew::FormulaAuditor do
       RUBY
 
       fa.audit_specs
-      expect(fa.problems.first[:message]).to match "should only be updated every 10 releases on multiples of 10"
+      expect(fa.problems.first[:message]).to match "Should only be updated every 10 releases on multiples of 10"
     end
 
     it "allows non-versioned formulae to have a `HEAD` spec" do

Library/Homebrew/test/formula_validation_spec.rb

@@ -68,7 +68,7 @@ RSpec.describe Formula do
       end.to fail_with_invalid :version
     end
 
-    specify "head-only is valid" do
+    specify "HEAD-only is valid" do
       f = formula do
         head "foo"
       end

Library/Homebrew/test/service_spec.rb

@@ -68,7 +68,7 @@ RSpec.describe Homebrew::Service do
 
       expect do
         f.service.manual_command
-      end.to raise_error TypeError, "Service#keep_alive allows only [:always, :successful_exit, :crashed, :path]"
+      end.to raise_error TypeError, "Service#keep_alive only allows: [:always, :successful_exit, :crashed, :path]"
     end
   end
 

Library/Homebrew/test/services/cli_spec.rb

@@ -46,14 +46,15 @@ RSpec.describe Homebrew::Services::Cli do
     it "checks the input does not exist" do
       expect do
         services_cli.check!([])
-      end.to raise_error(UsageError, "Invalid usage: Formula(e) missing, please provide a formula name or use --all")
+      end.to raise_error(UsageError,
+                         "Invalid usage: Formula(e) missing, please provide a formula name or use `--all`.")
     end
 
     it "checks the input exists" do
       expect do
         services_cli.check!("hello")
       end.not_to raise_error(UsageError,
-                             "Invalid usage: Formula(e) missing, please provide a formula name or use --all")
+                             "Invalid usage: Formula(e) missing, please provide a formula name or use `--all`.")
     end
   end
 
@@ -88,7 +89,7 @@ RSpec.describe Homebrew::Services::Cli do
       expect(Homebrew::Services::System).not_to receive(:root?)
       expect do
         services_cli.start(["service_name"], "/non/existent/path")
-      end.to raise_error(UsageError, "Invalid usage: Provided service file does not exist")
+      end.to raise_error(UsageError, "Invalid usage: Provided service file does not exist.")
     end
 
     it "checks empty targets cause no error" do
@@ -111,7 +112,7 @@ RSpec.describe Homebrew::Services::Cli do
       expect(Homebrew::Services::System).not_to receive(:root?)
       expect do
         services_cli.start(["service_name"], "/hfdkjshksdjhfkjsdhf/fdsjghsdkjhb")
-      end.to raise_error(UsageError, "Invalid usage: Provided service file does not exist")
+      end.to raise_error(UsageError, "Invalid usage: Provided service file does not exist.")
     end
 
     it "checks empty targets cause no error" do
@@ -164,7 +165,7 @@ RSpec.describe Homebrew::Services::Cli do
       service = instance_double(Homebrew::Services::FormulaWrapper, name: "name", installed?: false)
       expect do
         services_cli.install_service_file(service, nil)
-      end.to raise_error(UsageError, "Invalid usage: Formula `name` is not installed")
+      end.to raise_error(UsageError, "Invalid usage: Formula `name` is not installed.")
     end
 
     it "checks service file exists" do
@@ -178,7 +179,7 @@ RSpec.describe Homebrew::Services::Cli do
         services_cli.install_service_file(service, nil)
       end.to raise_error(
         UsageError,
-        "Invalid usage: Formula `name` has not implemented #plist, #service or installed a locatable service file",
+        "Invalid usage: Formula `name` has not implemented #plist, #service or provided a locatable service file.",
       )
     end
   end

Library/Homebrew/test/services/commands/info_spec.rb

@@ -17,7 +17,8 @@ RSpec.describe Homebrew::Services::Commands::Info do
     it "fails with empty list" do
       expect do
         described_class.run([], verbose: false, json: false)
-      end.to raise_error UsageError, "Invalid usage: Formula(e) missing, please provide a formula name or use --all"
+      end.to raise_error UsageError,
+                         "Invalid usage: Formula(e) missing, please provide a formula name or use `--all`."
     end
 
     it "succeeds with items" do

Library/Homebrew/test/services/commands/restart_spec.rb

@@ -13,7 +13,8 @@ RSpec.describe Homebrew::Services::Commands::Restart do
     it "fails with empty list" do
       expect do
         described_class.run([], nil, verbose: false)
-      end.to raise_error UsageError, "Invalid usage: Formula(e) missing, please provide a formula name or use --all"
+      end.to raise_error UsageError,
+                         "Invalid usage: Formula(e) missing, please provide a formula name or use `--all`."
     end
 
     it "starts if services are not loaded" do

Library/Homebrew/test/version_spec.rb

@@ -104,7 +104,7 @@ RSpec.describe Version do
       it "raises an error" do
         expect do
           null_version.to_str
-        end.to raise_error NoMethodError, "undefined method `to_str' for Version:NULL"
+        end.to raise_error NoMethodError, "undefined method `to_str` for Version:NULL"
       end
     end
 

Library/Homebrew/utils/github/api.rb

@@ -123,7 +123,7 @@ module GitHub
       end
     end
 
-    # Error when the user has no GitHub API credentials set at all (macOS keychain, GitHub CLI or envvar).
+    # Error when the user has no GitHub API credentials set at all (macOS keychain, GitHub CLI or env var).
     class MissingAuthenticationError < Error
       sig { void }
       def initialize

Library/Homebrew/version.rb

@@ -723,7 +723,7 @@ class Version
   # @api public
   sig { returns(String) }
   def to_str
-    raise NoMethodError, "undefined method `to_str' for #{self.class}:NULL" if null?
+    raise NoMethodError, "undefined method `to_str` for #{self.class}:NULL" if null?
 
     T.must(version).to_str
   end

completions/zsh/_brew

@@ -1909,9 +1909,9 @@ _brew_search() {
 # brew services
 _brew_services() {
   _arguments \
-    '--all[Run subcommand on all services]' \
+    '(--file)--all[Run subcommand on all services]' \
     '--debug[Display any debugging information]' \
-    '--file[Use the service file from this location to `start` the service]' \
+    '(--all)--file[Use the service file from this location to `start` the service]' \
     '--help[Show this message]' \
     '--json[Output as JSON]' \
     '--keep[When stopped, don'\''t unregister the service from launching at login (or boot)]' \

docs/Manpage.md

@@ -1411,26 +1411,26 @@ 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`)
+\[`sudo`\] `brew services` \[`list`\] \[`--json`\] \[`--debug`\]
 
 : List information about all managed services for the current user (or root).
   Provides more output from Homebrew and `launchctl`(1) or `systemctl`(1) if run
   with `--debug`.
 
-\[`sudo`\] `brew services info` (*`formula`*\|`--all`\|`--json`)
+\[`sudo`\] `brew services info` (*`formula`*\|`--all`) \[`--json`\]
 
 : List all managed services for the current user (or root).
 
-\[`sudo`\] `brew services run` (*`formula`*\|`--all`\|`--file=`)
+\[`sudo`\] `brew services run` (*`formula`*\|`--all`) \[`--file=`\]
 
 : Run the service *`formula`* without registering to launch at login (or boot).
 
-\[`sudo`\] `brew services start` (*`formula`*\|`--all`\|`--file=`)
+\[`sudo`\] `brew services start` (*`formula`*\|`--all`) \[`--file=`\]
 
 : Start the service *`formula`* immediately and register it to launch at login
   (or boot).
 
-\[`sudo`\] `brew services stop` (`--keep`) (`--no-wait`\|`--max-wait=`) (*`formula`*\|`--all`)
+\[`sudo`\] `brew services stop` \[`--keep`\] \[`--no-wait`\|`--max-wait=`\] (*`formula`*\|`--all`)
 
 : Stop the service *`formula`* immediately and unregister it from launching at
   login (or boot), unless `--keep` is specified.
@@ -1440,7 +1440,7 @@ If `sudo` is passed, operate on `/Library/LaunchDaemons` or
 : Stop the service *`formula`* immediately but keep it registered to launch at
   login (or boot).
 
-\[`sudo`\] `brew services restart` (*`formula`*\|`--all`\|`--file=`)
+\[`sudo`\] `brew services restart` (*`formula`*\|`--all`) \[`--file=`\]
 
 : Stop (if necessary) and start the service *`formula`* immediately and register
   it to launch at login (or boot).
@@ -1462,14 +1462,6 @@ If `sudo` is passed, operate on `/Library/LaunchDaemons` or
 : 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.
 
-`--all`
-
-: Run *`subcommand`* on all services.
-
-`--json`
-
-: Output as JSON.
-
 `--no-wait`
 
 : Don't wait for `stop` to finish stopping the service.
@@ -1478,6 +1470,14 @@ If `sudo` is passed, operate on `/Library/LaunchDaemons` or
 
 : When stopped, don't unregister the service from launching at login (or boot).
 
+`--all`
+
+: Run *`subcommand`* on all services.
+
+`--json`
+
+: Output as JSON.
+
 ### `setup-ruby` \[*`command`* ...\]
 
 Installs and configures Homebrew's Ruby. If `command` is passed, it will only

manpages/brew.1

@@ -879,25 +879,25 @@ Manage background services with macOS\[u2019] \fBlaunchctl\fP(1) daemon manager
 .P
 If \fBsudo\fP is passed, operate on \fB/Library/LaunchDaemons\fP or \fB/usr/lib/systemd/system\fP (started at boot)\. Otherwise, operate on \fB~/Library/LaunchAgents\fP or \fB~/\.config/systemd/user\fP (started at login)\.
 .TP
-[\fBsudo\fP] \fBbrew services\fP [\fBlist\fP] (\fB\-\-json\fP) (\fB\-\-debug\fP)
+[\fBsudo\fP] \fBbrew services\fP [\fBlist\fP] [\fB\-\-json\fP] [\fB\-\-debug\fP]
 List information about all managed services for the current user (or root)\. Provides more output from Homebrew and \fBlaunchctl\fP(1) or \fBsystemctl\fP(1) if run with \fB\-\-debug\fP\&\.
 .TP
-[\fBsudo\fP] \fBbrew services info\fP (\fIformula\fP|\fB\-\-all\fP|\fB\-\-json\fP)
+[\fBsudo\fP] \fBbrew services info\fP (\fIformula\fP|\fB\-\-all\fP) [\fB\-\-json\fP]
 List all managed services for the current user (or root)\.
 .TP
-[\fBsudo\fP] \fBbrew services run\fP (\fIformula\fP|\fB\-\-all\fP|\fB\-\-file=\fP)
+[\fBsudo\fP] \fBbrew services run\fP (\fIformula\fP|\fB\-\-all\fP) [\fB\-\-file=\fP]
 Run the service \fIformula\fP without registering to launch at login (or boot)\.
 .TP
-[\fBsudo\fP] \fBbrew services start\fP (\fIformula\fP|\fB\-\-all\fP|\fB\-\-file=\fP)
+[\fBsudo\fP] \fBbrew services start\fP (\fIformula\fP|\fB\-\-all\fP) [\fB\-\-file=\fP]
 Start the service \fIformula\fP immediately and register it to launch at login (or boot)\.
 .TP
-[\fBsudo\fP] \fBbrew services stop\fP (\fB\-\-keep\fP) (\fB\-\-no\-wait\fP|\fB\-\-max\-wait=\fP) (\fIformula\fP|\fB\-\-all\fP)
+[\fBsudo\fP] \fBbrew services stop\fP [\fB\-\-keep\fP] [\fB\-\-no\-wait\fP|\fB\-\-max\-wait=\fP] (\fIformula\fP|\fB\-\-all\fP)
 Stop the service \fIformula\fP immediately and unregister it from launching at login (or boot), unless \fB\-\-keep\fP is specified\.
 .TP
 [\fBsudo\fP] \fBbrew services kill\fP (\fIformula\fP|\fB\-\-all\fP)
 Stop the service \fIformula\fP immediately but keep it registered to launch at login (or boot)\.
 .TP
-[\fBsudo\fP] \fBbrew services restart\fP (\fIformula\fP|\fB\-\-all\fP|\fB\-\-file=\fP)
+[\fBsudo\fP] \fBbrew services restart\fP (\fIformula\fP|\fB\-\-all\fP) [\fB\-\-file=\fP]
 Stop (if necessary) and start the service \fIformula\fP immediately and register it to launch at login (or boot)\.
 .TP
 [\fBsudo\fP] \fBbrew services cleanup\fP
@@ -912,17 +912,17 @@ When run as root on macOS, run the service(s) as this user\.
 \fB\-\-max\-wait\fP
 Wait at most this many seconds for \fBstop\fP to finish stopping a service\. Defaults to 60\. Set this to zero (0) seconds to wait indefinitely\.
 .TP
-\fB\-\-all\fP
-Run \fIsubcommand\fP on all services\.
-.TP
-\fB\-\-json\fP
-Output as JSON\.
-.TP
 \fB\-\-no\-wait\fP
 Don\[u2019]t wait for \fBstop\fP to finish stopping the service\.
 .TP
 \fB\-\-keep\fP
 When stopped, don\[u2019]t unregister the service from launching at login (or boot)\.
+.TP
+\fB\-\-all\fP
+Run \fIsubcommand\fP on all services\.
+.TP
+\fB\-\-json\fP
+Output as JSON\.
 .SS "\fBsetup\-ruby\fP \fR[\fIcommand\fP \.\.\.]"
 Installs and configures Homebrew\[u2019]s Ruby\. If \fBcommand\fP is passed, it will only run Bundler if necessary for that command\.
 .SS "\fBshellenv\fP \fR[\fIshell\fP \.\.\.]"