Merge pull request #6835 from EricFromCanada/input-handling

cmd/dev-cmd: improve handling of invalid input

Library/Homebrew/cli/parser.rb

@@ -34,6 +34,7 @@ module Homebrew
         @conflicts = []
         @switch_sources = {}
         @processed_options = []
+        @max_named_args = nil
         @hide_from_man_page = false
         instance_eval(&block)
         post_initialize
@@ -139,6 +140,7 @@ module Homebrew
           raise e
         end
         check_constraint_violations
+        check_named_args(remaining_args)
         @args[:remaining] = remaining_args
         @args.freeze_processed_options!(@processed_options)
         Homebrew.args = @args
@@ -178,6 +180,10 @@ module Homebrew
         []
       end
 
+      def max_named(count)
+        @max_named_args = count
+      end
+
       def hide_from_man_page!
         @hide_from_man_page = true
       end
@@ -269,6 +275,10 @@ module Homebrew
         check_constraints
       end
 
+      def check_named_args(args)
+        raise NamedArgumentsError, @max_named_args if !@max_named_args.nil? && args.size > @max_named_args
+      end
+
       def process_option(*args)
         option, = @parser.make_switch(args)
         @processed_options << [option.short.first, option.long.first, option.arg, option.desc.first]
@@ -277,14 +287,10 @@ module Homebrew
 
     class OptionConstraintError < RuntimeError
       def initialize(arg1, arg2, missing: false)
-        if !missing
+        message = if !missing
-          message = <<~EOS
+          "`#{arg1}` and `#{arg2}` should be passed together."
-            `#{arg1}` and `#{arg2}` should be passed together.
-          EOS
         else
-          message = <<~EOS
+          "`#{arg2}` cannot be passed without `#{arg1}`."
-            `#{arg2}` cannot be passed without `#{arg1}`.
-          EOS
         end
         super message
       end
@@ -294,17 +300,27 @@ module Homebrew
       def initialize(args)
         args_list = args.map(&Formatter.public_method(:option))
                         .join(" and ")
-        super <<~EOS
+        super "Options #{args_list} are mutually exclusive."
-          Options #{args_list} are mutually exclusive.
-        EOS
       end
     end
 
     class InvalidConstraintError < RuntimeError
       def initialize(arg1, arg2)
-        super <<~EOS
+        super "`#{arg1}` and `#{arg2}` cannot be mutually exclusive and mutually dependent simultaneously."
-          `#{arg1}` and `#{arg2}` cannot be mutually exclusive and mutually dependent simultaneously.
+      end
-        EOS
+    end
+
+    class NamedArgumentsError < UsageError
+      def initialize(maximum)
+        message = case maximum
+        when 0
+          "This command does not take named arguments."
+        when 1
+          "This command does not take multiple named arguments."
+        else
+          "This command does not take more than #{maximum} named arguments."
+        end
+        super message
       end
     end
   end

Library/Homebrew/cmd/--env.rb

@@ -11,7 +11,7 @@ module Homebrew
   def __env_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `--env` [<options>]
+        `--env` [<options>] [<formula>]
 
         Summarise Homebrew's build environment as a plain list.
 

Library/Homebrew/cmd/--version.rb

@@ -13,14 +13,13 @@ module Homebrew
         Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask
         (if tapped) to standard output.
       EOS
+      max_named 0
     end
   end
 
   def __version
     __version_args.parse
 
-    odie "This command does not take arguments." if ARGV.any?
-
     puts "Homebrew #{HOMEBREW_VERSION}"
     puts "#{CoreTap.instance.full_name} #{CoreTap.instance.version_string}"
     puts "#{Tap.default_cask_tap.full_name} #{Tap.default_cask_tap.version_string}" if Tap.default_cask_tap.installed?

Library/Homebrew/cmd/analytics.rb

@@ -19,14 +19,13 @@ module Homebrew
       EOS
       switch :verbose
       switch :debug
+      max_named 1
     end
   end
 
   def analytics
     analytics_args.parse
 
-    raise UsageError if args.remaining.size > 1
-
     case args.remaining.first
     when nil, "state"
       if Utils::Analytics.disabled?
@@ -42,7 +41,7 @@ module Homebrew
     when "regenerate-uuid"
       Utils::Analytics.regenerate_uuid!
     else
-      raise UsageError
+      raise UsageError, "Unknown subcommand."
     end
   end
 end

Library/Homebrew/cmd/cat.rb

@@ -12,17 +12,17 @@ module Homebrew
 
         Display the source of <formula>.
       EOS
+      max_named 1
     end
   end
 
   def cat
     cat_args.parse
     # do not "fix" this to support multiple arguments, the output would be
-    # unparsable, if the user wants to cat multiple formula they can call
+    # unparsable; if the user wants to cat multiple formula they can call
-    # brew cat multiple times.
+    # `brew cat` multiple times.
     formulae = Homebrew.args.formulae
     raise FormulaUnspecifiedError if formulae.empty?
-    raise "`brew cat` doesn't support multiple arguments" if args.remaining.size > 1
 
     cd HOMEBREW_REPOSITORY
     pager = if ENV["HOMEBREW_BAT"].nil?

Library/Homebrew/cmd/cleanup.rb

@@ -21,7 +21,7 @@ module Homebrew
              description: "Show what would be removed, but do not actually remove anything."
       switch "-s",
              description: "Scrub the cache, including downloads for even the latest versions. "\
-                          "Note downloads for any installed formula or cask will still not be deleted. "\
+                          "Note downloads for any installed formulae or casks will still not be deleted. "\
                           "If you want to delete those too: `rm -rf \"$(brew --cache)\"`"
       switch "--prune-prefix",
              description: "Only prune the symlinks and directories from the prefix and remove no other files."

Library/Homebrew/cmd/command.rb

@@ -20,17 +20,18 @@ module Homebrew
 
   def command
     command_args.parse
-    abort "This command requires a command argument" if args.remaining.empty?
 
-    cmd = HOMEBREW_INTERNAL_COMMAND_ALIASES.fetch(args.remaining.first, args.remaining.first)
+    raise UsageError, "This command requires a command argument" if args.remaining.empty?
 
-    path = Commands.path(cmd)
+    args.remaining.each do |c|
+      cmd = HOMEBREW_INTERNAL_COMMAND_ALIASES.fetch(c, c)
+      path = Commands.path(cmd)
+      cmd_paths = PATH.new(ENV["PATH"]).append(Tap.cmd_directories) unless path
+      path ||= which("brew-#{cmd}", cmd_paths)
+      path ||= which("brew-#{cmd}.rb", cmd_paths)
 
-    cmd_paths = PATH.new(ENV["PATH"]).append(Tap.cmd_directories) unless path
+      odie "Unknown command: #{cmd}" unless path
-    path ||= which("brew-#{cmd}", cmd_paths)
+      puts path
-    path ||= which("brew-#{cmd}.rb", cmd_paths)
+    end
-
-    odie "Unknown command: #{cmd}" unless path
-    puts path
   end
 end

Library/Homebrew/cmd/commands.rb

@@ -19,6 +19,7 @@ module Homebrew
              description: "Include aliases of internal commands."
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 

Library/Homebrew/cmd/config.rb

@@ -16,12 +16,12 @@ module Homebrew
       EOS
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 
   def config
     config_args.parse
-    raise UsageError unless args.remaining.empty?
 
     SystemConfig.dump_verbose_config
   end

Library/Homebrew/cmd/desc.rb

@@ -40,11 +40,7 @@ module Homebrew
     search_type << :either if args.search
     search_type << :name   if args.name
     search_type << :desc   if args.description
-    if search_type.size > 1
+    odie "You must provide a search term." if search_type.present? && ARGV.named.empty?
-      odie "Pick one, and only one, of -s/--search, -n/--name, or -d/--description."
-    elsif search_type.present? && ARGV.named.empty?
-      odie "You must provide a search term."
-    end
 
     results = if search_type.empty?
       raise FormulaUnspecifiedError if ARGV.named.empty?

Library/Homebrew/cmd/diy.rb

@@ -21,6 +21,7 @@ module Homebrew
              description: "Explicitly set the <version> of the package being installed."
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 
@@ -47,7 +48,6 @@ module Homebrew
 
   def detect_version(path)
     version = path.version.to_s
-
     raise "Couldn't determine version, set it with --version=<version>" if version.empty?
 
     version

Library/Homebrew/cmd/doctor.rb

@@ -18,7 +18,8 @@ module Homebrew
         an issue; just ignore this.
       EOS
       switch "--list-checks",
-             description: "List all audit methods."
+             description: "List all audit methods, which can be run individually "\
+                          "if provided as arguments."
       switch "-D", "--audit-debug",
              description: "Enable debugging and profiling of audit methods."
       switch :verbose

Library/Homebrew/cmd/gist-logs.rb

@@ -28,6 +28,7 @@ module Homebrew
                           "be accessible with its link."
       switch :verbose
       switch :debug
+      max_named 1
     end
   end
 

Library/Homebrew/cmd/info.rb

@@ -61,25 +61,29 @@ module Homebrew
 
   def info
     info_args.parse
+
     if args.days.present?
-      raise UsageError, "days must be one of #{VALID_DAYS.join(", ")}" unless VALID_DAYS.include?(args.days)
+      raise UsageError, "--days must be one of #{VALID_DAYS.join(", ")}" unless VALID_DAYS.include?(args.days)
     end
 
     if args.category.present?
       if ARGV.named.present? && !VALID_FORMULA_CATEGORIES.include?(args.category)
-        raise UsageError, "category must be one of #{VALID_FORMULA_CATEGORIES.join(", ")} when querying formulae"
+        raise UsageError, "--category must be one of #{VALID_FORMULA_CATEGORIES.join(", ")} when querying formulae"
       end
 
       unless VALID_CATEGORIES.include?(args.category)
-        raise UsageError, "category must be one of #{VALID_CATEGORIES.join(", ")}"
+        raise UsageError, "--category must be one of #{VALID_CATEGORIES.join(", ")}"
       end
     end
 
     if args.json
-      raise UsageError, "invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
+      raise UsageError, "Invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
+      raise UsageError, "This command's option requires a formula argument" if ARGV.named.empty?
 
       print_json
     elsif args.github?
+      raise UsageError, "This command's option requires a formula argument" if ARGV.named.empty?
+
       exec_browser(*Homebrew.args.formulae.map { |f| github_info(f) })
     else
       print_info

Library/Homebrew/cmd/install.rb

@@ -101,6 +101,7 @@ module Homebrew
     end
 
     install_args.parse
+
     raise FormulaUnspecifiedError if args.remaining.empty?
 
     if args.ignore_dependencies?

Library/Homebrew/cmd/leaves.rb

@@ -15,6 +15,7 @@ module Homebrew
         List installed formulae that are not dependencies of another installed formula.
       EOS
       switch :debug
+      max_named 0
     end
   end
 

Library/Homebrew/cmd/link.rb

@@ -48,7 +48,10 @@ module Homebrew
         else
           keg.name
         end
-        puts "To relink: brew unlink #{keg.name} && brew link #{name_and_flag}"
+        puts <<~EOS
+          To relink:
+            brew unlink #{keg.name} && brew link #{name_and_flag}
+        EOS
         next
       end
 

Library/Homebrew/cmd/log.rb

@@ -22,6 +22,7 @@ module Homebrew
              description: "Print only one line per commit."
       flag   "-1", "--max-count",
              description: "Print only one or a specified number of commits."
+      max_named 1
     end
   end
 

Library/Homebrew/cmd/missing.rb

@@ -27,6 +27,7 @@ module Homebrew
 
   def missing
     missing_args.parse
+
     return unless HOMEBREW_CELLAR.exist?
 
     ff = if ARGV.named.empty?

Library/Homebrew/cmd/outdated.rb

@@ -10,7 +10,7 @@ module Homebrew
   def outdated_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `outdated` [<options>]
+        `outdated` [<options>] [<formula>]
 
         List installed formulae that have an updated version available. By default, version
         information is displayed in interactive shells, and suppressed otherwise.
@@ -41,7 +41,7 @@ module Homebrew
       ARGV.resolved_formulae
     end
     if args.json
-      raise UsageError, "invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
+      raise UsageError, "Invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
 
       outdated = print_outdated_json(formulae)
     else

Library/Homebrew/cmd/postinstall.rb

@@ -23,6 +23,8 @@ module Homebrew
   def postinstall
     postinstall_args.parse
 
+    raise KegUnspecifiedError if args.remaining.empty?
+
     ARGV.resolved_formulae.each do |f|
       ohai "Postinstalling #{f}"
       fi = FormulaInstaller.new(f)

Library/Homebrew/cmd/readall.rb

@@ -14,7 +14,7 @@ module Homebrew
         Import all formulae from the specified <tap>, or from all installed taps if none is provided.
         This can be useful for debugging issues across all formulae when making
         significant changes to `formula.rb`, testing the performance of loading
-        all formulae or to determine if any current formulae have Ruby issues.
+        all formulae or checking if any current formulae have Ruby issues.
       EOS
       switch "--aliases",
              description: "Verify any alias symlinks in each tap."

Library/Homebrew/cmd/reinstall.rb

@@ -47,6 +47,8 @@ module Homebrew
   def reinstall
     reinstall_args.parse
 
+    raise FormulaUnspecifiedError if args.remaining.empty?
+
     FormulaInstaller.prevent_build_flags unless DevelopmentTools.installed?
 
     Install.perform_preinstall_checks

Library/Homebrew/cmd/sh.rb

@@ -22,11 +22,13 @@ module Homebrew
              description: "Use the standard `PATH` instead of superenv's when `std` is passed."
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 
   def sh
     sh_args.parse
+
     ENV.activate_extensions!
 
     if superenv?

Library/Homebrew/cmd/switch.rb

@@ -14,46 +14,33 @@ module Homebrew
 
         Symlink all of the specified <version> of <formula>'s installation into Homebrew's prefix.
       EOS
-      switch_option :verbose
+      switch :verbose
-      switch_option :debug
+      switch :debug
+      max_named 2
     end
   end
 
   def switch
     switch_args.parse
+
+    raise FormulaUnspecifiedError if args.remaining.empty?
+
     name = args.remaining.first
-
-    usage = "Usage: brew switch <formula> <version>"
-
-    unless name
-      onoe usage
-      exit 1
-    end
-
     rack = Formulary.to_rack(name)
 
-    unless rack.directory?
+    odie "#{name} not found in the Cellar." unless rack.directory?
-      onoe "#{name} not found in the Cellar."
-      exit 2
-    end
 
     versions = rack.subdirs
                    .map { |d| Keg.new(d).version }
                    .sort
                    .join(", ")
     version = args.remaining.second
+    raise UsageError, "Specify one of #{name}'s installed versions: #{versions}" unless version
 
-    if !version || args.remaining.length > 2
+    odie <<~EOS unless (rack/version).directory?
-      onoe usage
+      #{name} does not have a version \"#{version}\" in the Cellar.
-      puts "#{name} installed versions: #{versions}"
+      #{name}'s installed versions: #{versions}
-      exit 1
+    EOS
-    end
-
-    unless (rack/version).directory?
-      onoe "#{name} does not have a version \"#{version}\" in the Cellar."
-      puts "#{name} installed versions: #{versions}"
-      exit 3
-    end
 
     # Unlink all existing versions
     rack.subdirs.each do |v|

Library/Homebrew/cmd/tap-info.rb

@@ -36,7 +36,7 @@ module Homebrew
     end
 
     if args.json
-      raise UsageError, "invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
+      raise UsageError, "Invalid JSON version: #{args.json}" unless ["v1", true].include? args.json
 
       print_tap_json(taps.sort_by(&:to_s))
     else

Library/Homebrew/cmd/tap.rb

@@ -38,6 +38,7 @@ module Homebrew
       switch "-q", "--quieter",
              description: "Suppress any warnings."
       switch :debug
+      max_named 2
     end
   end
 

Library/Homebrew/cmd/uninstall.rb

@@ -79,7 +79,7 @@ module Homebrew
             if rack.directory?
               versions = rack.subdirs.map(&:basename)
               puts "#{keg.name} #{versions.to_sentence} #{"is".pluralize(versions.count)} still installed."
-              puts "Remove all versions with `brew uninstall --force #{keg.name}`."
+              puts "Run `brew uninstall --force #{keg.name}` to remove all versions."
             end
           end
         end
@@ -87,7 +87,7 @@ module Homebrew
     end
   rescue MultipleVersionsInstalledError => e
     ofail e
-    puts "Use `brew uninstall --force #{e.name}` to remove all versions."
+    puts "Run `brew uninstall --force #{e.name}` to remove all versions."
   ensure
     # If we delete Cellar/newname, then Cellar/oldname symlink
     # can become broken and we have to remove it.

Library/Homebrew/cmd/untap.rb

@@ -19,11 +19,11 @@ module Homebrew
   def untap
     untap_args.parse
 
-    raise "Usage is `brew untap <tap-name>`" if args.remaining.empty?
+    raise UsageError, "This command requires a tap argument from `brew tap`'s list" if args.remaining.empty?
 
     ARGV.named.each do |tapname|
       tap = Tap.fetch(tapname)
-      raise "untapping #{tap} is not allowed" if tap.core_tap?
+      odie "Untapping #{tap} is not allowed" if tap.core_tap?
 
       tap.uninstall
     end

Library/Homebrew/cmd/update.sh

@@ -314,7 +314,7 @@ homebrew-update() {
       *)
         odie <<EOS
 This command updates brew itself, and does not take formula names.
-Use 'brew upgrade $@' instead.
+Use \`brew upgrade $@\` instead.
 EOS
         ;;
     esac
@@ -511,7 +511,7 @@ EOS
           if [[ "$UPSTREAM_SHA_HTTP_CODE" = "404" ]]
           then
             TAP="${DIR#$HOMEBREW_LIBRARY/Taps/}"
-            echo "$TAP does not exist! Run 'brew untap $TAP'" >>"$update_failed_file"
+            echo "$TAP does not exist! Run \`brew untap $TAP\` to remove it." >>"$update_failed_file"
           else
             echo "Fetching $DIR failed!" >>"$update_failed_file"
           fi

Library/Homebrew/dev-cmd/audit.rb

@@ -57,7 +57,8 @@ module Homebrew
       switch :verbose
       switch :debug
       conflicts "--only", "--except"
-      conflicts "--only-cops", "--except-cops"
+      conflicts "--only-cops", "--except-cops", "--strict"
+      conflicts "--only-cops", "--except-cops", "--only"
     end
   end
 
@@ -88,13 +89,6 @@ module Homebrew
 
     only_cops = args.only_cops
     except_cops = args.except_cops
-
-    if only_cops && except_cops
-      odie "--only-cops and --except-cops cannot be used simultaneously!"
-    elsif (only_cops || except_cops) && (strict || args.only)
-      odie "--only-cops/--except-cops and --strict/--only cannot be used simultaneously!"
-    end
-
     options = { fix: args.fix? }
 
     if only_cops
@@ -995,7 +989,6 @@ module Homebrew
     def audit
       only_audits = @only
       except_audits = @except
-      odie "--only and --except cannot be used simultaneously!" if only_audits && except_audits
 
       methods.map(&:to_s).grep(/^audit_/).each do |audit_method_name|
         name = audit_method_name.gsub(/^audit_/, "")

Library/Homebrew/dev-cmd/bottle.rb

@@ -86,6 +86,7 @@ module Homebrew
     bottle_args.parse
 
     return merge if args.merge?
+    raise KegUnspecifiedError if args.remaining.empty?
 
     ensure_relocation_formulae_installed! unless args.skip_relocation?
     ARGV.resolved_formulae.each do |f|
@@ -219,7 +220,7 @@ module Homebrew
       return
     end
 
-    return ofail "Formula not installed with '--build-bottle': #{f.full_name}" unless Utils::Bottles.built_as? f
+    return ofail "Formula was not installed with --build-bottle: #{f.full_name}" unless Utils::Bottles.built_as? f
 
     return ofail "Formula has no stable version: #{f.full_name}" unless f.stable
 
@@ -426,6 +427,7 @@ module Homebrew
 
   def merge
     write = args.write?
+    raise UsageError, "--merge requires a JSON file path argument" if ARGV.named.empty?
 
     bottles_hash = ARGV.named.reduce({}) do |hash, json_file|
       hash.deep_merge(JSON.parse(IO.read(json_file)))

Library/Homebrew/dev-cmd/bump-formula-pr.rb

@@ -65,6 +65,7 @@ module Homebrew
       switch :debug
       conflicts "--no-audit", "--strict"
       conflicts "--url", "--tag"
+      max_named 1
     end
   end
 
@@ -504,6 +505,6 @@ module Homebrew
 
     formula.path.atomic_write(backup_file)
     FileUtils.mv alias_rename.last, alias_rename.first if alias_rename.present?
-    odie "brew audit failed!"
+    odie "`brew audit` failed!"
   end
 end

Library/Homebrew/dev-cmd/bump-revision.rb

@@ -22,6 +22,7 @@ module Homebrew
       switch :quiet
       switch :verbose
       switch :debug
+      max_named 1
     end
   end
 
@@ -34,7 +35,6 @@ module Homebrew
 
     formulae = Homebrew.args.formulae
     raise FormulaUnspecifiedError if formulae.empty?
-    raise "Multiple formulae given, only one is allowed." if formulae.length > 1
 
     formula = formulae.first
     current_revision = formula.revision

Library/Homebrew/dev-cmd/create.rb

@@ -49,6 +49,7 @@ module Homebrew
       switch :verbose
       switch :debug
       conflicts "--autotools", "--cmake", "--go", "--meson", "--perl", "--python", "--rust"
+      max_named 1
     end
   end
 

Library/Homebrew/dev-cmd/extract.rb

@@ -91,6 +91,7 @@ module Homebrew
              description: "Extract the specified <version> of <formula> instead of the most recent."
       switch :force
       switch :debug
+      max_named 2
     end
   end
 
@@ -98,7 +99,7 @@ module Homebrew
     extract_args.parse
 
     # Expect exactly two named arguments: formula and tap
-    raise UsageError if args.remaining.length != 2
+    raise UsageError, "This command requires formula and tap arguments" if args.remaining.length != 2
 
     if args.remaining.first !~ HOMEBREW_TAP_FORMULA_REGEX
       name = args.remaining.first.downcase

Library/Homebrew/dev-cmd/install-bundler-gems.rb

@@ -14,6 +14,7 @@ module Homebrew
         Install Homebrew's Bundler gems.
       EOS
       switch :debug
+      max_named 0
     end
   end
 

Library/Homebrew/dev-cmd/man.rb

@@ -28,14 +28,13 @@ module Homebrew
                           "comparison without factoring in the date)."
       switch "--link",
              description: "This is now done automatically by `brew update`."
+      max_named 0
     end
   end
 
   def man
     man_args.parse
 
-    raise UsageError unless ARGV.named.empty?
-
     odie "`brew man --link` is now done automatically by `brew update`." if args.link?
 
     regenerate_man_pages

Library/Homebrew/dev-cmd/mirror.rb

@@ -21,7 +21,7 @@ module Homebrew
   def mirror
     mirror_args.parse
 
-    odie "This command requires at least one formula argument!" if ARGV.named.empty?
+    raise FormulaUnspecifiedError if args.remaining.empty?
 
     bintray_user = ENV["HOMEBREW_BINTRAY_USER"]
     bintray_key = ENV["HOMEBREW_BINTRAY_KEY"]

Library/Homebrew/dev-cmd/pull.rb

@@ -70,7 +70,9 @@ module Homebrew
 
     pull_args.parse
 
-    odie "This command requires at least one argument containing a URL or pull request number" if ARGV.named.empty?
+    if ARGV.named.empty?
+      raise UsageError, "This command requires at least one argument containing a URL or pull request number"
+    end
 
     # Passthrough Git environment variables for e.g. git am
     ENV["GIT_COMMITTER_NAME"] = ENV["HOMEBREW_GIT_NAME"] if ENV["HOMEBREW_GIT_NAME"]
@@ -107,7 +109,7 @@ module Homebrew
         end
         _, testing_job = *testing_match
         url = "https://github.com/Homebrew/homebrew-#{tap.repo}/compare/master...BrewTestBot:testing-#{testing_job}"
-        odie "Testing URLs require `--bottle`!" unless args.bottle?
+        odie "--bottle is required for testing job URLs!" unless args.bottle?
       elsif (api_match = arg.match HOMEBREW_PULL_API_REGEX)
         _, user, repo, issue = *api_match
         url = "https://github.com/#{user}/#{repo}/pull/#{issue}"
@@ -277,7 +279,7 @@ module Homebrew
     elsif patch_changes[:formulae].length > 1
       odie "Can only bump one changed formula; bumped #{patch_changes[:formulae]}"
     elsif !patch_changes[:others].empty?
-      odie "Can not bump if non-formula files are changed"
+      odie "Cannot bump if non-formula files are changed"
     end
   end
 

Library/Homebrew/dev-cmd/release-notes.rb

@@ -16,6 +16,7 @@ module Homebrew
       EOS
       switch "--markdown",
              description: "Print as a Markdown list."
+      max_named 2
     end
   end
 

Library/Homebrew/dev-cmd/tap-new.rb

@@ -15,13 +15,14 @@ module Homebrew
       EOS
       switch :verbose
       switch :debug
+      max_named 1
     end
   end
 
   def tap_new
     tap_new_args.parse
 
-    raise "A tap argument is required" if ARGV.named.empty?
+    raise UsageError, "This command requires a tap argument" if ARGV.named.empty?
 
     tap = Tap.fetch(ARGV.named.first)
     titleized_user = tap.user.dup

Library/Homebrew/dev-cmd/tests.rb

@@ -29,6 +29,7 @@ module Homebrew
              description: "Randomise tests with the specified <value> instead of a random seed."
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 

Library/Homebrew/dev-cmd/update-test.rb

@@ -23,6 +23,7 @@ module Homebrew
              description: "Use the commit at the specified <date> as the start commit."
       switch :verbose
       switch :debug
+      max_named 0
     end
   end
 
@@ -88,7 +89,7 @@ module Homebrew
     chdir "update-test" do
       curdir = Pathname.new(Dir.pwd)
 
-      oh1 "Setup test environment..."
+      oh1 "Preparing test environment..."
       # copy Homebrew installation
       safe_system "git", "clone", "#{HOMEBREW_REPOSITORY}/.git", ".",
                   "--branch", "master", "--single-branch"

Library/Homebrew/dev-cmd/vendor-gems.rb

@@ -14,6 +14,7 @@ module Homebrew
         Install and commit Homebrew's vendored gems.
       EOS
       switch :debug
+      max_named 0
     end
   end
 

docs/Manpage.md

@@ -67,7 +67,7 @@ this for the given formulae and casks.
 * `-n`, `--dry-run`:
   Show what would be removed, but do not actually remove anything.
 * `-s`:
-  Scrub the cache, including downloads for even the latest versions. Note downloads for any installed formula or cask will still not be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
+  Scrub the cache, including downloads for even the latest versions. Note downloads for any installed formulae or casks will still not be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
 * `--prune-prefix`:
   Only prune the symlinks and directories from the prefix and remove no other files.
 
@@ -157,7 +157,7 @@ everything you use Homebrew for is working fine: please don't worry or file an
 issue; just ignore this.
 
 * `--list-checks`:
-  List all audit methods.
+  List all audit methods, which can be run individually if provided as arguments.
 * `-D`, `--audit-debug`:
   Enable debugging and profiling of audit methods.
 
@@ -355,7 +355,7 @@ Show install options specific to *`formula`*.
 * `--all`:
   Show options for all available formulae.
 
-### `outdated` [*`options`*]
+### `outdated` [*`options`*] [*`formula`*]
 
 List installed formulae that have an updated version available. By default,
 version information is displayed in interactive shells, and suppressed
@@ -384,7 +384,7 @@ Rerun the post-install steps for *`formula`*.
 Import all formulae from the specified *`tap`*, or from all installed taps if none
 is provided. This can be useful for debugging issues across all formulae when
 making significant changes to `formula.rb`, testing the performance of loading
-all formulae or to determine if any current formulae have Ruby issues.
+all formulae or checking if any current formulae have Ruby issues.
 
 * `--aliases`:
   Verify any alias symlinks in each tap.
@@ -644,7 +644,7 @@ directory doesn't exist, `$(brew --repository)/Cellar`.
 If *`formula`* is provided, display the location in the cellar where *`formula`*
 would be installed, without any sort of versioned directory as the last path.
 
-### `--env` [*`options`*]
+### `--env` [*`options`*] [*`formula`*]
 
 Summarise Homebrew's build environment as a plain list.
 

manpages/brew-cask.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "November 2019" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "December 2019" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS

manpages/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "November 2019" "Homebrew" "brew"
+.TH "BREW" "1" "December 2019" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for macOS
@@ -63,7 +63,7 @@ Show what would be removed, but do not actually remove anything\.
 .
 .TP
 \fB\-s\fR
-Scrub the cache, including downloads for even the latest versions\. Note downloads for any installed formula or cask will still not be deleted\. If you want to delete those too: \fBrm \-rf "$(brew \-\-cache)"\fR
+Scrub the cache, including downloads for even the latest versions\. Note downloads for any installed formulae or casks will still not be deleted\. If you want to delete those too: \fBrm \-rf "$(brew \-\-cache)"\fR
 .
 .TP
 \fB\-\-prune\-prefix\fR
@@ -176,7 +176,7 @@ Check your system for potential problems\. Will exit with a non\-zero status if
 .
 .TP
 \fB\-\-list\-checks\fR
-List all audit methods\.
+List all audit methods, which can be run individually if provided as arguments\.
 .
 .TP
 \fB\-D\fR, \fB\-\-audit\-debug\fR
@@ -467,7 +467,7 @@ Show options for formulae that are currently installed\.
 \fB\-\-all\fR
 Show options for all available formulae\.
 .
-.SS "\fBoutdated\fR [\fIoptions\fR]"
+.SS "\fBoutdated\fR [\fIoptions\fR] [\fIformula\fR]"
 List installed formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
 .
 .TP
@@ -493,7 +493,7 @@ Pin the specified \fIformula\fR, preventing them from being upgraded when issuin
 Rerun the post\-install steps for \fIformula\fR\.
 .
 .SS "\fBreadall\fR [\fIoptions\fR] [\fItap\fR]"
-Import all formulae from the specified \fItap\fR, or from all installed taps if none is provided\. This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues\.
+Import all formulae from the specified \fItap\fR, or from all installed taps if none is provided\. This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or checking if any current formulae have Ruby issues\.
 .
 .TP
 \fB\-\-aliases\fR
@@ -812,7 +812,7 @@ Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR
 .P
 If \fIformula\fR is provided, display the location in the cellar where \fIformula\fR would be installed, without any sort of versioned directory as the last path\.
 .
-.SS "\fB\-\-env\fR [\fIoptions\fR]"
+.SS "\fB\-\-env\fR [\fIoptions\fR] [\fIformula\fR]"
 Summarise Homebrew\'s build environment as a plain list\.
 .
 .P