Use CLI::Parser for cask commands.

Library/Homebrew/cask/auditor.rb

@@ -9,22 +9,22 @@ module Cask
     def self.audit(cask, audit_download: false, audit_appcast: false,
                    audit_online: false, audit_strict: false,
                    audit_token_conflicts: false, audit_new_cask: false,
-                   quarantine: true, commit_range: nil)
+                   quarantine: true, commit_range: nil, language: nil)
       new(cask, audit_download: audit_download,
                 audit_appcast: audit_appcast,
                 audit_online: audit_online,
                 audit_new_cask: audit_new_cask,
                 audit_strict: audit_strict,
                 audit_token_conflicts: audit_token_conflicts,
-                quarantine: quarantine, commit_range: commit_range).audit
+                quarantine: quarantine, commit_range: commit_range, language: language).audit
     end
 
-    attr_reader :cask, :commit_range
+    attr_reader :cask, :commit_range, :language
 
     def initialize(cask, audit_download: false, audit_appcast: false,
                    audit_online: false, audit_strict: false,
                    audit_token_conflicts: false, audit_new_cask: false,
-                   quarantine: true, commit_range: nil)
+                   quarantine: true, commit_range: nil, language: nil)
       @cask = cask
       @audit_download = audit_download
       @audit_appcast = audit_appcast
@@ -34,6 +34,7 @@ module Cask
       @quarantine = quarantine
       @commit_range = commit_range
       @audit_token_conflicts = audit_token_conflicts
+      @language = language
     end
 
     attr_predicate :audit_appcast?, :audit_download?, :audit_online?,
@@ -43,7 +44,7 @@ module Cask
       warnings = Set.new
       errors = Set.new
 
-      if !Homebrew.args.value("language") && language_blocks
+      if !language && language_blocks
         language_blocks.each_key do |l|
           audit = audit_languages(l)
           puts audit.summary

Library/Homebrew/cask/cmd.rb

@@ -3,12 +3,11 @@
 require "optparse"
 require "shellwords"
 
+require "cli/parser"
 require "extend/optparse"
 
 require "cask/config"
 
-require "cask/cmd/options"
-
 require "cask/cmd/abstract_command"
 require "cask/cmd/--cache"
 require "cask/cmd/audit"
@@ -48,33 +47,87 @@ module Cask
       "dr"       => "doctor",
     }.freeze
 
-    include Options
+    def self.description
+      max_command_len = Cmd.commands.map(&:length).max
 
-    option "--appdir=PATH",               ->(value) { Config.global.appdir               = value }
+      <<~EOS +
-    option "--colorpickerdir=PATH",       ->(value) { Config.global.colorpickerdir       = value }
+        Homebrew Cask provides a friendly CLI workflow for the administration of macOS applications distributed as binaries.
-    option "--prefpanedir=PATH",          ->(value) { Config.global.prefpanedir          = value }
-    option "--qlplugindir=PATH",          ->(value) { Config.global.qlplugindir          = value }
-    option "--mdimporterdir=PATH",        ->(value) { Config.global.mdimporterdir        = value }
-    option "--dictionarydir=PATH",        ->(value) { Config.global.dictionarydir        = value }
-    option "--fontdir=PATH",              ->(value) { Config.global.fontdir              = value }
-    option "--servicedir=PATH",           ->(value) { Config.global.servicedir           = value }
-    option "--input_methoddir=PATH",      ->(value) { Config.global.input_methoddir      = value }
-    option "--internet_plugindir=PATH",   ->(value) { Config.global.internet_plugindir   = value }
-    option "--audio_unit_plugindir=PATH", ->(value) { Config.global.audio_unit_plugindir = value }
-    option "--vst_plugindir=PATH",        ->(value) { Config.global.vst_plugindir        = value }
-    option "--vst3_plugindir=PATH",       ->(value) { Config.global.vst3_plugindir       = value }
-    option "--screen_saverdir=PATH",      ->(value) { Config.global.screen_saverdir      = value }
 
-    option "--help", :help, false
+        Commands:
+      EOS
+        Cmd.command_classes
+           .select(&:visible?)
+           .map do |klass|
+             "  - #{"`#{klass.command_name}`".ljust(max_command_len + 2)}  #{klass.short_description}\n"
+           end
+           .join +
+        "\nSee also: `man brew`"
+    end
 
-    option "--language=a,b,c", ->(value) { Config.global.languages = value }
+    def self.parser(&block)
+      Homebrew::CLI::Parser.new do
+        if block_given?
+          instance_eval(&block)
+        else
+          usage_banner <<~EOS
+            `cask` <command> [<options>] [<cask>]
 
-    # override default handling of --version
+            #{Cmd.description}
-    option "--version", ->(*) { raise OptionParser::InvalidOption }
+          EOS
+        end
+
+        flag "--appdir=",
+             description: "Target location for Applications. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:appdir]}`"
+        flag "--colorpickerdir=",
+             description: "Target location for Color Pickers. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:colorpickerdir]}`"
+        flag "--prefpanedir=",
+             description: "Target location for Preference Panes. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:prefpanedir]}`"
+        flag "--qlplugindir=",
+             description: "Target location for QuickLook Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:qlplugindir]}`"
+        flag "--mdimporterdir=",
+             description: "Target location for Spotlight Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:mdimporterdir]}`"
+        flag "--dictionarydir=",
+             description: "Target location for Dictionaries. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:dictionarydir]}`"
+        flag "--fontdir=",
+             description: "Target location for Fonts. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:fontdir]}`"
+        flag "--servicedir=",
+             description: "Target location for Services. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:servicedir]}`"
+        flag "--input_methoddir=",
+             description: "Target location for Input Methods. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:input_methoddir]}`"
+        flag "--internet_plugindir=",
+             description: "Target location for Internet Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:internet_plugindir]}`"
+        flag "--audio_unit_plugindir=",
+             description: "Target location for Audio Unit Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:audio_unit_plugindir]}`"
+        flag "--vst_plugindir=",
+             description: "Target location for VST Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:vst_plugindir]}`"
+        flag "--vst3_plugindir=",
+             description: "Target location for VST3 Plugins. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:vst3_plugindir]}`"
+        flag "--screen_saverdir=",
+             description: "Target location for Screen Savers. " \
+                          "Default: `#{Config::DEFAULT_DIRS[:screen_saverdir]}`"
+        comma_array "--language",
+                    description: "Set language of the Cask to install. The first matching " \
+                                 "language is used, otherwise the default language on the Cask. " \
+                                 "The default value is the `language of your system`"
+      end
+    end
 
     def self.command_classes
       @command_classes ||= constants.map(&method(:const_get))
-                                    .select { |klass| klass.respond_to?(:run) }
+                                    .select { |klass| klass.is_a?(Class) && klass < AbstractCommand }
                                     .reject(&:abstract?)
                                     .sort_by(&:command_name)
     end
@@ -98,7 +151,7 @@ module Cask
     end
 
     def initialize(*args)
-      @args = process_options(*args)
+      @argv = args
     end
 
     def find_external_command(command)
@@ -143,83 +196,31 @@ module Cask
     end
 
     def run
-      MacOS.full_version = ENV["MACOS_VERSION"] unless ENV["MACOS_VERSION"].nil?
+      argv = @argv
+
+      args = self.class.parser.parse(argv, ignore_invalid_options: true)
+
+      Config::DEFAULT_DIRS.each_key do |name|
+        Config.global.public_send(:"#{name}=", args[name]) if args[name]
+      end
+
+      Config.global.languages = args.language if args.language
+
       Tap.default_cask_tap.install unless Tap.default_cask_tap.installed?
 
-      args = @args.dup
+      command, argv = detect_internal_command(*argv) ||
-      command, args = detect_internal_command(*args) || detect_external_command(*args) || [NullCommand.new, args]
+                      detect_external_command(*argv) ||
+                      [args.remaining.empty? ? NullCommand : UnknownSubcommand.new(args.remaining.first), argv]
 
-      if help?
+      if args.help?
-        Help.new(command.command_name).run
+        puts command.help
       else
-        command.run(*args)
+        command.run(*argv)
       end
-    rescue CaskError, MethodDeprecatedError, ArgumentError, OptionParser::InvalidOption => e
+    rescue CaskError, MethodDeprecatedError, ArgumentError => e
       onoe e.message
-      $stderr.puts e.backtrace if debug?
+      $stderr.puts e.backtrace if args.debug?
       exit 1
-    rescue StandardError, ScriptError, NoMemoryError => e
-      onoe e.message
-      $stderr.puts Utils.error_message_with_suggestions
-      $stderr.puts e.backtrace
-      exit 1
-    end
-
-    def self.nice_listing(cask_list)
-      cask_taps = {}
-      cask_list.each do |c|
-        user, repo, token = c.split "/"
-        repo.sub!(/^homebrew-/i, "")
-        cask_taps[token] ||= []
-        cask_taps[token].push "#{user}/#{repo}"
-      end
-      list = []
-      cask_taps.each do |token, taps|
-        if taps.length == 1
-          list.push token
-        else
-          taps.each { |r| list.push [r, token].join "/" }
-        end
-      end
-      list.sort
-    end
-
-    def process_options(*args)
-      non_options = []
-
-      if idx = args.index("--")
-        non_options += args.drop(idx)
-        args = args.first(idx)
-      end
-
-      exclude_regex = /^--#{Regexp.union(*Config::DEFAULT_DIRS.keys.map(&Regexp.public_method(:escape)))}=/
-      cask_opts = Shellwords.shellsplit(ENV.fetch("HOMEBREW_CASK_OPTS", ""))
-                            .reject { |arg| arg.match?(exclude_regex) }
-
-      all_args = cask_opts + args
-
-      i = 0
-      remaining = []
-
-      while i < all_args.count
-        begin
-          arg = all_args[i]
-
-          remaining << arg unless process_arguments([arg]).empty?
-        rescue OptionParser::MissingArgument
-          raise if i + 1 >= all_args.count
-
-          args = all_args[i..(i + 1)]
-          process_arguments(args)
-          i += 1
-        rescue OptionParser::InvalidOption
-          remaining << arg
-        end
-
-        i += 1
-      end
-
-      remaining + non_options
     end
 
     class ExternalRubyCommand
@@ -246,26 +247,33 @@ module Cask
         @path = path
       end
 
-      def run(*)
+      def run(*argv)
-        exec @path, *ARGV[1..]
+        exec @path, *argv
       end
     end
 
-    class NullCommand
+    class UnknownSubcommand
-      def run(*args)
+      def initialize(command_name)
-        if args.empty?
+        @command_name = command_name
-          ofail "No subcommand given.\n"
+      end
-        else
-          ofail "Unknown subcommand: #{args.first}"
-        end
 
-        $stderr.puts
+      def run(*)
-        $stderr.puts Help.usage
+        raise UsageError, "Subcommand `#{@command_name}` does not exist."
       end
 
       def help
         run
       end
     end
+
+    class NullCommand
+      def self.run(*)
+        raise UsageError, "No subcommand given."
+      end
+
+      def self.help
+        Cmd.parser.generate_help_text
+      end
+    end
   end
 end

Library/Homebrew/cask/cmd/--cache.rb

@@ -5,13 +5,16 @@ require "cask/download"
 module Cask
   class Cmd
     class Cache < AbstractCommand
-      def self.command_name
+      def self.min_named
-        "--cache"
+        :cask
       end
 
-      def initialize(*)
+      def self.description
-        super
+        "Display the file used to cache a <cask>."
-        raise CaskUnspecifiedError if args.empty?
+      end
+
+      def self.command_name
+        "--cache"
       end
 
       def run
@@ -23,10 +26,6 @@ module Cask
       def self.cached_location(cask)
         Download.new(cask).downloader.cached_location
       end
-
-      def self.help
-        "display the file used to cache the Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/abstract_command.rb

@@ -1,20 +1,66 @@
 # frozen_string_literal: true
 
-require_relative "options"
 require "search"
 
 module Cask
   class Cmd
     class AbstractCommand
-      include Options
       include Homebrew::Search
 
-      option "--[no-]binaries",   :binaries,      true
+      def self.min_named
-      option "--debug",           :debug,         false
+        nil
-      option "--verbose",         :verbose,       false
+      end
-      option "--outdated",        :outdated_only, false
+
-      option "--require-sha",     :require_sha,   false
+      def self.max_named
-      option "--[no-]quarantine", :quarantine,    true
+        nil
+      end
+
+      def self.banner_args
+        if min_named == :cask && max_named != 1
+          " <cask>"
+        elsif max_named&.zero?
+          ""
+        else
+          " [<cask>]"
+        end
+      end
+
+      def self.banner_headline
+        "`#{command_name}` [<options>]#{banner_args}"
+      end
+
+      def self.parser(&block)
+        banner = <<~EOS
+          `cask` #{banner_headline}
+
+          #{description}
+        EOS
+
+        min_n = min_named
+        max_n = max_named
+
+        Cmd.parser do
+          usage_banner banner
+
+          instance_eval(&block) if block_given?
+
+          switch "--[no-]binaries",
+                 description: "Disable/enable linking of helper executables to `#{Config.global.binarydir}`. " \
+                              "Default: enabled",
+                 env:         :cask_opts_binaries
+
+          switch "--require-sha",
+                 description: "Require all casks to have a checksum.",
+                 env:         :cask_opts_require_sha
+
+          switch "--[no-]quarantine",
+                 description: "Disable/enable quarantining of downloads. Default: enabled",
+                 env:         :cask_opts_quarantine
+
+          min_named min_n unless min_n.nil?
+          max_named max_n unless max_n.nil?
+        end
+      end
 
       def self.command_name
         @command_name ||= name.sub(/^.*:/, "").gsub(/(.)([A-Z])/, '\1_\2').downcase
@@ -29,19 +75,21 @@ module Cask
       end
 
       def self.help
-        nil
+        parser.generate_help_text
+      end
+
+      def self.short_description
+        description.split(".").first
       end
 
       def self.run(*args)
         new(*args).run
       end
 
-      attr_accessor :args
+      attr_reader :args
-
-      private :args=
 
       def initialize(*args)
-        @args = process_arguments(*args)
+        @args = self.class.parser.parse(args)
       end
 
       private
@@ -49,7 +97,7 @@ module Cask
       def casks(alternative: -> { [] })
         return @casks if defined?(@casks)
 
-        casks = args.empty? ? alternative.call : args
+        casks = args.named.empty? ? alternative.call : args.named
         @casks = casks.map { |cask| CaskLoader.load(cask) }
       rescue CaskUnavailableError => e
         reason = [e.reason, *suggestion_message(e.token)].join(" ")

Library/Homebrew/cask/cmd/audit.rb

@@ -6,56 +6,56 @@ require "cask/auditor"
 module Cask
   class Cmd
     class Audit < AbstractCommand
-      option "--download",        :download_arg,        false
+      def self.description
-      option "--appcast",         :appcast_arg,         false
-      option "--token-conflicts", :token_conflicts_arg, false
-      option "--strict",          :strict_arg,          false
-      option "--online",          :online_arg,          false
-      option "--new-cask",        :new_cask_arg,        false
-
-      def self.usage
         <<~EOS
-          `cask audit` [<options>] [<cask>]
-
-          --strict          - Run additional, stricter style checks.
-          --online          - Run additional, slower style checks that require a network connection.
-          --new-cask        - Run various additional style checks to determine if a new cask is eligible
-                              for Homebrew. This should be used when creating new casks and implies
-                              `--strict` and `--online`.
-          --download        - Audit the downloaded file
-          --appcast         - Audit the appcast
-          --token-conflicts - Audit for token conflicts
-
           Check <cask> for Homebrew coding style violations. This should be run before
-          submitting a new cask. If no <casks> are provided, check all locally
+          submitting a new cask. If no <cask> is provided, checks all locally
           available casks. Will exit with a non-zero status if any errors are
           found, which can be useful for implementing pre-commit hooks.
         EOS
       end
 
-      def self.help
+      def self.parser
-        "verifies installability of Casks"
+        super do
+          switch "--download",
+                 description: "Audit the downloaded file"
+          switch "--appcast",
+                 description: "Audit the appcast"
+          switch "--token-conflicts",
+                 description: "Audit for token conflicts"
+          switch "--strict",
+                 description: "Run additional, stricter style checks"
+          switch "--online",
+                 description: "Run additional, slower style checks that require a network connection"
+          switch "--new-cask",
+                 description: "Run various additional style checks to determine if a new cask is eligible
+                               for Homebrew. This should be used when creating new casks and implies
+                               `--strict` and `--online`"
+        end
       end
 
       def run
         Homebrew.auditing = true
-        strict = new_cask_arg? || strict_arg?
+        strict = args.new_cask? || args.strict?
-        token_conflicts = strict || token_conflicts_arg?
+        online = args.new_cask? || args.online?
 
-        online = new_cask_arg? || online_arg?
+        options = {
-        download = online || download_arg?
+          audit_download:        online || args.download?,
-        appcast = online || appcast_arg?
+          audit_appcast:         online || args.appcast?,
+          audit_online:          online,
+          audit_strict:          strict,
+          audit_new_cask:        args.new_cask?,
+          audit_token_conflicts: strict || args.token_conflicts?,
+          quarantine:            args.quarantine?,
+          language:              args.language,
+        }.compact
+
+        options[:quarantine] = true if options[:quarantine].nil?
 
         failed_casks = casks(alternative: -> { Cask.to_a })
                        .reject do |cask|
           odebug "Auditing Cask #{cask}"
-          result = Auditor.audit(cask, audit_download:        download,
+          result = Auditor.audit(cask, **options)
-                                       audit_appcast:         appcast,
-                                       audit_online:          online,
-                                       audit_strict:          strict,
-                                       audit_new_cask:        new_cask_arg?,
-                                       audit_token_conflicts: token_conflicts,
-                                       quarantine:            quarantine?)
 
           result[:warnings].empty? && result[:errors].empty?
         end

Library/Homebrew/cask/cmd/cat.rb

@@ -3,9 +3,12 @@
 module Cask
   class Cmd
     class Cat < AbstractCommand
-      def initialize(*)
+      def self.min_named
-        super
+        :cask
-        raise CaskUnspecifiedError if args.empty?
+      end
+
+      def self.description
+        "Dump raw source of a <cask> to the standard output."
       end
 
       def run
@@ -18,10 +21,6 @@ module Cask
           end
         end
       end
-
-      def self.help
-        "dump raw source of the given Cask to the standard output"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/create.rb

@@ -3,14 +3,26 @@
 module Cask
   class Cmd
     class Create < AbstractCommand
+      def self.min_named
+        :cask
+      end
+
+      def self.max_named
+        1
+      end
+
+      def self.description
+        "Creates the given <cask> and opens it in an editor."
+      end
+
       def initialize(*)
         super
-        raise CaskUnspecifiedError if args.empty?
+      rescue Homebrew::CLI::MaxNamedArgumentsError
-        raise ArgumentError, "Only one Cask can be created at a time." if args.count > 1
+        raise UsageError, "Only one cask can be created at a time."
       end
 
       def run
-        cask_token = args.first
+        cask_token = args.named.first
         cask_path = CaskLoader.path(cask_token)
         raise CaskAlreadyCreatedError, cask_token if cask_path.exist?
 
@@ -37,10 +49,6 @@ module Cask
           end
         RUBY
       end
-
-      def self.help
-        "creates the given Cask and opens it in an editor"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/doctor.rb

@@ -6,15 +6,12 @@ require "diagnostic"
 module Cask
   class Cmd
     class Doctor < AbstractCommand
-      def initialize(*)
+      def self.max_named
-        super
+        0
-        return if args.empty?
-
-        raise ArgumentError, "#{self.class.command_name} does not take arguments."
       end
 
-      def summary_header
+      def self.description
-        "Cask's Doctor Checkup"
+        "Checks for configuration issues."
       end
 
       def run
@@ -32,10 +29,6 @@ module Cask
 
         raise CaskError, "There are some problems with your setup." unless success
       end
-
-      def self.help
-        "checks for configuration issues"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/edit.rb

@@ -3,10 +3,22 @@
 module Cask
   class Cmd
     class Edit < AbstractCommand
+      def self.min_named
+        :cask
+      end
+
+      def self.max_named
+        1
+      end
+
+      def self.description
+        "Open the given <cask> for editing."
+      end
+
       def initialize(*)
         super
-        raise CaskUnspecifiedError if args.empty?
+      rescue Homebrew::CLI::MaxNamedArgumentsError
-        raise ArgumentError, "Only one Cask can be edited at a time." if args.count > 1
+        raise UsageError, "Only one cask can be edited at a time."
       end
 
       def run
@@ -25,10 +37,6 @@ module Cask
 
         raise
       end
-
-      def self.help
-        "edits the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/fetch.rb

@@ -5,26 +5,37 @@ require "cask/download"
 module Cask
   class Cmd
     class Fetch < AbstractCommand
-      option "--force", :force, false
+      def self.min_named
+        :cask
+      end
 
-      def initialize(*)
+      def self.parser
-        super
+        super do
-        raise CaskUnspecifiedError if args.empty?
+          switch "--force",
+                 description: "Force redownloading even if files already exist in local cache."
+        end
+      end
+
+      def self.description
+        "Downloads remote application files to local cache."
       end
 
       def run
+        options = {
+          force:      args.force?,
+          quarantine: args.quarantine?,
+        }.compact
+
+        options[:quarantine] = true if options[:quarantine].nil?
+
         casks.each do |cask|
           puts Installer.caveats(cask)
           ohai "Downloading external files for Cask #{cask}"
-          downloaded_path = Download.new(cask, force: force?, quarantine: quarantine?).perform
+          downloaded_path = Download.new(cask, **options).perform
           Verify.all(cask, downloaded_path)
           ohai "Success! Downloaded to -> #{downloaded_path}"
         end
       end
-
-      def self.help
-        "downloads remote application files to local cache"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/help.rb

@@ -3,53 +3,31 @@
 module Cask
   class Cmd
     class Help < AbstractCommand
+      def self.max_named
+        1
+      end
+
+      def self.description
+        "Print help for `cask` commands."
+      end
+
       def run
-        if args.empty?
+        if args.named.empty?
-          puts self.class.purpose
+          puts Cmd.parser.generate_help_text
-          puts
+        else
-          puts self.class.usage
+          command_name = args.named.first
-        elsif args.count == 1
-          command_name = args.first
 
           unless command = self.class.commands[command_name]
             raise "No help information found for command '#{command_name}'."
           end
 
-          if command.respond_to?(:usage)
+          puts command.help
-            puts command.usage
-          else
-            puts command.help
-          end
-        else
-          raise ArgumentError, "#{self.class.command_name} only takes up to one argument."
         end
       end
 
-      def self.purpose
-        <<~EOS
-          Homebrew Cask provides a friendly CLI workflow for the administration
-          of macOS applications distributed as binaries.
-        EOS
-      end
-
       def self.commands
         Cmd.command_classes.select(&:visible?).map { |klass| [klass.command_name, klass] }.to_h
       end
-
-      def self.usage
-        max_command_len = Cmd.commands.map(&:length).max
-
-        "Commands:\n" +
-          Cmd.command_classes
-             .select(&:visible?)
-             .map { |klass| "    #{klass.command_name.ljust(max_command_len)}  #{klass.help}\n" }
-             .join +
-          %Q(\nSee also "man brew-cask")
-      end
-
-      def self.help
-        "print help strings for commands"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/home.rb

@@ -3,6 +3,10 @@
 module Cask
   class Cmd
     class Home < AbstractCommand
+      def self.description
+        "Opens the homepage of the given <cask>. If no cask is given, opens the Homebrew homepage."
+      end
+
       def run
         if casks.none?
           odebug "Opening project homepage"
@@ -18,10 +22,6 @@ module Cask
       def self.open_url(url)
         SystemCommand.run!(OS::PATH_OPEN, args: ["--", url])
       end
-
-      def self.help
-        "opens the homepage of the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/info.rb

@@ -6,15 +6,23 @@ require "cask/installer"
 module Cask
   class Cmd
     class Info < AbstractCommand
-      option "--json=VERSION", :json
+      def self.min_named
+        :cask
+      end
 
-      def initialize(*)
+      def self.description
-        super
+        "Displays information about the given <cask>."
-        raise CaskUnspecifiedError if args.empty?
+      end
+
+      def self.parser
+        super do
+          flag "--json=",
+               description: "Output information in JSON format."
+        end
       end
 
       def run
-        if json == "v1"
+        if args.json == "v1"
           puts JSON.generate(casks.map(&:to_h))
         else
           casks.each_with_index do |cask, i|
@@ -25,10 +33,6 @@ module Cask
         end
       end
 
-      def self.help
-        "displays information about the given Cask"
-      end
-
       def self.get_info(cask)
         output = title_info(cask) + "\n"
         output << Formatter.url(cask.homepage) + "\n" if cask.homepage

Library/Homebrew/cask/cmd/install.rb

@@ -3,31 +3,44 @@
 module Cask
   class Cmd
     class Install < AbstractCommand
-      option "--force",          :force,          false
+      def self.min_named
-      option "--skip-cask-deps", :skip_cask_deps, false
+        :cask
+      end
 
-      def initialize(*)
+      def self.description
-        super
+        "Installs the given <cask>."
-        raise CaskUnspecifiedError if args.empty?
+      end
+
+      def self.parser(&block)
+        super do
+          switch "--force",
+                 description: "Force overwriting existing files."
+          switch "--skip-cask-deps",
+                 description: "Skip installing cask dependencies."
+
+          instance_eval(&block) if block_given?
+        end
       end
 
       def run
+        options = {
+          binaries:       args.binaries?,
+          verbose:        args.verbose?,
+          force:          args.force?,
+          skip_cask_deps: args.skip_cask_deps?,
+          require_sha:    args.require_sha?,
+          quarantine:     args.quarantine?,
+        }.compact
+
+        options[:quarantine] = true if options[:quarantine].nil?
+
         odie "Installing casks is supported only on macOS" unless OS.mac?
         casks.each do |cask|
-          Installer.new(cask, binaries:       binaries?,
+          Installer.new(cask, **options).install
-                              verbose:        verbose?,
-                              force:          force?,
-                              skip_cask_deps: skip_cask_deps?,
-                              require_sha:    require_sha?,
-                              quarantine:     quarantine?).install
         rescue CaskAlreadyInstalledError => e
           opoo e.message
         end
       end
-
-      def self.help
-        "installs the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/internal_help.rb

@@ -3,11 +3,12 @@
 module Cask
   class Cmd
     class InternalHelp < AbstractInternalCommand
-      def initialize(*)
+      def self.max_named
-        super
+        0
-        return if args.empty?
+      end
 
-        raise ArgumentError, "#{self.class.command_name} does not take arguments."
+      def self.description
+        "Print help for unstable internal-use commands."
       end
 
       def run
@@ -20,10 +21,6 @@ module Cask
         end
         puts "\n"
       end
-
-      def self.help
-        "print help strings for unstable internal-use commands"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/internal_stanza.rb

@@ -13,24 +13,45 @@ module Cask
       #
       # On failure, a blank line is returned on the standard output.
       #
-      # Examples
-      #
-      #     brew cask _stanza appcast   --table
-      #     brew cask _stanza app       --table           alfred google-chrome adium vagrant
-      #     brew cask _stanza url       --table           alfred google-chrome adium vagrant
-      #     brew cask _stanza version   --table           alfred google-chrome adium vagrant
-      #     brew cask _stanza artifacts --table           alfred google-chrome adium vagrant
-      #     brew cask _stanza artifacts --table --yaml    alfred google-chrome adium vagrant
-      #
 
       ARTIFACTS =
         (DSL::ORDINARY_ARTIFACT_CLASSES.map(&:dsl_key) +
          DSL::ARTIFACT_BLOCK_CLASSES.map(&:dsl_key)).freeze
 
-      option "--table",   :table,   false
+      def self.min_named
-      option "--quiet",   :quiet,   false
+        1
-      option "--yaml",    :yaml,    false
+      end
-      option "--inspect", :inspect, false
+
+      def self.banner_args
+        " <stanza_name> [<cask>]"
+      end
+
+      def self.description
+        <<~EOS
+          Extract and render a specific stanza for the given <cask>.
+
+          Examples:
+            `brew cask _stanza appcast   --table`
+            `brew cask _stanza app       --table           alfred google-chrome vagrant`
+            `brew cask _stanza url       --table           alfred google-chrome vagrant`
+            `brew cask _stanza version   --table           alfred google-chrome vagrant`
+            `brew cask _stanza artifacts --table           alfred google-chrome vagrant`
+            `brew cask _stanza artifacts --table --yaml    alfred google-chrome vagrant`
+        EOS
+      end
+
+      def self.parser
+        super do
+          switch "--table",
+                 description: "Print stanza in table format."
+          switch "--quiet",
+                 description: ""
+          switch "--yaml",
+                 description: ""
+          switch "--inspect",
+                 description: ""
+        end
+      end
 
       attr_accessor :format, :stanza
       private :format, :format=
@@ -38,19 +59,19 @@ module Cask
 
       def initialize(*)
         super
-        raise ArgumentError, "No stanza given." if args.empty?
 
-        @stanza = args.shift.to_sym
+        named = args.named.dup
+        @stanza = named.shift.to_sym
+        args.freeze_named_args!(named)
 
-        @format = :to_yaml if yaml?
+        @format = :to_yaml if args.yaml?
 
         return if DSL::DSL_METHODS.include?(stanza)
 
-        raise ArgumentError,
+        raise UsageError, <<~EOS
-              <<~EOS
+          Unknown/unsupported stanza: '#{stanza}'
-                Unknown/unsupported stanza: '#{stanza}'
+          Check cask reference for supported stanzas.
-                Check Cask reference for supported stanzas.
+        EOS
-              EOS
       end
 
       def run
@@ -60,12 +81,12 @@ module Cask
         end
 
         casks(alternative: -> { Cask.to_a }).each do |cask|
-          print "#{cask}\t" if table?
+          print "#{cask}\t" if args.table?
 
           begin
             value = cask.send(stanza)
           rescue
-            opoo "failure calling '#{stanza}' on Cask '#{cask}'" unless quiet?
+            opoo "failure calling '#{stanza}' on Cask '#{cask}'" unless args.quiet?
             puts ""
             next
           end
@@ -89,10 +110,6 @@ module Cask
           end
         end
       end
-
-      def self.help
-        "extract and render a specific stanza for the given Casks"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/list.rb

@@ -3,40 +3,30 @@
 module Cask
   class Cmd
     class List < AbstractCommand
-      option "-1",             :one, false
+      def self.description
-      option "--versions",     :versions, false
+        "Lists installed casks or the casks provided in the arguments."
-      option "--full-name",    :full_name, false
-      option "--json",         :json, false
-
-      def self.usage
-        <<~EOS
-          `cask list`, `cask ls` [<options>] [<casks>]
-
-          -1          - Force output to be one entry per line.
-                        This is the default when output is not to a terminal.
-          --versions  - Show the version number for installed formulae, or only the specified
-                        casks if <casks> are provided.
-          --full-name - Print casks with fully-qualified names.
-          --json      - Print a JSON representation of <cask>. See the docs for examples of using the JSON
-                        output: <https://docs.brew.sh/Querying-Brew>
-
-          List all installed casks.
-
-          If <casks> are provided, limit information to just those casks.
-        EOS
       end
 
-      def self.help
+      def self.parser
-        "lists installed Casks or the casks provided in the arguments"
+        super do
+          switch "-1",
+                 description: "Force output to be one entry per line."
+          switch "--versions",
+                 description: "Show the version number the listed casks."
+          switch "--full-name",
+                 description: "Print casks with fully-qualified names."
+          switch "--json",
+                 description: "Print a JSON representation of the listed casks. "
+        end
       end
 
       def run
         self.class.list_casks(
           *casks,
-          json:      json?,
+          json:      args.json?,
-          one:       one?,
+          one:       args.public_send(:'1?'),
-          full_name: full_name?,
+          full_name: args.full_name?,
-          versions:  versions?,
+          versions:  args.versions?,
         )
       end
 

Library/Homebrew/cask/cmd/options.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Cask
-  class Cmd
-    module Options
-      def self.included(klass)
-        klass.extend(ClassMethods)
-      end
-
-      module ClassMethods
-        def options
-          @options ||= {}
-          return @options unless superclass.respond_to?(:options)
-
-          superclass.options.merge(@options)
-        end
-
-        def option(name, method, default_value = nil)
-          @options ||= {}
-          @options[name] = method
-
-          return if method.respond_to?(:call)
-
-          define_method(:"#{method}=") do |value|
-            instance_variable_set(:"@#{method}", value)
-          end
-
-          if [true, false].include?(default_value)
-            define_method(:"#{method}?") do
-              return default_value unless instance_variable_defined?(:"@#{method}")
-
-              instance_variable_get(:"@#{method}") == true
-            end
-          else
-            define_method(:"#{method}") do
-              return default_value unless instance_variable_defined?(:"@#{method}")
-
-              instance_variable_get(:"@#{method}")
-            end
-          end
-        end
-      end
-
-      def process_arguments(*arguments)
-        parser = OptionParser.new do |opts|
-          next if self.class.options.nil?
-
-          self.class.options.each do |option_name, option_method|
-            option_type = case option_name.split(/(\ |=)/).last
-            when "PATH"
-              Pathname
-            when /\w+(,\w+)+/
-              Array
-            end
-
-            opts.on(option_name, *option_type) do |value|
-              if option_method.respond_to?(:call)
-                option_method.call(value)
-              else
-                send(:"#{option_method}=", value)
-              end
-            end
-          end
-        end
-        parser.parse(*arguments)
-      end
-    end
-  end
-end

Library/Homebrew/cask/cmd/outdated.rb

@@ -3,27 +3,29 @@
 module Cask
   class Cmd
     class Outdated < AbstractCommand
-      option "--greedy", :greedy, false
+      def self.description
-      option "--quiet",  :quiet, false
+        "List the outdated installed casks."
-      option "--json",   :json, false
+      end
 
-      def initialize(*)
+      def self.parser
-        super
+        super do
-        self.verbose = ($stdout.tty? || verbose?) && !quiet?
+          switch "--greedy",
-        @outdated_casks = casks(alternative: -> { Caskroom.casks }).select do |cask|
+                 description: "Also include casks which specify `auto_updates true` or `version :latest`."
-          odebug "Checking update info of Cask #{cask}"
+          switch "--json",
-          cask.outdated?(greedy?)
+                 description: "Print a JSON representation of outdated casks."
         end
       end
 
       def run
-        output = @outdated_casks.map { |cask| cask.outdated_info(greedy?, verbose?, json?) }
+        outdated_casks = casks(alternative: -> { Caskroom.casks }).select do |cask|
+          odebug "Checking update info of Cask #{cask}"
+          cask.outdated?(args.greedy?)
+        end
 
-        puts json? ? JSON.generate(output) : output
+        verbose = ($stdout.tty? || args.verbose?) && !args.quiet?
-      end
+        output = outdated_casks.map { |cask| cask.outdated_info(args.greedy?, verbose, args.json?) }
 
-      def self.help
+        puts args.json? ? JSON.generate(output) : output
-        "list the outdated installed Casks"
       end
     end
   end

Library/Homebrew/cask/cmd/reinstall.rb

@@ -3,15 +3,19 @@
 module Cask
   class Cmd
     class Reinstall < Install
+      def self.description
+        "Reinstalls the given <cask>."
+      end
+
       def run
         self.class.reinstall_casks(
           *casks,
-          binaries:       binaries?,
+          binaries:       args.binaries?,
-          verbose:        verbose?,
+          verbose:        args.verbose?,
-          force:          force?,
+          force:          args.force?,
-          skip_cask_deps: skip_cask_deps?,
+          skip_cask_deps: args.skip_cask_deps?,
-          require_sha:    require_sha?,
+          require_sha:    args.require_sha?,
-          quarantine:     quarantine?,
+          quarantine:     args.quarantine?,
         )
       end
 
@@ -24,25 +28,22 @@ module Cask
         require_sha: nil,
         quarantine: nil
       )
-        # TODO: Handle this in `CLI::Parser`.
+
-        binaries = Homebrew::EnvConfig.cask_opts_binaries? if binaries.nil?
+        options = {
-        quarantine = Homebrew::EnvConfig.cask_opts_quarantine? if quarantine.nil?
+          binaries:       binaries,
-        require_sha = Homebrew::EnvConfig.cask_opts_require_sha? if require_sha.nil?
+          verbose:        verbose,
+          force:          force,
+          skip_cask_deps: skip_cask_deps,
+          require_sha:    require_sha,
+          quarantine:     quarantine,
+        }.compact
+
+        options[:quarantine] = true if options[:quarantine].nil?
 
         casks.each do |cask|
-          Installer.new(cask,
+          Installer.new(cask, **options).reinstall
-                        binaries:       binaries,
-                        verbose:        verbose,
-                        force:          force,
-                        skip_cask_deps: skip_cask_deps,
-                        require_sha:    require_sha,
-                        quarantine:     quarantine).reinstall
         end
       end
-
-      def self.help
-        "reinstalls the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/style.rb

@@ -5,8 +5,15 @@ require "json"
 module Cask
   class Cmd
     class Style < AbstractCommand
-      def self.help
+      def self.description
-        "checks Cask style using RuboCop"
+        "Checks style of the given <cask> using RuboCop."
+      end
+
+      def self.parser
+        super do
+          switch "--fix",
+                 description: "Fix style violations automatically using RuboCop's auto-correct feature."
+        end
       end
 
       def self.rubocop(*paths, auto_correct: false, debug: false, json: false)
@@ -48,18 +55,16 @@ module Cask
         result
       end
 
-      option "--fix", :fix, false
-
       def run
-        result = self.class.rubocop(*cask_paths, auto_correct: fix?, debug: debug?)
+        result = self.class.rubocop(*cask_paths, auto_correct: args.fix?, debug: args.debug?)
         raise CaskError, "Style check failed." unless result.status.success?
       end
 
       def cask_paths
-        @cask_paths ||= if args.empty?
+        @cask_paths ||= if args.named.empty?
           Tap.map(&:cask_dir).select(&:directory?).concat(test_cask_paths)
-        elsif args.any? { |file| File.exist?(file) }
+        elsif args.named.any? { |file| File.exist?(file) }
-          args.map { |path| Pathname(path).expand_path }
+          args.named.map { |path| Pathname(path).expand_path }
         else
           casks.map(&:sourcefile_path)
         end

Library/Homebrew/cask/cmd/uninstall.rb

@@ -3,24 +3,37 @@
 module Cask
   class Cmd
     class Uninstall < AbstractCommand
-      option "--force", :force, false
+      def self.min_named
+        :cask
+      end
 
-      def initialize(*)
+      def self.description
-        super
+        "Uninstalls the given <cask>."
-        raise CaskUnspecifiedError if args.empty?
+      end
+
+      def self.parser
+        super do
+          switch "--force",
+                 description: "Uninstall even if the <cask> is not installed, overwrite " \
+                              "existing files and ignore errors when removing files."
+        end
       end
 
       def run
         self.class.uninstall_casks(
           *casks,
-          binaries: binaries?,
+          binaries: args.binaries?,
-          verbose:  verbose?,
+          verbose:  args.verbose?,
-          force:    force?,
+          force:    args.force?,
         )
       end
 
-      def self.uninstall_casks(*casks, verbose: false, force: false, binaries: nil)
+      def self.uninstall_casks(*casks, binaries: nil, force: false, verbose: false)
-        binaries = Homebrew::EnvConfig.cask_opts_binaries? if binaries.nil?
+        options = {
+          binaries: binaries,
+          force:    force,
+          verbose:  verbose,
+        }.compact
 
         casks.each do |cask|
           odebug "Uninstalling Cask #{cask}"
@@ -32,7 +45,7 @@ module Cask
             cask = CaskLoader.load(cask.installed_caskfile) if cask.installed_caskfile.exist?
           end
 
-          Installer.new(cask, binaries: binaries, verbose: verbose, force: force).uninstall
+          Installer.new(cask, **options).uninstall
 
           next if (versions = cask.versions).empty?
 
@@ -42,10 +55,6 @@ module Cask
           EOS
         end
       end
-
-      def self.help
-        "uninstalls the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/upgrade.rb

@@ -6,28 +6,35 @@ require "cask/config"
 module Cask
   class Cmd
     class Upgrade < AbstractCommand
-      option "--greedy", :greedy, false
+      def self.description
-      option "--quiet",  :quiet, false
+        "Upgrades all outdated casks or the specified casks."
-      option "--force", :force, false
+      end
-      option "--skip-cask-deps", :skip_cask_deps, false
-      option "--dry-run", :dry_run, false
 
-      def initialize(*)
+      def self.parser
-        super
+        super do
-        self.verbose = ($stdout.tty? || verbose?) && !quiet?
+          switch "--force",
+                 description: "Force overwriting existing files."
+          switch "--skip-cask-deps",
+                 description: "Skip installing cask dependencies."
+          switch "--greedy",
+                 description: "Also include casks which specify `auto_updates true` or `version :latest`."
+          switch "--dry-run",
+                 description: "Show what would be upgraded, but do not actually upgrade anything."
+        end
       end
 
       def run
+        verbose = ($stdout.tty? || args.verbose?) && !args.quiet?
         self.class.upgrade_casks(
           *casks,
-          force:          force?,
+          force:          args.force?,
-          greedy:         greedy?,
+          greedy:         args.greedy?,
-          dry_run:        dry_run?,
+          dry_run:        args.dry_run?,
-          binaries:       binaries?,
+          binaries:       args.binaries?,
-          quarantine:     quarantine?,
+          quarantine:     args.quarantine?,
-          require_sha:    require_sha?,
+          require_sha:    args.require_sha?,
-          skip_cask_deps: skip_cask_deps?,
+          skip_cask_deps: args.skip_cask_deps?,
-          verbose:        verbose?,
+          verbose:        verbose,
         )
       end
 
@@ -42,10 +49,8 @@ module Cask
         quarantine: nil,
         require_sha: nil
       )
-        # TODO: Handle this in `CLI::Parser`.
+
-        binaries = Homebrew::EnvConfig.cask_opts_binaries? if binaries.nil?
+        quarantine = true if quarantine.nil?
-        quarantine = Homebrew::EnvConfig.cask_opts_quarantine? if quarantine.nil?
-        require_sha = Homebrew::EnvConfig.cask_opts_require_sha? if require_sha.nil?
 
         outdated_casks = if casks.empty?
           Caskroom.casks.select do |cask|
@@ -98,22 +103,30 @@ module Cask
         odebug "Started upgrade process for Cask #{old_cask}"
         old_config = old_cask.config
 
+        old_options = {
+          binaries: binaries,
+          verbose:  verbose,
+          force:    force,
+          upgrade:  true,
+        }.compact
+
         old_cask_installer =
-          Installer.new(old_cask, binaries: binaries,
+          Installer.new(old_cask, **old_options)
-                                  verbose:  verbose,
-                                  force:    force,
-                                  upgrade:  true)
 
         new_cask.config = Config.global.merge(old_config)
 
+        new_options = {
+          binaries:       binaries,
+          verbose:        verbose,
+          force:          force,
+          skip_cask_deps: skip_cask_deps,
+          require_sha:    require_sha,
+          upgrade:        true,
+          quarantine:     quarantine,
+        }.compact
+
         new_cask_installer =
-          Installer.new(new_cask, binaries:       binaries,
+          Installer.new(new_cask, **new_options)
-                                  verbose:        verbose,
-                                  force:          force,
-                                  skip_cask_deps: skip_cask_deps,
-                                  require_sha:    require_sha,
-                                  upgrade:        true,
-                                  quarantine:     quarantine)
 
         started_upgrade = false
         new_artifacts_installed = false
@@ -148,10 +161,6 @@ module Cask
           raise e
         end
       end
-
-      def self.help
-        "upgrades all outdated casks"
-      end
     end
   end
 end

Library/Homebrew/cask/cmd/zap.rb

@@ -3,26 +3,34 @@
 module Cask
   class Cmd
     class Zap < AbstractCommand
-      option "--force", :force, false
+      def self.min_named
+        :cask
+      end
 
-      def initialize(*)
+      def self.description
-        super
+        <<~EOS
-        raise CaskUnspecifiedError if args.empty?
+          Zaps all files associated with the given <cask>. Implicitly also performs all actions associated with `uninstall`.
+
+          *May remove files which are shared between applications.*
+        EOS
+      end
+
+      def self.parser
+        super do
+          switch "--force",
+                 description: "Ignore errors when removing files."
+        end
       end
 
       def run
         casks.each do |cask|
           odebug "Zapping Cask #{cask}"
 
-          raise CaskNotInstalledError, cask unless cask.installed? || force?
+          raise CaskNotInstalledError, cask unless cask.installed? || args.force?
 
-          Installer.new(cask, verbose: verbose?, force: force?).zap
+          Installer.new(cask, verbose: args.verbose?, force: args.force?).zap
         end
       end
-
-      def self.help
-        "zaps all files associated with the given Cask"
-      end
     end
   end
 end

Library/Homebrew/cask/config.rb

@@ -12,12 +12,12 @@ module Cask
   class Config
     DEFAULT_DIRS = {
       appdir:               "/Applications",
+      colorpickerdir:       "~/Library/ColorPickers",
       prefpanedir:          "~/Library/PreferencePanes",
       qlplugindir:          "~/Library/QuickLook",
       mdimporterdir:        "~/Library/Spotlight",
       dictionarydir:        "~/Library/Dictionaries",
       fontdir:              "~/Library/Fonts",
-      colorpickerdir:       "~/Library/ColorPickers",
       servicedir:           "~/Library/Services",
       input_methoddir:      "~/Library/Input Methods",
       internet_plugindir:   "~/Library/Internet Plug-Ins",

Library/Homebrew/cask/dsl.rb

@@ -21,6 +21,7 @@ require "cask/dsl/uninstall_preflight"
 require "cask/dsl/version"
 
 require "cask/url"
+require "cask/utils"
 
 module Cask
   class DSL

Library/Homebrew/cli/parser.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "env_config"
 require "cli/args"
 require "optparse"
 require "set"
 require "formula"
+require "utils/tty"
 
 COMMAND_DESC_WIDTH = 80
 OPTION_DESC_WIDTH = 43
@@ -27,15 +29,24 @@ module Homebrew
 
       def self.global_options
         [
+          ["-d", "--debug", "Display any debugging information."],
           ["-q", "--quiet", "Suppress any warnings."],
           ["-v", "--verbose", "Make some output more verbose."],
-          ["-d", "--debug", "Display any debugging information."],
+          ["-h", "--help", "Show this message."],
         ]
       end
 
       def initialize(&block)
         @parser = OptionParser.new
 
+        @parser.summary_indent = " " * 2
+
+        # Disable default handling of `--version` switch.
+        @parser.base.long.delete("version")
+
+        # Disable default handling of `--help` switch.
+        @parser.base.long.delete("help")
+
         @args = Homebrew::CLI::Args.new
 
         @constraints = []
@@ -49,54 +60,44 @@ module Homebrew
         @formula_options = false
 
         self.class.global_options.each do |short, long, desc|
-          switch short, long, description: desc, env: option_to_name(long)
+          switch short, long, description: desc, env: option_to_name(long), method: :on_tail
         end
 
         instance_eval(&block) if block_given?
-
-        post_initialize
       end
 
-      def post_initialize
+      def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil, method: :on)
-        # Disable default handling of `--version` switch.
-        @parser.base.long.delete("version")
-
-        # Disable default handling of `--help` switch.
-        @parser.on_tail("-h", "--help", "Show this message.") do
-          # Handled in `brew.rb`.
-        end
-      end
-
-      def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil)
         global_switch = names.first.is_a?(Symbol)
         return if global_switch
 
         description = option_to_description(*names) if description.nil?
         process_option(*names, description)
-        @parser.on(*names, *wrap_option_desc(description)) do
+        @parser.public_send(method, *names, *wrap_option_desc(description)) do |value|
-          enable_switch(*names, from: :args)
+          set_switch(*names, value: value, from: :args)
         end
 
         names.each do |name|
           set_constraints(name, required_for: required_for, depends_on: depends_on)
         end
 
-        enable_switch(*names, from: :env) if env?(env)
+        env_value = env?(env)
+        set_switch(*names, value: env_value, from: :env) unless env_value.nil?
       end
       alias switch_option switch
 
       def env?(env)
-        return false if env.blank?
+        return if env.blank?
 
         Homebrew::EnvConfig.try(:"#{env}?")
       end
 
       def usage_banner(text)
-        @parser.banner = Formatter.wrap("#{text}\n", COMMAND_DESC_WIDTH)
+        @parser.banner = "#{text}\n"
       end
 
       def usage_banner_text
         @parser.banner
+               .gsub(/^  - (`[^`]+`)\s+/, "\n- \\1  \n  ") # Format `cask` subcommands as MarkDown list.
       end
 
       def comma_array(name, description: nil)
@@ -133,7 +134,7 @@ module Homebrew
       end
 
       def option_to_name(option)
-        option.sub(/\A--?/, "")
+        option.sub(/\A--?(\[no-\])?/, "")
               .tr("-", "_")
               .delete("=")
       end
@@ -150,10 +151,6 @@ module Homebrew
         names.map { |name| name.to_s.sub(/\A--?/, "").tr("-", " ") }.max
       end
 
-      def summary
-        @parser.to_s
-      end
-
       def parse_remaining(argv, ignore_invalid_options: false)
         i = 0
         remaining = []
@@ -221,23 +218,35 @@ module Homebrew
           remaining + non_options
         end
 
-        check_constraint_violations unless ignore_invalid_options
+        unless ignore_invalid_options
-        check_named_args(named_args) unless ignore_invalid_options
+          check_constraint_violations
+          check_named_args(named_args)
+        end
+
         @args.freeze_named_args!(named_args)
         @args.freeze_remaining_args!(non_options.empty? ? remaining : [*remaining, "--", non_options])
         @args.freeze_processed_options!(@processed_options)
 
         @args_parsed = true
+
+        if !ignore_invalid_options && @args.help?
+          puts generate_help_text
+          exit
+        end
+
         @args
       end
 
       def generate_help_text
-        @parser.to_s
+        Formatter.wrap(
-               .sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
+          @parser.to_s.gsub(/^  - (`[^`]+`\s+)/, "  \\1"), # Remove `-` from `cask` subcommand listing.
-               .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
+          COMMAND_DESC_WIDTH,
-               .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
+        )
-               .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")
+                 .sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
-               .gsub(/\*(.*?)\*/m, "#{Tty.underline}\\1#{Tty.reset}")
+                 .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
+                 .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
+                 .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")
+                 .gsub(/\*(.*?)\*/m, "#{Tty.underline}\\1#{Tty.reset}")
       end
 
       def formula_options
@@ -282,10 +291,10 @@ module Homebrew
 
       private
 
-      def enable_switch(*names, from:)
+      def set_switch(*names, value:, from:)
         names.each do |name|
           @switch_sources[option_to_name(name)] = from
-          @args["#{option_to_name(name)}?"] = true
+          @args["#{option_to_name(name)}?"] = value
         end
       end
 

Library/Homebrew/cmd/cask.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
-require "cask"
+require "cask/cmd"
 
 module Homebrew
   module_function
 
+  def cask_args
+    Cask::Cmd.parser
+  end
+
   def cask
+    ARGV.freeze
     Cask::Cmd.run(*ARGV)
   end
 end

Library/Homebrew/cmd/list.rb

@@ -111,7 +111,6 @@ module Homebrew
     lib/ruby/site_ruby/[12].*
     lib/ruby/vendor_ruby/[12].*
     manpages/brew.1
-    manpages/brew-cask.1
     share/pypy/*
     share/pypy3/*
     share/info/dir

Library/Homebrew/cmd/reinstall.rb

@@ -80,12 +80,12 @@ module Homebrew
 
     Cask::Cmd::Reinstall.reinstall_casks(
       *casks,
-      binaries:       args.binaries?,
+      binaries:       EnvConfig.cask_opts_binaries?,
       verbose:        args.verbose?,
       force:          args.force?,
-      require_sha:    args.require_sha?,
+      require_sha:    EnvConfig.cask_opts_require_sha?,
       skip_cask_deps: args.skip_cask_deps?,
-      quarantine:     args.quarantine?,
+      quarantine:     EnvConfig.cask_opts_quarantine?,
     )
   end
 end

Library/Homebrew/cmd/uninstall.rb

@@ -128,7 +128,7 @@ module Homebrew
 
     Cask::Cmd::Uninstall.uninstall_casks(
       *casks,
-      binaries: args.binaries?,
+      binaries: EnvConfig.cask_opts_binaries?,
       verbose:  args.verbose?,
       force:    args.force?,
     )

Library/Homebrew/cmd/upgrade.rb

@@ -152,9 +152,9 @@ module Homebrew
       force:          args.force?,
       greedy:         args.greedy?,
       dry_run:        args.dry_run?,
-      binaries:       args.binaries?,
+      binaries:       EnvConfig.cask_opts_binaries?,
-      quarantine:     args.quarantine?,
+      quarantine:     EnvConfig.cask_opts_quarantine?,
-      require_sha:    args.require_sha?,
+      require_sha:    EnvConfig.cask_opts_require_sha?,
       skip_cask_deps: args.skip_cask_deps?,
       verbose:        args.verbose?,
     )

Library/Homebrew/dev-cmd/man.rb

@@ -51,9 +51,6 @@ module Homebrew
     markup = build_man_page
     convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md", preserve_date: preserve_date)
     convert_man_page(markup, TARGET_MAN_PATH/"brew.1", preserve_date: preserve_date)
-
-    cask_markup = (SOURCE_PATH/"brew-cask.1.md").read
-    convert_man_page(cask_markup, TARGET_MAN_PATH/"brew-cask.1", preserve_date: preserve_date)
   end
 
   def build_man_page

Library/Homebrew/env_config.rb

@@ -55,7 +55,12 @@ module Homebrew
         default:      HOMEBREW_DEFAULT_CACHE,
       },
       HOMEBREW_CASK_OPTS:                 {
-        description: "Options which should be used for all `cask` commands.",
+        description: "Options which should be used for all `cask` commands. All `--*dir` options, " \
+                     "`--language`, `--require-sha`, `--no-quarantine` and `--no-binaries` are supported." \
+                     "\n" \
+                     "For example, you might add something like the following to your " \
+                     "~/.profile, ~/.bash_profile, or ~/.zshenv:\n\n" \
+                     "`export HOMEBREW_CASK_OPTS='--appdir=~/Applications --fontdir=/Library/Fonts'`",
       },
       HOMEBREW_CLEANUP_MAX_AGE_DAYS:      {
         description: "Cleanup all cached files older than this many days.",
@@ -276,6 +281,9 @@ module Homebrew
         description: "A comma-separated list of hostnames and domain names excluded " \
                      "from proxying by `curl`(1), `git`(1) and `svn`(1) when downloading through Homebrew.",
       },
+      SUDO_ASKPASS:                       {
+        description: "When this variable is set, the `-A` option is passed when calling `sudo`(8)",
+      },
     }.freeze
 
     def env_method_name(env, hash)

Library/Homebrew/manpages/brew-cask.1.md

@@ -1,278 +1 @@
-brew-cask(1) - a friendly binary installer for macOS
-====================================================
 
-## SYNOPSIS
-
-`brew cask` command [options] [ <token> ... ]
-
-## DESCRIPTION
-
-Homebrew Cask is a tool for installing precompiled macOS binaries (such as
-Applications) from the command line. The user is never required to use the
-graphical user interface.
-
-## FREQUENTLY USED COMMANDS
-
-  * `install` [--force] [--skip-cask-deps] [--require-sha] [--no-quarantine] [--language=<iso-language>[,<iso-language> ... ]] <token> [ <token> ... ]:
-    Install Cask identified by <token>.
-
-  * `uninstall` [--force] <token> [ <token> ... ]:
-    Uninstall Cask identified by <token>.
-
-## COMMANDS
-
-  * `--cache` <token> [ <token> ... ]:
-    Display the file used to cache the Cask identified by <token>.
-
-  * `audit` [--language=<iso-language>[,<iso-language> ... ]] [ <token> ... ]:
-    Check the given Casks for installability.
-    If no tokens are given on the command line, all Casks are audited.
-
-  * `cat` <token> [ <token> ... ]:
-    Dump the given Cask definition file to the standard output.
-
-  * `create` <token>:
-    Generate a Cask definition file for the Cask identified by <token>
-    and open a template for it in your favorite editor.
-
-  * `doctor` or `dr`:
-    Check for configuration issues. Can be useful to upload as a gist for
-    developers along with a bug report.
-
-  * `edit` <token>:
-    Open the given Cask definition file for editing.
-
-  * `fetch` [--force] [--no-quarantine] <token> [ <token> ... ]:
-    Download remote application files for the given Cask to the local
-    cache. With `--force`, force re-download even if the files are already
-    cached. `--no-quarantine` will prevent Gatekeeper from
-    enforcing its security restrictions on the Cask.
-
-  * `home` or `homepage` [ <token> ... ]:
-    Display the homepage associated with a given Cask in a browser.
-
-    With no arguments, display the project page <https://brew.sh/>.
-
-  * `info` or `abv` <token> [ <token> ... ]:
-    Display information about the given Cask.
-
-  * `install` [--force] [--skip-cask-deps] [--require-sha] [--no-quarantine] <token> [ <token> ... ]:
-    Install the given Cask. With `--force`, re-install even if the Cask
-    appears to be already present. With `--skip-cask-deps`, skip any Cask
-    dependencies. `--require-sha` will abort installation if the Cask does not
-    have a checksum defined. `--no-quarantine` will prevent Gatekeeper from
-    enforcing its security restrictions on the Cask.
-
-    <token> is usually the ID of a Cask,
-    but see [OTHER WAYS TO SPECIFY A CASK][] for variations.
-
-  * `list` or `ls` [-1] [--versions] [ <token> ... ]:
-    Without any arguments, list all installed Casks. With `-1`, always
-    format the output in a single column. With `--versions`, show all installed
-    versions.
-
-    If <token> is given, summarize the staged files associated with the
-    given Cask.
-
-  * `outdated` [--greedy] [--verbose|--quiet] [ <token> ... ]:
-    Without token arguments, display all the installed Casks that have newer
-    versions available in the tap; otherwise check only the tokens given
-    in the command line.
-    If `--greedy` is given then also include in the output the Casks having
-    `auto_updates true` or `version :latest`. Otherwise they are skipped
-    because there is no reliable way to know when updates are available for
-    them.<br>
-    `--verbose` forces the display of the outdated and latest version.<br>
-    `--quiet` suppresses the display of versions.
-
-  * `reinstall` [--no-quarantine] <token> [ <token> ... ]:
-    Reinstall the given Cask.
-
-  * `style` [--fix] [ <token> ... ]:
-    Check the given Casks for correct style using RuboCop (with custom Cask cops).
-    If no tokens are given on the command line, all Casks are checked.
-    With `--fix`, auto-correct any style errors if possible.
-
-  * `uninstall` or `rm` or `remove` [--force] <token> [ <token> ... ]:
-    Uninstall the given Cask. With `--force`, uninstall even if the Cask
-    does not appear to be present.
-
-  * `upgrade` [--force] [--greedy] [--dry-run] <token> [ <token> ... ]:
-    Without token arguments, upgrade all the installed Casks that have newer
-    versions available in the tap; otherwise update the tokens given
-    in the command line.
-    If `--greedy` is given then also upgrade the Casks having `auto_updates true`
-    or `version :latest`.
-
-    If `--dry-run` is given, show what would be upgraded, but do not actually
-    upgrade anything.
-
-  * `zap` [--force] <token> [ <token> ... ]:
-    Unconditionally remove _all_ files associated with the given Cask.
-    With `--force`, zap even if the Cask does not appear to be currently installed.
-
-    Implicitly performs all actions associated with `uninstall`.
-
-    Removes all staged versions of the Cask distribution found under
-    `<Caskroom_path>/`<token>.
-
-    If the Cask definition contains a `zap` stanza, performs additional
-    `zap` actions as defined there, such as removing local preference
-    files. `zap` actions are variable, depending on the level of detail
-    defined by the Cask author.
-
-    **`zap` may remove files which are shared between applications.**
-
-## INTERNAL COMMANDS
-
-  * `_stanza` <stanza_name> [ --table | --yaml | --inspect | --quiet ] [ <token> ... ]:
-    Given a <stanza_name> and a <token>, returns the current stanza for a
-    given Cask. If no <token> is given, then data for all Casks is returned.
-
-## OPTIONS
-
-To make these options persistent, see the [ENVIRONMENT](#environment) section, below.
-
-Some of these (such as `--prefpanedir`) may be subject to removal
-in a future version.
-
-  * `--force`:
-    Force an install to proceed even when a previously-existing install
-    is detected.
-
-  * `--skip-cask-deps`:
-    Skip Cask dependencies when installing.
-
-  *  `--require-sha`:
-    Abort Cask installation if the Cask does not have a checksum defined.
-
-  *  `--no-quarantine`:
-    Prevent Gatekeeper from enforcing its security restrictions on the Cask.
-    This will let you run it straightaway.
-
-  * `--verbose`:
-    Give additional feedback during installation.
-
-  * `--appdir=<path>`:
-    Target location for Applications. The default value is `/Applications`.
-
-  * `--language=<iso-language>[,<iso-language> ... ]]`:
-    Set language of the Cask to install. The first matching language is used, otherwise the default language on the Cask. The default value is the `language of your system`.
-
-  * `--colorpickerdir=<path>`:
-    Target location for Color Pickers. The default value is `~/Library/ColorPickers`.
-
-  * `--prefpanedir=<path>`:
-    Target location for Preference Panes. The default value is `~/Library/PreferencePanes`.
-
-  * `--qlplugindir=<path>`:
-    Target location for QuickLook Plugins. The default value is `~/Library/QuickLook`.
-
-  * `--dictionarydir=<path>`:
-    Target location for Dictionaries. The default value is `~/Library/Dictionaries`.
-
-  * `--fontdir=<path>`:
-    Target location for Fonts. The default value is `~/Library/Fonts`.
-
-  * `--servicedir=<path>`:
-    Target location for Services. The default value is `~/Library/Services`.
-
-  * `--input_methoddir=<path>`:
-    Target location for Input Methods. The default value is `~/Library/Input Methods`.
-
-  * `--internet_plugindir=<path>`:
-    Target location for Internet Plugins. The default value is `~/Library/Internet Plug-Ins`.
-
-  * `--audio_unit_plugindir=<path>`:
-    Target location for Audio Unit Plugins. The default value is `~/Library/Audio/Plug-Ins/Components`.
-
-  * `--vst_plugindir=<path>`:
-    Target location for VST Plugins. The default value is `~/Library/Audio/Plug-Ins/VST`.
-
-  * `--vst3_plugindir=<path>`:
-    Target location for VST3 Plugins. The default value is `~/Library/Audio/Plug-Ins/VST3`.
-
-  * `--screen_saverdir=<path>`:
-    Target location for Screen Savers. The default value is `~/Library/Screen Savers`.
-
-  * `--no-binaries`:
-    Do not link "helper" executables to `/usr/local/bin`.
-
-  * `--debug`:
-    Output debugging information of use to Cask authors and developers.
-
-## INTERACTION WITH HOMEBREW
-
-Homebrew Cask is implemented as a external command for Homebrew. That means
-this project is entirely built upon the Homebrew infrastructure. For
-example, upgrades to the Homebrew Cask tool are received through Homebrew:
-
-    brew update; brew cask upgrade; brew cleanup
-
-And updates to individual Cask definitions are received whenever you issue
-the Homebrew command:
-
-    brew update
-
-## OTHER WAYS TO SPECIFY A CASK
-
-Most Homebrew Cask commands can accept a Cask token as an argument. As
-described above, the argument can take the form of:
-
-  * A simple token, e.g. `google-chrome`
-
-Homebrew Cask also accepts three other forms in place of plain tokens:
-
-  * A fully-qualified token which includes the Tap name, e.g.
-    `homebrew/cask-fonts/font-symbola`
-
-  * A fully-qualified pathname to a Cask file, e.g.
-    `/usr/local/Library/Taps/homebrew/homebrew-cask/Casks/google-chrome.rb`
-
-  * A `curl`-retrievable URI to a Cask file, e.g.
-    `https://raw.githubusercontent.com/Homebrew/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb`
-
-## ENVIRONMENT
-
-Homebrew Cask respects many of the environment variables used by the
-parent command `brew`. Please refer to the `brew`(1) man page for more
-information.
-
-Environment variables specific to Homebrew Cask:
-
-  * `HOMEBREW_CASK_OPTS`:
-    This variable may contain any arguments normally used as options on
-    the command-line. This is particularly useful to make options persistent.
-    For example, you might add to your ~/.profile, ~/.bash_profile, or ~/.zshenv
-    something like:
-
-               export HOMEBREW_CASK_OPTS='--appdir=~/Applications --fontdir=/Library/Fonts'
-
-Other environment variables:
-
-  * `SUDO_ASKPASS`:
-    When this variable is set, Homebrew Cask will call `sudo`(8) with the `-A` option.
-
-
-## SEE ALSO
-
-The Homebrew home page: <https://brew.sh/>
-
-The Homebrew Cask GitHub page: <https://github.com/Homebrew/homebrew-cask>
-
-`brew`(1), `curl`(1)
-
-## AUTHORS
-
-Paul Hinze and Contributors.
-
-Man page format based on `brew.1.md` from Homebrew.
-
-## BUGS
-
-We still have bugs - and we are busy fixing them!  If you have a problem, don't
-be shy about reporting it on our [GitHub issues page](https://github.com/Homebrew/homebrew-cask/issues?state=open).
-
-When reporting bugs, remember that Homebrew Cask is an separate repository within
-Homebrew. Do your best to direct bug reports to the appropriate repository. If
-your command-line started with `brew cask`, bring the bug to us first!

Library/Homebrew/manpages/brew.1.md.erb

@@ -101,6 +101,12 @@ can take several different forms:
     Homebrew can install formulae from a local path. It can point to either a
     formula file or a bottle.
 
+## SPECIFYING CASKS
+
+Many Homebrew Cask commands accept one or more <cask> arguments. These can be
+specified the same way as the <formula> arguments described in
+`SPECIFYING FORMULAE` above.
+
 ## ENVIRONMENT
 
 Note that environment variables must have a value set to be detected. For example, run
@@ -155,3 +161,6 @@ See our issues on GitHub:
 
   * **Homebrew/homebrew-core**:
     <https://github.com/Homebrew/homebrew-core/issues>
+
+  * **Homebrew/homebrew-cask**:
+    <https://github.com/Homebrew/homebrew-cask/issues>

Library/Homebrew/sorbet/files.yaml

@@ -449,7 +449,6 @@ false:
 false:
   - ./PATH.rb
   - ./build_environment.rb
-  - ./cask/cmd/options.rb
   - ./cask/config.rb
   - ./cask/dsl/appcast.rb
   - ./cask/dsl/container.rb
@@ -505,7 +504,6 @@ false:
   - ./test/cache_store_spec.rb
   - ./test/cask/cask_loader/from_content_loader_spec.rb
   - ./test/cask/cask_loader/from_uri_loader_spec.rb
-  - ./test/cask/cmd/options_spec.rb
   - ./test/cask/cmd/shared_examples/invalid_option.rb
   - ./test/cask/config_spec.rb
   - ./test/cask/denylist_spec.rb

Library/Homebrew/test/cask/cmd/audit_spec.rb

@@ -22,176 +22,100 @@ describe Cask::Cmd::Audit, :cask do
       expect(Cask::CaskLoader).to receive(:load).with(cask_token).and_return(cask)
 
       expect(Cask::Auditor).to receive(:audit)
-        .with(cask, audit_download:        false,
+        .with(cask, quarantine: true)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
         .and_return(result)
 
       described_class.run(cask_token)
     end
   end
 
-  describe "rules for downloading a Cask" do
+  it "does not pass anything if no flags are specified" do
-    it "does not download the Cask per default" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
-      expect(Cask::Auditor).to receive(:audit)
+      .with(cask, quarantine: true)
-        .with(cask, audit_download:        false,
+      .and_return(result)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
 
-      described_class.run("casktoken")
+    described_class.run("casktoken")
-    end
-
-    it "download a Cask if --download flag is set" do
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      expect(Cask::Auditor).to receive(:audit)
-        .with(cask, audit_download:        true,
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
-
-      described_class.run("casktoken", "--download")
-    end
   end
 
-  describe "rules for checking token conflicts" do
+  it "passes `audit_download` if the `--download` flag is specified" do
-    it "does not check for token conflicts per default" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
-      expect(Cask::Auditor).to receive(:audit)
+      .with(cask, audit_download: true, quarantine: true)
-        .with(cask, audit_download:        false,
+      .and_return(result)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
 
-      described_class.run("casktoken")
+    described_class.run("casktoken", "--download")
-    end
-
-    it "checks for token conflicts if --token-conflicts flag is set" do
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      expect(Cask::Auditor).to receive(:audit)
-        .with(cask, audit_download:        false,
-                    audit_appcast:         false,
-                    audit_token_conflicts: true,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
-
-      described_class.run("casktoken", "--token-conflicts")
-    end
   end
 
-  describe "rules for checking strictly" do
+  it "passes `audit_token_conflicts` if the `--token-conflicts` flag is specified" do
-    it "does not check strictly per default" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
-      expect(Cask::Auditor).to receive(:audit)
+      .with(cask, audit_token_conflicts: true, quarantine: true)
-        .with(cask, audit_download:        false,
+      .and_return(result)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
 
-      described_class.run("casktoken")
+    described_class.run("casktoken", "--token-conflicts")
-    end
-
-    it "checks strictly if --strict flag is set" do
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      expect(Cask::Auditor).to receive(:audit)
-        .with(cask, audit_download:        false,
-                    audit_appcast:         false,
-                    audit_token_conflicts: true,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          true,
-                    quarantine:            true)
-        .and_return(result)
-
-      described_class.run("casktoken", "--strict")
-    end
   end
 
-  describe "rules for checking online" do
+  it "passes `audit_strict` and `audit_token_conflicts` if the `--strict` flag is specified" do
-    it "does not check online per default" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
-      expect(Cask::Auditor).to receive(:audit)
+      .with(cask, audit_strict: true, audit_token_conflicts: true, quarantine: true)
-        .with(cask, audit_download:        false,
+      .and_return(result)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
 
-      described_class.run("casktoken")
+    described_class.run("casktoken", "--strict")
-    end
-
-    it "checks online if --online flag is set" do
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      expect(Cask::Auditor).to receive(:audit)
-        .with(cask, audit_download:        true,
-                    audit_appcast:         true,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          true,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
-
-      described_class.run("casktoken", "--online")
-    end
   end
 
-  describe "rules for checking new casks" do
+  it "passes `audit_online` if the `--online` flag is specified" do
-    it "does not check new casks per default" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
-      expect(Cask::Auditor).to receive(:audit)
+      .with(cask, audit_online: true, audit_appcast: true, audit_download: true, quarantine: true)
-        .with(cask, audit_download:        false,
+      .and_return(result)
-                    audit_appcast:         false,
-                    audit_token_conflicts: false,
-                    audit_new_cask:        false,
-                    audit_online:          false,
-                    audit_strict:          false,
-                    quarantine:            true)
-        .and_return(result)
 
-      described_class.run("casktoken")
+    described_class.run("casktoken", "--online")
-    end
+  end
 
-    it "checks new casks if --new-cask flag is set" do
+  it "passes `audit_appcast`, `audit_download`, `audit_new_cask`, `audit_online`, `audit_strict` " \
-      allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+     "and `audit_token_conflicts` if the `--new-cask` flag is specified" do
-      expect(Cask::Auditor).to receive(:audit)
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
-        .with(cask, audit_download:        true,
+    expect(Cask::Auditor).to receive(:audit)
-                    audit_appcast:         true,
+      .with(cask, audit_appcast:         true,
-                    audit_token_conflicts: true,
+                  audit_download:        true,
-                    audit_new_cask:        true,
+                  audit_new_cask:        true,
-                    audit_online:          true,
+                  audit_online:          true,
-                    audit_strict:          true,
+                  audit_strict:          true,
-                    quarantine:            true)
+                  audit_token_conflicts: true,
-        .and_return(result)
+                  quarantine:            true)
+      .and_return(result)
 
-      described_class.run("casktoken", "--new-cask")
+    described_class.run("casktoken", "--new-cask")
-    end
+  end
+
+  it "passes `language` if the `--language` flag is specified" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
+      .with(cask, quarantine: true, language: ["de-AT"])
+      .and_return(result)
+
+    described_class.run("casktoken", "--language=de-AT")
+  end
+
+  it "passes `quarantine` if the `--no-quarantine` flag is specified" do
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
+      .with(cask, quarantine: false)
+      .and_return(result)
+
+    described_class.run("casktoken", "--no-quarantine")
+  end
+
+  it "passes `quarantine` if the `--no-quarantine` flag is in HOMEBREW_CASK_OPTS" do
+    ENV["HOMEBREW_CASK_OPTS"] = "--no-quarantine"
+
+    allow(Cask::CaskLoader).to receive(:load).and_return(cask)
+    expect(Cask::Auditor).to receive(:audit)
+      .with(cask, quarantine: false)
+      .and_return(result)
+
+    described_class.run("casktoken")
   end
 end

Library/Homebrew/test/cask/cmd/create_spec.rb

@@ -46,7 +46,7 @@ describe Cask::Cmd::Create, :cask do
   it "raises an exception when more than one Cask is given" do
     expect {
       described_class.run("additional-cask", "another-cask")
-    }.to raise_error(/Only one Cask can be created at a time\./)
+    }.to raise_error(UsageError, /Only one cask can be created at a time\./)
   end
 
   it "raises an exception when the Cask already exists" do

Library/Homebrew/test/cask/cmd/doctor_spec.rb

@@ -14,6 +14,6 @@ describe Cask::Cmd::Doctor, :cask do
   it "raises an exception when arguments are given" do
     expect {
       described_class.run("argument")
-    }.to raise_error(ArgumentError)
+    }.to raise_error(UsageError, /does not take named arguments/)
   end
 end

Library/Homebrew/test/cask/cmd/edit_spec.rb

@@ -20,7 +20,7 @@ describe Cask::Cmd::Edit, :cask do
   it "raises an error when given more than one argument" do
     expect {
       described_class.new("local-caffeine", "local-transmission")
-    }.to raise_error(/Only one Cask can be edited at a time\./)
+    }.to raise_error(UsageError, /Only one cask can be edited at a time\./)
   end
 
   it "raises an exception when the Cask doesn't exist" do

Library/Homebrew/test/cask/cmd/options_spec.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-describe Cask::Cmd, :cask do
-  it "supports setting the appdir" do
-    described_class.new.process_options("help", "--appdir=/some/path/foo")
-
-    expect(Cask::Config.global.appdir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the appdir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--appdir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.appdir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the prefpanedir" do
-    described_class.new.process_options("help", "--prefpanedir=/some/path/foo")
-
-    expect(Cask::Config.global.prefpanedir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the prefpanedir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--prefpanedir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.prefpanedir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the qlplugindir" do
-    described_class.new.process_options("help", "--qlplugindir=/some/path/foo")
-
-    expect(Cask::Config.global.qlplugindir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the qlplugindir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--qlplugindir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.qlplugindir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the mdimporterdir" do
-    described_class.new.process_options("help", "--mdimporterdir=/some/path/foo")
-
-    expect(Cask::Config.global.mdimporterdir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the mdimporterdir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--mdimporterdir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.mdimporterdir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the colorpickerdir" do
-    described_class.new.process_options("help", "--colorpickerdir=/some/path/foo")
-
-    expect(Cask::Config.global.colorpickerdir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the colorpickerdir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--colorpickerdir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.colorpickerdir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the dictionarydir" do
-    described_class.new.process_options("help", "--dictionarydir=/some/path/foo")
-
-    expect(Cask::Config.global.dictionarydir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the dictionarydir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--dictionarydir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.dictionarydir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the fontdir" do
-    described_class.new.process_options("help", "--fontdir=/some/path/foo")
-
-    expect(Cask::Config.global.fontdir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the fontdir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--fontdir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.fontdir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "supports setting the servicedir" do
-    described_class.new.process_options("help", "--servicedir=/some/path/foo")
-
-    expect(Cask::Config.global.servicedir).to eq(Pathname.new("/some/path/foo"))
-  end
-
-  it "supports setting the servicedir from ENV" do
-    ENV["HOMEBREW_CASK_OPTS"] = "--servicedir=/some/path/bar"
-
-    described_class.new.process_options("help")
-
-    expect(Cask::Config.global.servicedir).to eq(Pathname.new("/some/path/bar"))
-  end
-
-  it "allows additional options to be passed through" do
-    rest = described_class.new.process_options("edit", "foo", "--create", "--appdir=/some/path/qux")
-
-    expect(Cask::Config.global.appdir).to eq(Pathname.new("/some/path/qux"))
-    expect(rest).to eq(%w[edit foo --create])
-  end
-
-  describe "--help" do
-    it "sets the Cask help method to true" do
-      command = described_class.new("foo", "--help")
-      expect(command.help?).to be true
-    end
-  end
-end

Library/Homebrew/test/cask/cmd/outdated_spec.rb

@@ -15,8 +15,6 @@ describe Cask::Cmd::Outdated, :cask do
 
   before do
     installed.each { |cask| InstallHelper.install_with_caskfile(cask) }
-
-    allow_any_instance_of(described_class).to receive(:verbose?).and_return(true)
   end
 
   it_behaves_like "a command that handles invalid options"
@@ -25,7 +23,7 @@ describe Cask::Cmd::Outdated, :cask do
     it "checks all the installed Casks when no token is provided" do
       expect {
         described_class.run
-      }.to output(<<~EOS).to_stdout
+      }.to output(<<~EOS).to_stdout.as_tty
         local-caffeine (1.2.2) != 1.2.3
         local-transmission (2.60) != 2.61
       EOS
@@ -34,7 +32,7 @@ describe Cask::Cmd::Outdated, :cask do
     it "checks only the tokens specified in the command line" do
       expect {
         described_class.run("local-caffeine")
-      }.to output(<<~EOS).to_stdout
+      }.to output(<<~EOS).to_stdout.as_tty
         local-caffeine (1.2.2) != 1.2.3
       EOS
     end
@@ -42,17 +40,24 @@ describe Cask::Cmd::Outdated, :cask do
     it 'ignores "auto_updates" and "latest" Casks even when their tokens are provided in the command line' do
       expect {
         described_class.run("local-caffeine", "auto-updates", "version-latest-string")
-      }.to output(<<~EOS).to_stdout
+      }.to output(<<~EOS).to_stdout.as_tty
         local-caffeine (1.2.2) != 1.2.3
       EOS
     end
   end
 
-  describe "--quiet overrides --verbose" do
+  describe "--quiet overrides TTY" do
-    before do
+    it "lists only the names (no versions) of the outdated Casks with --quiet" do
-      allow_any_instance_of(described_class).to receive(:verbose?).and_call_original
+      expect {
+        described_class.run("--quiet")
+      }.to output(<<~EOS).to_stdout.as_tty
+        local-caffeine
+        local-transmission
+      EOS
     end
+  end
 
+  describe "--quiet overrides --verbose" do
     it "lists only the names (no versions) of the outdated Casks with --quiet" do
       expect {
         described_class.run("--verbose", "--quiet")
@@ -67,7 +72,7 @@ describe Cask::Cmd::Outdated, :cask do
     it 'includes the Casks with "auto_updates true" or "version latest" with --greedy' do
       expect {
         described_class.run("--greedy")
-      }.to output(<<~EOS).to_stdout
+      }.to output(<<~EOS).to_stdout.as_tty
         auto-updates (2.57) != 2.61
         local-caffeine (1.2.2) != 1.2.3
         local-transmission (2.60) != 2.61
@@ -81,7 +86,7 @@ describe Cask::Cmd::Outdated, :cask do
 
       expect {
         described_class.run("--greedy")
-      }.to output(<<~EOS).to_stdout
+      }.to output(<<~EOS).to_stdout.as_tty
         local-caffeine (1.2.2) != 1.2.3
         local-transmission (2.60) != 2.61
         version-latest-string (latest) != latest

Library/Homebrew/test/cask/cmd/style_spec.rb

@@ -46,7 +46,7 @@ describe Cask::Cmd::Style, :cask do
     subject { cli.cask_paths }
 
     before do
-      allow(cli).to receive(:args).and_return(tokens)
+      allow(cli).to receive(:args).and_return(instance_double(Homebrew::CLI::Args, named: tokens))
     end
 
     context "when no cask tokens are given" do

Library/Homebrew/test/cask/cmd_spec.rb

@@ -1,31 +1,9 @@
 # frozen_string_literal: true
 
 describe Cask::Cmd, :cask do
-  it "lists the taps for Casks that show up in two taps" do
+  context "when no subcommand is given" do
-    listing = described_class.nice_listing(%w[
+    it "raises an error" do
-                                             homebrew/cask/adium
+      expect { subject.run }.to raise_error(UsageError, /subcommand/)
-                                             homebrew/cask/google-chrome
-                                             passcod/homebrew-cask/adium
-                                           ])
-
-    expect(listing).to eq(%w[
-                            google-chrome
-                            homebrew/cask/adium
-                            passcod/cask/adium
-                          ])
-  end
-
-  context "when given no arguments" do
-    it "exits successfully" do
-      expect(subject).not_to receive(:exit).with(be_nonzero)
-      subject.run
-    end
-  end
-
-  context "when no option is specified" do
-    it "--binaries is true by default" do
-      command = Cask::Cmd::Install.new("some-cask")
-      expect(command.binaries?).to be true
     end
   end
 
@@ -33,10 +11,9 @@ describe Cask::Cmd, :cask do
     let(:noop_command) { double("Cmd::Noop", run: nil) }
 
     it "prints help output when subcommand receives `--help` flag" do
-      command = described_class.new("info", "--help")
+      expect {
-
+        described_class.run("info", "--help")
-      expect { command.run }.to output(/displays information about the given Cask/).to_stdout
+      }.to output(/Displays information about the given cask/).to_stdout
-      expect(command.help?).to eq(true)
     end
 
     it "respects the env variable when choosing what appdir to create" do

Library/Homebrew/test/cli/parser_spec.rb

@@ -15,6 +15,24 @@ describe Homebrew::CLI::Parser do
       allow(Homebrew::EnvConfig).to receive(:pry?).and_return(true)
     end
 
+    context "when using negative options" do
+      subject(:parser) {
+        described_class.new do
+          switch "--[no-]positive"
+        end
+      }
+
+      it "sets the positive name to false if the negative flag is passed" do
+        args = parser.parse(["--no-positive"])
+        expect(args).not_to be_positive
+      end
+
+      it "sets the positive name to true if the positive flag is passed" do
+        args = parser.parse(["--positive"])
+        expect(args).to be_positive
+      end
+    end
+
     context "when `ignore_invalid_options` is true" do
       it "passes through invalid options" do
         args = parser.parse(["-v", "named-arg", "--not-a-valid-option"], ignore_invalid_options: true)

Library/Homebrew/test/support/helper/spec/shared_context/homebrew_cask.rb

@@ -8,8 +8,6 @@ require "test/support/helper/cask/never_sudo_system_command"
 
 module Cask
   class Config
-    remove_const :DEFAULT_DIRS
-
     DEFAULT_DIRS_PATHNAMES = {
       appdir:               Pathname(TEST_TMPDIR)/"cask-appdir",
       prefpanedir:          Pathname(TEST_TMPDIR)/"cask-prefpanedir",
@@ -27,6 +25,7 @@ module Cask
       screen_saverdir:      Pathname(TEST_TMPDIR)/"cask-screen_saverdir",
     }.freeze
 
+    remove_const :DEFAULT_DIRS
     DEFAULT_DIRS = DEFAULT_DIRS_PATHNAMES.transform_values(&:to_s).freeze
   end
 end
@@ -51,7 +50,7 @@ RSpec.shared_context "Homebrew Cask", :needs_macos do
 
       example.run
     ensure
-      FileUtils.rm_rf Cask::Config::DEFAULT_DIRS.values
+      FileUtils.rm_rf Cask::Config::DEFAULT_DIRS_PATHNAMES.values
       FileUtils.rm_rf [Cask::Config.global.binarydir, Cask::Caskroom.path, Cask::Cache.path]
       Tap.default_cask_tap.path.unlink
       third_party_tap.path.unlink

docs/Manpage.md

@@ -44,24 +44,117 @@ If no search term is provided, all locally available formulae are listed.
 
 ### `analytics` [*`subcommand`*]
 
-Control Homebrew's anonymous aggregate user behaviour analytics. Read more at
+Control Homebrew's anonymous aggregate user behaviour analytics.
-<https://docs.brew.sh/Analytics>.
+Read more at <https://docs.brew.sh/Analytics>.
 
 `brew analytics` [`state`]:
-    Display the current state of Homebrew's analytics.
+Display the current state of Homebrew's analytics.
 
 `brew analytics` [`on`|`off`]:
-    Turn Homebrew's analytics on or off respectively.
+Turn Homebrew's analytics on or off respectively.
 
 `brew analytics regenerate-uuid`:
-    Regenerate the UUID used for Homebrew's analytics.
+Regenerate the UUID used for Homebrew's analytics.
+
+### `cask` *`command`* [*`options`*] [*`cask`*]
+
+Homebrew Cask provides a friendly CLI workflow for the administration of macOS applications distributed as binaries.
+
+Commands:
+
+- `--cache`  
+  Display the file used to cache a *`cask`*
+
+- `audit`  
+  Check *`cask`* for Homebrew coding style violations
+
+- `cat`  
+  Dump raw source of a *`cask`* to the standard output
+
+- `create`  
+  Creates the given *`cask`* and opens it in an editor
+
+- `doctor`  
+  Checks for configuration issues
+
+- `edit`  
+  Open the given *`cask`* for editing
+
+- `fetch`  
+  Downloads remote application files to local cache
+
+- `help`  
+  Print help for `cask` commands
+
+- `home`  
+  Opens the homepage of the given *`cask`*
+
+- `info`  
+  Displays information about the given *`cask`*
+
+- `install`  
+  Installs the given *`cask`*
+
+- `list`  
+  Lists installed casks or the casks provided in the arguments
+
+- `outdated`  
+  List the outdated installed casks
+
+- `reinstall`  
+  Reinstalls the given *`cask`*
+
+- `style`  
+  Checks style of the given *`cask`* using RuboCop
+
+- `uninstall`  
+  Uninstalls the given *`cask`*
+
+- `upgrade`  
+  Upgrades all outdated casks or the specified casks
+
+- `zap`  
+  Zaps all files associated with the given *`cask`*
+
+See also: `man brew`
+
+* `--appdir`:
+  Target location for Applications. Default: `/Applications`
+* `--colorpickerdir`:
+  Target location for Color Pickers. Default: `~/Library/ColorPickers`
+* `--prefpanedir`:
+  Target location for Preference Panes. Default: `~/Library/PreferencePanes`
+* `--qlplugindir`:
+  Target location for QuickLook Plugins. Default: `~/Library/QuickLook`
+* `--mdimporterdir`:
+  Target location for Spotlight Plugins. Default: `~/Library/Spotlight`
+* `--dictionarydir`:
+  Target location for Dictionaries. Default: `~/Library/Dictionaries`
+* `--fontdir`:
+  Target location for Fonts. Default: `~/Library/Fonts`
+* `--servicedir`:
+  Target location for Services. Default: `~/Library/Services`
+* `--input_methoddir`:
+  Target location for Input Methods. Default: `~/Library/Input Methods`
+* `--internet_plugindir`:
+  Target location for Internet Plugins. Default: `~/Library/Internet Plug-Ins`
+* `--audio_unit_plugindir`:
+  Target location for Audio Unit Plugins. Default: `~/Library/Audio/Plug-Ins/Components`
+* `--vst_plugindir`:
+  Target location for VST Plugins. Default: `~/Library/Audio/Plug-Ins/VST`
+* `--vst3_plugindir`:
+  Target location for VST3 Plugins. Default: `~/Library/Audio/Plug-Ins/VST3`
+* `--screen_saverdir`:
+  Target location for Screen Savers. Default: `~/Library/Screen Savers`
+* `--language`:
+  Set language of the Cask to install. The first matching language is used, otherwise the default language on the Cask. The default value is the `language of your system`
 
 ### `cleanup` [*`options`*] [*`formula`*|*`cask`*]
 
-Remove stale lock files and outdated downloads for all formulae and casks, and
+Remove stale lock files and outdated downloads for all formulae and casks,
-remove old versions of installed formulae. If arguments are specified, only do
+and remove old versions of installed formulae. If arguments are specified,
-this for the given formulae and casks. Removes all downloads more than 120 days
+only do this for the given formulae and casks. Removes all downloads more than
-old. This can be adjusted with `HOMEBREW_CLEANUP_MAX_AGE_DAYS`.
+120 days old. This can be adjusted with `HOMEBREW_CLEANUP_MAX_AGE_DAYS`.
 
 * `--prune`:
   Remove all cache files older than specified *`days`*.
@@ -83,14 +176,14 @@ Show lists of built-in and external commands.
 
 ### `config`
 
-Show Homebrew and system configuration info useful for debugging. If you file a
+Show Homebrew and system configuration info useful for debugging. If you file
-bug report, you will be required to provide this information.
+a bug report, you will be required to provide this information.
 
 ### `deps` [*`options`*] [*`formula`*]
 
-Show dependencies for *`formula`*. Additional options specific to *`formula`* may be
+Show dependencies for *`formula`*. Additional options specific to *`formula`*
-appended to the command. When given multiple formula arguments, show the
+may be appended to the command. When given multiple formula arguments,
-intersection of dependencies for each formula.
+show the intersection of dependencies for each formula.
 
 * `-n`:
   Sort dependencies in topological order.
@@ -123,9 +216,9 @@ intersection of dependencies for each formula.
 
 ### `desc` [*`options`*] (*`text`*|`/`*`text`*`/`|*`formula`*)
 
-Display *`formula`*'s name and one-line description. Formula descriptions are
+Display *`formula`*'s name and one-line description.
-cached; the cache is created on the first search, making that search slower than
+Formula descriptions are cached; the cache is created on the
-subsequent ones.
+first search, making that search slower than subsequent ones.
 
 * `-s`, `--search`:
   Search both names and descriptions for *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression.
@@ -136,11 +229,11 @@ subsequent ones.
 
 ### `doctor` [*`options`*]
 
-Check your system for potential problems. Will exit with a non-zero status if
+Check your system for potential problems. Will exit with a non-zero status
-any potential problems are found. Please note that these warnings are just used
+if any potential problems are found. Please note that these warnings are just
-to help the Homebrew maintainers with debugging if you file an issue. If
+used to help the Homebrew maintainers with debugging if you file an issue. If
-everything you use Homebrew for is working fine: please don't worry or file an
+everything you use Homebrew for is working fine: please don't worry or file
-issue; just ignore this.
+an issue; just ignore this.
 
 * `--list-checks`:
   List all audit methods, which can be run individually if provided as arguments.
@@ -149,8 +242,8 @@ issue; just ignore this.
 
 ### `fetch` [*`options`*] *`formula`*
 
-Download a bottle (if available) or source packages for *`formula`*. For tarballs,
+Download a bottle (if available) or source packages for *`formula`*.
-also print SHA-256 checksums.
+For tarballs, also print SHA-256 checksums.
 
 * `--HEAD`:
   Fetch HEAD version instead of stable version.
@@ -173,8 +266,8 @@ also print SHA-256 checksums.
 
 ### `gist-logs` [*`options`*] *`formula`*
 
-Upload logs for a failed build of *`formula`* to a new Gist. Presents an error
+Upload logs for a failed build of *`formula`* to a new Gist. Presents an
-message if no logs are found.
+error message if no logs are found.
 
 * `--with-hostname`:
   Include the hostname in the Gist.
@@ -185,8 +278,8 @@ message if no logs are found.
 
 ### `home` [*`formula`*]
 
-Open *`formula`*'s homepage in a browser, or open Homebrew's own homepage if no
+Open *`formula`*'s homepage in a browser, or open Homebrew's own homepage
-formula is provided.
+if no formula is provided.
 
 ### `info` [*`options`*] [*`formula`*]
 
@@ -213,11 +306,10 @@ If *`formula`* is provided, show summary of information about *`formula`*.
 
 ### `install` [*`options`*] *`formula`*
 
-Install *`formula`*. Additional options specific to *`formula`* may be appended to
+Install *`formula`*. Additional options specific to *`formula`* may be appended to the command.
-the command.
 
-Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
+Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
-the installed formulae or, every 30 days, for all formulae.
+installed formulae or, every 30 days, for all formulae.
 
 * `-d`, `--debug`:
   If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
@@ -264,8 +356,9 @@ List installed formulae that are not dependencies of another installed formula.
 
 ### `link`, `ln` [*`options`*] *`formula`*
 
-Symlink all of *`formula`*'s installed files into Homebrew's prefix. This is done
+Symlink all of *`formula`*'s installed files into Homebrew's prefix. This
-automatically when you install formulae but can be useful for DIY installations.
+is done automatically when you install formulae but can be useful for DIY
+installations.
 
 * `--overwrite`:
   Delete files that already exist in the prefix while linking.
@@ -305,8 +398,8 @@ If *`formula`* is provided, summarise the paths within its current keg.
 
 ### `log` [*`options`*] [*`formula`*]
 
-Show the `git log` for *`formula`*, or show the log for the Homebrew repository if
+Show the `git log` for *`formula`*, or show the log for the Homebrew repository
-no formula is provided.
+if no formula is provided.
 
 * `-p`, `--patch`:
   Also print patch from commit.
@@ -351,9 +444,8 @@ Show install options specific to *`formula`*.
 
 ### `outdated` [*`options`*] [*`formula`*|*`cask`*]
 
-List installed casks and formulae that have an updated version available. By
+List installed casks and formulae that have an updated version available. By default, version
-default, version information is displayed in interactive shells, and suppressed
+information is displayed in interactive shells, and suppressed otherwise.
-otherwise.
 
 * `-q`, `--quiet`:
   List only the names of outdated kegs (takes precedence over `--verbose`).
@@ -372,8 +464,8 @@ otherwise.
 
 ### `pin` *`formula`*
 
-Pin the specified *`formula`*, preventing them from being upgraded when issuing
+Pin the specified *`formula`*, preventing them from being upgraded when
-the `brew upgrade` *`formula`* command. See also `unpin`.
+issuing the `brew upgrade` *`formula`* command. See also `unpin`.
 
 ### `postinstall` *`formula`*
 
@@ -381,10 +473,10 @@ Rerun the post-install steps for *`formula`*.
 
 ### `readall` [*`options`*] [*`tap`*]
 
-Import all items from the specified *`tap`*, or from all installed taps if none is
+Import all items from the specified *`tap`*, or from all installed taps if none is provided.
-provided. This can be useful for debugging issues across all items when making
+This can be useful for debugging issues across all items when making
-significant changes to `formula.rb`, testing the performance of loading all
+significant changes to `formula.rb`, testing the performance of loading
-items or checking if any current formulae/casks have Ruby issues.
+all items or checking if any current formulae/casks have Ruby issues.
 
 * `--aliases`:
   Verify any alias symlinks in each tap.
@@ -396,8 +488,8 @@ items or checking if any current formulae/casks have Ruby issues.
 Uninstall and then install *`formula`* using the same options it was originally
 installed with, plus any appended brew formula options.
 
-Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
+Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
-the reinstalled formulae or, every 30 days, for all formulae.
+reinstalled formulae or, every 30 days, for all formulae.
 
 * `-d`, `--debug`:
   If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
@@ -418,12 +510,12 @@ the reinstalled formulae or, every 30 days, for all formulae.
 
 ### `search` [*`options`*] [*`text`*|`/`*`text`*`/`]
 
-Perform a substring search of cask tokens and formula names for *`text`*. If
+Perform a substring search of cask tokens and formula names for *`text`*. If *`text`*
-*`text`* is flanked by slashes, it is interpreted as a regular expression. The
+is flanked by slashes, it is interpreted as a regular expression.
-search for *`text`* is extended online to `homebrew/core` and `homebrew/cask`.
+The search for *`text`* is extended online to `homebrew/core` and `homebrew/cask`.
 
-If no *`text`* is provided, list all locally available formulae (including tapped
+If no *`text`* is provided, list all locally available formulae (including tapped ones).
-ones). No online search is performed.
+No online search is performed.
 
 * `--formula`:
   Without *`text`*, list all locally available formulae (no online search is performed). With *`text`*, search online and locally for formulae.
@@ -453,8 +545,7 @@ Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.p
 
 ### `switch` *`formula`* *`version`*
 
-Symlink all of the specified *`version`* of *`formula`*'s installation into
+Symlink all of the specified *`version`* of *`formula`*'s installation into Homebrew's prefix.
-Homebrew's prefix.
 
 ### `tap` [*`options`*] [*`user`*`/`*`repo`*] [*`URL`*]
 
@@ -462,15 +553,15 @@ Tap a formula repository.
 
 If no arguments are provided, list all installed taps.
 
-With *`URL`* unspecified, tap a formula repository from GitHub using HTTPS. Since
+With *`URL`* unspecified, tap a formula repository from GitHub using HTTPS.
-so many taps are hosted on GitHub, this command is a shortcut for `brew tap`
+Since so many taps are hosted on GitHub, this command is a shortcut for
-*`user`*`/`*`repo`* `https://github.com/`*`user`*`/homebrew-`*`repo`*.
+`brew tap` *`user`*`/`*`repo`* `https://github.com/`*`user`*`/homebrew-`*`repo`*.
 
-With *`URL`* specified, tap a formula repository from anywhere, using any
+With *`URL`* specified, tap a formula repository from anywhere, using
-transport protocol that `git`(1) handles. The one-argument form of `tap`
+any transport protocol that `git`(1) handles. The one-argument form of `tap`
-simplifies but also limits. This two-argument command makes no assumptions, so
+simplifies but also limits. This two-argument command makes no
-taps can be cloned from places other than GitHub and using protocols other than
+assumptions, so taps can be cloned from places other than GitHub and
-HTTPS, e.g. SSH, git, HTTP, FTP(S), rsync.
+using protocols other than HTTPS, e.g. SSH, git, HTTP, FTP(S), rsync.
 
 * `--full`:
   Convert a shallow clone to a full clone without untapping. Taps are only cloned as shallow clones on continuous integration, or if `--shallow` was originally passed.
@@ -505,17 +596,17 @@ Uninstall *`formula`*.
 
 ### `unlink` [*`options`*] *`formula`*
 
-Remove symlinks for *`formula`* from Homebrew's prefix. This can be useful for
+Remove symlinks for *`formula`* from Homebrew's prefix. This can be useful
-temporarily disabling a formula: `brew unlink` *`formula`* `&&` *`commands`* `&&
+for temporarily disabling a formula:
-brew link` *`formula`*
+`brew unlink` *`formula`* `&&` *`commands`* `&& brew link` *`formula`*
 
 * `-n`, `--dry-run`:
   List files which would be unlinked without actually unlinking or deleting any files.
 
 ### `unpin` *`formula`*
 
-Unpin *`formula`*, allowing them to be upgraded by `brew upgrade` *`formula`*. See
+Unpin *`formula`*, allowing them to be upgraded by `brew upgrade` *`formula`*.
-also `pin`.
+See also `pin`.
 
 ### `untap` *`tap`*
 
@@ -540,13 +631,12 @@ Fetch and reset Homebrew and all tap repositories (or any specified *`repository
 
 ### `upgrade` [*`options`*] [*`formula`*|*`cask`*]
 
-Upgrade outdated casks and outdated, unpinned formulae using the same options
+Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally
-they were originally installed with, plus any appended brew formula options. If
+installed with, plus any appended brew formula options. If *`cask`* or *`formula`* are specified,
-*`cask`* or *`formula`* are specified, upgrade only the given *`cask`* or *`formula`*
+upgrade only the given *`cask`* or *`formula`* kegs (unless they are pinned; see `pin`, `unpin`).
-kegs (unless they are pinned; see `pin`, `unpin`).
 
-Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
+Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
-the upgraded formulae or, every 30 days, for all formulae.
+upgraded formulae or, every 30 days, for all formulae.
 
 * `-d`, `--debug`:
   If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
@@ -579,10 +669,10 @@ the upgraded formulae or, every 30 days, for all formulae.
 
 ### `uses` [*`options`*] *`formula`*
 
-Show formulae that specify *`formula`* as a dependency (i.e. show dependents of
+Show formulae that specify *`formula`* as a dependency (i.e. show dependents
-*`formula`*). When given multiple formula arguments, show the intersection of
+of *`formula`*). When given multiple formula arguments, show the intersection
-formulae that use *`formula`*. By default, `uses` shows all formulae that specify
+of formulae that use *`formula`*. By default, `uses` shows all formulae that
-*`formula`* as a required or recommended dependency for their stable builds.
+specify *`formula`* as a required or recommended dependency for their stable builds.
 
 * `--recursive`:
   Resolve more than one level of dependencies.
@@ -620,13 +710,13 @@ If *`formula`* is provided, display the file or directory used to cache *`formul
 
 Display Homebrew's Caskroom path.
 
-If *`cask`* is provided, display the location in the Caskroom where *`cask`* would
+If *`cask`* is provided, display the location in the Caskroom where *`cask`*
-be installed, without any sort of versioned directory as the last path.
+would be installed, without any sort of versioned directory as the last path.
 
 ### `--cellar` [*`formula`*]
 
-Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if that
+Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
-directory doesn't exist, `$(brew --repository)/Cellar`.
+that 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.
@@ -635,8 +725,8 @@ would be installed, without any sort of versioned directory as the last path.
 
 Summarise Homebrew's build environment as a plain list.
 
-If the command's output is sent through a pipe and no shell is specified, the
+If the command's output is sent through a pipe and no shell is specified,
-list is formatted for export to `bash`(1) unless `--plain` is passed.
+the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
 * `--shell`:
   Generate a list of environment variables for the specified shell, or `--shell=auto` to detect the current shell.
@@ -648,20 +738,19 @@ list is formatted for export to `bash`(1) unless `--plain` is passed.
 Display Homebrew's install path. *Default:* `/usr/local` on macOS and
 `/home/linuxbrew/.linuxbrew` on Linux.
 
-If *`formula`* is provided, display the location in the Cellar where *`formula`* is
+If *`formula`* is provided, display the location in the Cellar where *`formula`*
-or would be installed.
+is or would be installed.
 
 ### `--repository`, `--repo` [*`user`*`/`*`repo`*]
 
 Display where Homebrew's `.git` directory is located.
 
-If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory
+If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory is located.
-is located.
 
 ### `--version`
 
-Print the version numbers of Homebrew, Homebrew/homebrew-core and
+Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask
-Homebrew/homebrew-cask (if tapped) to standard output.
+(if tapped) to standard output.
 
 ## DEVELOPER COMMANDS
 
@@ -669,8 +758,8 @@ Homebrew/homebrew-cask (if tapped) to standard output.
 
 Check *`formula`* for Homebrew coding style violations. This should be run before
 submitting a new formula. If no *`formula`* are provided, check all locally
-available formulae and skip style checks. Will exit with a non-zero status if
+available formulae and skip style checks. Will exit with a non-zero status if any
-any errors are found.
+errors are found.
 
 * `--strict`:
   Run additional, stricter style checks.
@@ -704,9 +793,10 @@ any errors are found.
 ### `bottle` [*`options`*] *`formula`*
 
 Generate a bottle (binary package) from a formula that was installed with
-`--build-bottle`. If the formula specifies a rebuild version, it will be
+`--build-bottle`.
-incremented in the generated DSL. Passing `--keep-old` will attempt to keep it
+If the formula specifies a rebuild version, it will be incremented in the
-at its original value, while `--no-rebuild` will remove it.
+generated DSL. Passing `--keep-old` will attempt to keep it at its original
+value, while `--no-rebuild` will remove it.
 
 * `--skip-relocation`:
   Do not check if the bottle can be marked as relocatable.
@@ -739,14 +829,12 @@ If a *`tag`* is specified, the Git commit *`revision`* corresponding to that tag
 should also be specified. A best effort to determine the *`revision`* will be made
 if the value is not supplied by the user.
 
-If a *`version`* is specified, a best effort to determine the *`URL`* and *`SHA-256`*
+If a *`version`* is specified, a best effort to determine the *`URL`* and *`SHA-256`* or
-or the *`tag`* and *`revision`* will be made if both values are not supplied by the
+the *`tag`* and *`revision`* will be made if both values are not supplied by the user.
-user.
 
 *Note:* this command cannot be used to transition a formula from a
 URL-and-SHA-256 style specification into a tag-and-revision style specification,
-nor vice versa. It must use whichever style specification the formula already
+nor vice versa. It must use whichever style specification the formula already uses.
-uses.
 
 * `-n`, `--dry-run`:
   Print what would be done rather than doing it.
@@ -800,7 +888,8 @@ Display the path to the file being used when invoking `brew` *`cmd`*.
 Generate a formula for the downloadable file at *`URL`* and open it in the editor.
 Homebrew will attempt to automatically derive the formula name and version, but
 if it fails, you'll have to make your own template. The `wget` formula serves as
-a simple example. For the complete API, see: <https://rubydoc.brew.sh/Formula>
+a simple example. For the complete API, see:
+<https://rubydoc.brew.sh/Formula>
 
 * `--autotools`:
   Create a basic template for an Autotools-style build.
@@ -839,9 +928,9 @@ a simple example. For the complete API, see: <https://rubydoc.brew.sh/Formula>
 
 ### `diy` [*`options`*]
 
-Automatically determine the installation prefix for non-Homebrew software. Using
+Automatically determine the installation prefix for non-Homebrew software.
-the output from this command, you can install your own software into the Cellar
+Using the output from this command, you can install your own software into
-and then link it into Homebrew's prefix with `brew link`.
+the Cellar and then link it into Homebrew's prefix with `brew link`.
 
 * `--name`:
   Explicitly set the *`name`* of the package being installed.
@@ -857,8 +946,8 @@ Homebrew repository for editing if no formula is provided.
 
 Look through repository history to find the most recent version of *`formula`* and
 create a copy in *`tap`*`/Formula/`*`formula`*`@`*`version`*`.rb`. If the tap is not
-installed yet, attempt to install/clone the tap before continuing. To extract a
+installed yet, attempt to install/clone the tap before continuing. To extract
-formula from a tap that is not `homebrew/core` use its fully-qualified form of
+a formula from a tap that is not `homebrew/core` use its fully-qualified form of
 *`user`*`/`*`repo`*`/`*`formula`*.
 
 * `--version`:
@@ -923,8 +1012,8 @@ Find pull requests that can be automatically merged using `brew pr-publish`.
 
 ### `pr-publish` [*`options`*] *`pull_request`* [*`pull_request`* ...]
 
-Publish bottles for a pull request with GitHub Actions. Requires write access to
+Publish bottles for a pull request with GitHub Actions.
-the repository.
+Requires write access to the repository.
 
 * `--tap`:
   Target tap repository (default: `homebrew/core`).
@@ -933,9 +1022,9 @@ the repository.
 
 ### `pr-pull` [*`options`*] *`pull_request`* [*`pull_request`* ...]
 
-Download and publish bottles, and apply the bottle commit from a pull request
+Download and publish bottles, and apply the bottle commit from a
-with artifacts generated by GitHub Actions. Requires write access to the
+pull request with artifacts generated by GitHub Actions.
-repository.
+Requires write access to the repository.
 
 * `--no-publish`:
   Download the bottles, apply the bottle commit and upload the bottles to Bintray, but don't publish them.
@@ -987,17 +1076,17 @@ Run Homebrew with the Ruby profiler, e.g. `brew prof readall`.
 
 ### `release-notes` [*`options`*] [*`previous_tag`*] [*`end_ref`*]
 
-Print the merged pull requests on Homebrew/brew between two Git refs. If no
+Print the merged pull requests on Homebrew/brew between two Git refs.
-*`previous_tag`* is provided it defaults to the latest tag. If no *`end_ref`* is
+If no *`previous_tag`* is provided it defaults to the latest tag.
-provided it defaults to `origin/master`.
+If no *`end_ref`* is provided it defaults to `origin/master`.
 
 * `--markdown`:
   Print as a Markdown list.
 
 ### `ruby` (`-e` *`text`*|*`file`*)
 
-Run a Ruby instance with Homebrew's libraries loaded, e.g. `brew ruby -e "puts
+Run a Ruby instance with Homebrew's libraries loaded, e.g.
-:gcc.f.deps"` or `brew ruby script.rb`.
+`brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`.
 
 * `-r`:
   Load a library using `require`.
@@ -1007,26 +1096,25 @@ Run a Ruby instance with Homebrew's libraries loaded, e.g. `brew ruby -e "puts
 ### `sh` [*`options`*]
 
 Start a Homebrew build environment shell. Uses our years-battle-hardened
-Homebrew build logic to help your `./configure && make && make install` or even
+Homebrew build logic to help your `./configure && make && make install`
-your `gem install` succeed. Especially handy if you run Homebrew in an
+or even your `gem install` succeed. Especially handy if you run Homebrew
-Xcode-only configuration since it adds tools like `make` to your `PATH` which
+in an Xcode-only configuration since it adds tools like `make` to your `PATH`
-build systems would not find otherwise.
+which build systems would not find otherwise.
 
 * `--env`:
   Use the standard `PATH` instead of superenv's when `std` is passed.
 
 ### `sponsors`
 
-Print a Markdown summary of Homebrew's GitHub Sponsors, suitable for pasting
+Print a Markdown summary of Homebrew's GitHub Sponsors, suitable for pasting into a README.
-into a README.
 
 ### `style` [*`options`*] [*`file`*|*`tap`*|*`formula`*]
 
 Check formulae or files for conformance to Homebrew style guidelines.
 
-Lists of *`file`*, *`tap`* and *`formula`* may not be combined. If none are provided,
+Lists of *`file`*, *`tap`* and *`formula`* may not be combined. If none are
-`style` will run style checks on the whole Homebrew library, including core code
+provided, `style` will run style checks on the whole Homebrew library,
-and all formulae.
+including core code and all formulae.
 
 * `--fix`:
   Fix style violations automatically using RuboCop's auto-correct feature.
@@ -1043,9 +1131,9 @@ Generate the template files for a new tap.
 
 ### `test` [*`options`*] *`formula`*
 
-Run the test method provided by an installed formula. There is no standard
+Run the test method provided by an installed formula.
-output or return code, but generally it should notify the user if something is
+There is no standard output or return code, but generally it should notify the
-wrong with the installed formula.
+user if something is wrong with the installed formula.
 
 *Example:* `brew install jruby && brew test jruby`
 
@@ -1079,8 +1167,8 @@ Run Homebrew's unit and integration tests.
 
 ### `unpack` [*`options`*] *`formula`*
 
-Unpack the source files for *`formula`* into subdirectories of the current working
+Unpack the source files for *`formula`* into subdirectories of the current
-directory.
+working directory.
 
 * `--destdir`:
   Create subdirectories in the directory named by *`path`* instead.
@@ -1115,8 +1203,8 @@ Update versions for PyPI resource blocks in *`formula`*.
 
 ### `update-test` [*`options`*]
 
-Run a test of `brew update` with a new repository clone. If no options are
+Run a test of `brew update` with a new repository clone.
-passed, use `origin/master` as the start commit.
+If no options are passed, use `origin/master` as the start commit.
 
 * `--to-tag`:
   Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags.
@@ -1135,14 +1223,17 @@ Install and commit Homebrew's vendored gems.
 
 These options are applicable across multiple subcommands.
 
+* `-d`, `--debug`:
+  Display any debugging information.
+
 * `-q`, `--quiet`:
   Suppress any warnings.
 
 * `-v`, `--verbose`:
   Make some output more verbose.
 
-* `-d`, `--debug`:
+* `-h`, `--help`:
-  Display any debugging information.
+  Show this message.
 
 ## OFFICIAL EXTERNAL COMMANDS
 
@@ -1154,56 +1245,37 @@ Install macOS applications distributed as binaries. See `brew-cask`(1).
 
 ### `bundle` [*`subcommand`*]
 
-Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store
+Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store and Whalebrew.
-and Whalebrew.
 
 `brew bundle` [`install`]:
-    Install and upgrade (by default) all dependencies from the `Brewfile`.
+Install and upgrade (by default) all dependencies from the `Brewfile`.
 
-You can skip the installation of dependencies by adding space-separated values
+You can skip the installation of dependencies by adding space-separated values to one or more of the following environment variables: `HOMEBREW_BUNDLE_BREW_SKIP`, `HOMEBREW_BUNDLE_CASK_SKIP`, `HOMEBREW_BUNDLE_MAS_SKIP`, `HOMEBREW_BUNDLE_WHALEBREW_SKIP`, `HOMEBREW_BUNDLE_TAP_SKIP`
-to one or more of the following environment variables:
-`HOMEBREW_BUNDLE_BREW_SKIP`, `HOMEBREW_BUNDLE_CASK_SKIP`,
-`HOMEBREW_BUNDLE_MAS_SKIP`, `HOMEBREW_BUNDLE_WHALEBREW_SKIP`,
-`HOMEBREW_BUNDLE_TAP_SKIP`
 
-`brew bundle` will output a `Brewfile.lock.json` in the same directory as the
+`brew bundle` will output a `Brewfile.lock.json` in the same directory as the `Brewfile` if all dependencies are installed successfully. This contains dependency and system status information which can be useful in debugging `brew bundle` failures and replicating a "last known good build" state. You can opt-out of this behaviour by setting the `HOMEBREW_BUNDLE_NO_LOCK` environment variable or passing the `--no-lock` option. You may wish to check this file into the same version control system as your `Brewfile` (or ensure your version control system ignores it if you'd prefer to rely on debugging information from a local machine).
-`Brewfile` if all dependencies are installed successfully. This contains
-dependency and system status information which can be useful in debugging `brew
-bundle` failures and replicating a "last known good build" state. You can
-opt-out of this behaviour by setting the `HOMEBREW_BUNDLE_NO_LOCK` environment
-variable or passing the `--no-lock` option. You may wish to check this file into
-the same version control system as your `Brewfile` (or ensure your version
-control system ignores it if you'd prefer to rely on debugging information from
-a local machine).
 
 `brew bundle dump`:
-    Write all installed casks/formulae/images/taps into a `Brewfile`.
+Write all installed casks/formulae/images/taps into a `Brewfile`.
 
 `brew bundle cleanup`:
-    Uninstall all dependencies not listed from the `Brewfile`.
+Uninstall all dependencies not listed from the `Brewfile`.
 
-This workflow is useful for maintainers or testers who regularly install lots of
+This workflow is useful for maintainers or testers who regularly install lots of formulae.
-formulae.
 
 `brew bundle check`:
-    Check if all dependencies are installed from the `Brewfile` .
+Check if all dependencies are installed from the `Brewfile` .
 
-This provides a successful exit code if everything is up-to-date, making it
+This provides a successful exit code if everything is up-to-date, making it useful for scripting.
-useful for scripting.
 
 `brew bundle list`:
-    List all dependencies present in a `Brewfile`.
+List all dependencies present in a `Brewfile`.
 
 By default, only Homebrew dependencies are listed.
 
 `brew bundle exec` *`command`*:
-    Run an external command in an isolated build environment based on the
+Run an external command in an isolated build environment based on the `Brewfile` dependencies.
-`Brewfile` dependencies.
 
-This sanitized build environment ignores unrequested dependencies, which makes
+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 find keg-only dependencies like `openssl`, `icu4c`, etc.
-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 find keg-only dependencies like `openssl`, `icu4c`, etc.
 
 * `--file`:
   Read the `Brewfile` from this location. Use `--file=-` to pipe to stdin/stdout.
@@ -1244,41 +1316,31 @@ If `sudo` is passed, operate on `/Library/LaunchDaemons` (started at boot).
 Otherwise, operate on `~/Library/LaunchAgents` (started at login).
 
 [`sudo`] `brew services` [`list`]:
-    List all managed services for the current user (or root).
+List all managed services for the current user (or root).
 
 [`sudo`] `brew services run` (*`formula`*|`--all`):
-    Run the service *`formula`* without registering to launch at login (or boot).
+Run the service *`formula`* without registering to launch at login (or boot).
 
 [`sudo`] `brew services start` (*`formula`*|`--all`):
-    Start the service *`formula`* immediately and register it to launch at login
+Start the service *`formula`* immediately and register it to launch at login (or boot).
-(or boot).
 
 [`sudo`] `brew services stop` (*`formula`*|`--all`):
-    Stop the service *`formula`* immediately and unregister it from launching at
+Stop the service *`formula`* immediately and unregister it from launching at login (or boot).
-login (or boot).
 
 [`sudo`] `brew services restart` (*`formula`*|`--all`):
-    Stop (if necessary) and start the service *`formula`* immediately and register
+Stop (if necessary) and start the service *`formula`* immediately and register it to launch at login (or boot).
-it to launch at login (or boot).
 
 [`sudo`] `brew services cleanup`:
-    Remove all unused services.
+Remove all unused services.
 
 * `--all`:
   Run *`subcommand`* on all services.
 
 ### `test-bot` [*`options`*] [*`formula`*]:
 
-Tests the full lifecycle of a Homebrew change to a tap (Git repository). For
+Tests the full lifecycle of a Homebrew change to a tap (Git repository). For example, for a GitHub Actions pull request that changes a formula `brew test-bot` will ensure the system is cleaned and setup to test the formula, install the formula, run various tests and checks on it, bottle (package) the binaries and test formulae that depend on it to ensure they aren't broken by these changes.
-example, for a GitHub Actions pull request that changes a formula `brew
-test-bot` will ensure the system is cleaned and setup to test the formula,
-install the formula, run various tests and checks on it, bottle (package) the
-binaries and test formulae that depend on it to ensure they aren't broken by
-these changes.
 
-Only supports GitHub Actions as a CI provider. This is because Homebrew uses
+Only supports GitHub Actions as a CI provider. This is because Homebrew uses GitHub Actions and it's freely available for public and private use with macOS and Linux workers.
-GitHub Actions and it's freely available for public and private use with macOS
-and Linux workers.
 
 * `--dry-run`:
   print what would be done rather than doing it.
@@ -1353,6 +1415,12 @@ can take several different forms:
     Homebrew can install formulae from a local path. It can point to either a
     formula file or a bottle.
 
+## SPECIFYING CASKS
+
+Many Homebrew Cask commands accept one or more *`cask`* arguments. These can be
+specified the same way as the *`formula`* arguments described in
+`SPECIFYING FORMULAE` above.
+
 ## ENVIRONMENT
 
 Note that environment variables must have a value set to be detected. For example, run
@@ -1407,7 +1475,10 @@ Note that environment variables must have a value set to be detected. For exampl
     *Default:* macOS: `$HOME/Library/Caches/Homebrew`, Linux: `$XDG_CACHE_HOME/Homebrew` or `$HOME/.cache/Homebrew`.
 
   * `HOMEBREW_CASK_OPTS`:
-    Options which should be used for all `cask` commands.
+    Options which should be used for all `cask` commands. All `--*dir` options, `--language`, `--require-sha`, `--no-quarantine` and `--no-binaries` are supported.
+For example, you might add something like the following to your ~/.profile, ~/.bash_profile, or ~/.zshenv:
+
+`export HOMEBREW_CASK_OPTS='--appdir=~/Applications --fontdir=/Library/Fonts'`
 
   * `HOMEBREW_CLEANUP_MAX_AGE_DAYS`:
     Cleanup all cached files older than this many days.
@@ -1579,6 +1650,9 @@ Note that environment variables must have a value set to be detected. For exampl
   * `no_proxy`:
     A comma-separated list of hostnames and domain names excluded from proxying by `curl`(1), `git`(1) and `svn`(1) when downloading through Homebrew.
 
+  * `SUDO_ASKPASS`:
+    When this variable is set, the `-A` option is passed when calling `sudo`(8)
+
 ## USING HOMEBREW BEHIND A PROXY
 
 Set the `http_proxy`, `https_proxy`, `all_proxy`, `ftp_proxy` and/or `no_proxy`
@@ -1626,6 +1700,9 @@ See our issues on GitHub:
   * **Homebrew/homebrew-core**:
     <https://github.com/Homebrew/homebrew-core/issues>
 
+  * **Homebrew/homebrew-cask**:
+    <https://github.com/Homebrew/homebrew-cask/issues>
+
 [SYNOPSIS]: #SYNOPSIS "SYNOPSIS"
 [DESCRIPTION]: #DESCRIPTION "DESCRIPTION"
 [ESSENTIAL COMMANDS]: #ESSENTIAL-COMMANDS "ESSENTIAL COMMANDS"
@@ -1635,6 +1712,7 @@ See our issues on GitHub:
 [OFFICIAL EXTERNAL COMMANDS]: #OFFICIAL-EXTERNAL-COMMANDS "OFFICIAL EXTERNAL COMMANDS"
 [CUSTOM EXTERNAL COMMANDS]: #CUSTOM-EXTERNAL-COMMANDS "CUSTOM EXTERNAL COMMANDS"
 [SPECIFYING FORMULAE]: #SPECIFYING-FORMULAE "SPECIFYING FORMULAE"
+[SPECIFYING CASKS]: #SPECIFYING-CASKS "SPECIFYING CASKS"
 [ENVIRONMENT]: #ENVIRONMENT "ENVIRONMENT"
 [USING HOMEBREW BEHIND A PROXY]: #USING-HOMEBREW-BEHIND-A-PROXY "USING HOMEBREW BEHIND A PROXY"
 [SEE ALSO]: #SEE-ALSO "SEE ALSO"

manpages/brew-cask.1

@@ -1,316 +0,0 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "BREW\-CASK" "1" "August 2020" "Homebrew" "brew-cask"
-.
-.SH "NAME"
-\fBbrew\-cask\fR \- a friendly binary installer for macOS
-.
-.SH "SYNOPSIS"
-\fBbrew cask\fR command [options] [ \fItoken\fR \.\.\. ]
-.
-.SH "DESCRIPTION"
-Homebrew Cask is a tool for installing precompiled macOS binaries (such as Applications) from the command line\. The user is never required to use the graphical user interface\.
-.
-.SH "FREQUENTLY USED COMMANDS"
-.
-.TP
-\fBinstall\fR [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha] [\-\-no\-quarantine] [\-\-language=\fIiso\-language\fR[,\fIiso\-language\fR \.\.\. ]] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Install Cask identified by \fItoken\fR\.
-.
-.TP
-\fBuninstall\fR [\-\-force] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Uninstall Cask identified by \fItoken\fR\.
-.
-.SH "COMMANDS"
-.
-.TP
-\fB\-\-cache\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
-Display the file used to cache the Cask identified by \fItoken\fR\.
-.
-.TP
-\fBaudit\fR [\-\-language=\fIiso\-language\fR[,\fIiso\-language\fR \.\.\. ]] [ \fItoken\fR \.\.\. ]
-Check the given Casks for installability\. If no tokens are given on the command line, all Casks are audited\.
-.
-.TP
-\fBcat\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
-Dump the given Cask definition file to the standard output\.
-.
-.TP
-\fBcreate\fR \fItoken\fR
-Generate a Cask definition file for the Cask identified by \fItoken\fR and open a template for it in your favorite editor\.
-.
-.TP
-\fBdoctor\fR or \fBdr\fR
-Check for configuration issues\. Can be useful to upload as a gist for developers along with a bug report\.
-.
-.TP
-\fBedit\fR \fItoken\fR
-Open the given Cask definition file for editing\.
-.
-.TP
-\fBfetch\fR [\-\-force] [\-\-no\-quarantine] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Download remote application files for the given Cask to the local cache\. With \fB\-\-force\fR, force re\-download even if the files are already cached\. \fB\-\-no\-quarantine\fR will prevent Gatekeeper from enforcing its security restrictions on the Cask\.
-.
-.TP
-\fBhome\fR or \fBhomepage\fR [ \fItoken\fR \.\.\. ]
-Display the homepage associated with a given Cask in a browser\.
-.
-.IP
-With no arguments, display the project page \fIhttps://brew\.sh/\fR\.
-.
-.TP
-\fBinfo\fR or \fBabv\fR \fItoken\fR [ \fItoken\fR \.\.\. ]
-Display information about the given Cask\.
-.
-.TP
-\fBinstall\fR [\-\-force] [\-\-skip\-cask\-deps] [\-\-require\-sha] [\-\-no\-quarantine] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Install the given Cask\. With \fB\-\-force\fR, re\-install even if the Cask appears to be already present\. With \fB\-\-skip\-cask\-deps\fR, skip any Cask dependencies\. \fB\-\-require\-sha\fR will abort installation if the Cask does not have a checksum defined\. \fB\-\-no\-quarantine\fR will prevent Gatekeeper from enforcing its security restrictions on the Cask\.
-.
-.IP
-\fItoken\fR is usually the ID of a Cask, but see \fIOTHER WAYS TO SPECIFY A CASK\fR for variations\.
-.
-.TP
-\fBlist\fR or \fBls\fR [\-1] [\-\-versions] [ \fItoken\fR \.\.\. ]
-Without any arguments, list all installed Casks\. With \fB\-1\fR, always format the output in a single column\. With \fB\-\-versions\fR, show all installed versions\.
-.
-.IP
-If \fItoken\fR is given, summarize the staged files associated with the given Cask\.
-.
-.TP
-\fBoutdated\fR [\-\-greedy] [\-\-verbose|\-\-quiet] [ \fItoken\fR \.\.\. ]
-Without token arguments, display all the installed Casks that have newer versions available in the tap; otherwise check only the tokens given in the command line\. If \fB\-\-greedy\fR is given then also include in the output the Casks having \fBauto_updates true\fR or \fBversion :latest\fR\. Otherwise they are skipped because there is no reliable way to know when updates are available for them\.
-.
-.br
-\fB\-\-verbose\fR forces the display of the outdated and latest version\.
-.
-.br
-\fB\-\-quiet\fR suppresses the display of versions\.
-.
-.TP
-\fBreinstall\fR [\-\-no\-quarantine] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Reinstall the given Cask\.
-.
-.TP
-\fBstyle\fR [\-\-fix] [ \fItoken\fR \.\.\. ]
-Check the given Casks for correct style using RuboCop (with custom Cask cops)\. If no tokens are given on the command line, all Casks are checked\. With \fB\-\-fix\fR, auto\-correct any style errors if possible\.
-.
-.TP
-\fBuninstall\fR or \fBrm\fR or \fBremove\fR [\-\-force] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Uninstall the given Cask\. With \fB\-\-force\fR, uninstall even if the Cask does not appear to be present\.
-.
-.TP
-\fBupgrade\fR [\-\-force] [\-\-greedy] [\-\-dry\-run] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Without token arguments, upgrade all the installed Casks that have newer versions available in the tap; otherwise update the tokens given in the command line\. If \fB\-\-greedy\fR is given then also upgrade the Casks having \fBauto_updates true\fR or \fBversion :latest\fR\.
-.
-.IP
-If \fB\-\-dry\-run\fR is given, show what would be upgraded, but do not actually upgrade anything\.
-.
-.TP
-\fBzap\fR [\-\-force] \fItoken\fR [ \fItoken\fR \.\.\. ]
-Unconditionally remove \fIall\fR files associated with the given Cask\. With \fB\-\-force\fR, zap even if the Cask does not appear to be currently installed\.
-.
-.IP
-Implicitly performs all actions associated with \fBuninstall\fR\.
-.
-.IP
-Removes all staged versions of the Cask distribution found under \fB<Caskroom_path>/\fR\fItoken\fR\.
-.
-.IP
-If the Cask definition contains a \fBzap\fR stanza, performs additional \fBzap\fR actions as defined there, such as removing local preference files\. \fBzap\fR actions are variable, depending on the level of detail defined by the Cask author\.
-.
-.IP
-\fB\fBzap\fR may remove files which are shared between applications\.\fR
-.
-.SH "INTERNAL COMMANDS"
-.
-.TP
-\fB_stanza\fR \fIstanza_name\fR [ \-\-table | \-\-yaml | \-\-inspect | \-\-quiet ] [ \fItoken\fR \.\.\. ]
-Given a \fIstanza_name\fR and a \fItoken\fR, returns the current stanza for a given Cask\. If no \fItoken\fR is given, then data for all Casks is returned\.
-.
-.SH "OPTIONS"
-To make these options persistent, see the \fIENVIRONMENT\fR section, below\.
-.
-.P
-Some of these (such as \fB\-\-prefpanedir\fR) may be subject to removal in a future version\.
-.
-.TP
-\fB\-\-force\fR
-Force an install to proceed even when a previously\-existing install is detected\.
-.
-.TP
-\fB\-\-skip\-cask\-deps\fR
-Skip Cask dependencies when installing\.
-.
-.TP
-\fB\-\-require\-sha\fR
-Abort Cask installation if the Cask does not have a checksum defined\.
-.
-.TP
-\fB\-\-no\-quarantine\fR
-Prevent Gatekeeper from enforcing its security restrictions on the Cask\. This will let you run it straightaway\.
-.
-.TP
-\fB\-\-verbose\fR
-Give additional feedback during installation\.
-.
-.TP
-\fB\-\-appdir=<path>\fR
-Target location for Applications\. The default value is \fB/Applications\fR\.
-.
-.TP
-\fB\-\-language=<iso\-language>[,<iso\-language> \.\.\. ]]\fR
-Set language of the Cask to install\. The first matching language is used, otherwise the default language on the Cask\. The default value is the \fBlanguage of your system\fR\.
-.
-.TP
-\fB\-\-colorpickerdir=<path>\fR
-Target location for Color Pickers\. The default value is \fB~/Library/ColorPickers\fR\.
-.
-.TP
-\fB\-\-prefpanedir=<path>\fR
-Target location for Preference Panes\. The default value is \fB~/Library/PreferencePanes\fR\.
-.
-.TP
-\fB\-\-qlplugindir=<path>\fR
-Target location for QuickLook Plugins\. The default value is \fB~/Library/QuickLook\fR\.
-.
-.TP
-\fB\-\-dictionarydir=<path>\fR
-Target location for Dictionaries\. The default value is \fB~/Library/Dictionaries\fR\.
-.
-.TP
-\fB\-\-fontdir=<path>\fR
-Target location for Fonts\. The default value is \fB~/Library/Fonts\fR\.
-.
-.TP
-\fB\-\-servicedir=<path>\fR
-Target location for Services\. The default value is \fB~/Library/Services\fR\.
-.
-.TP
-\fB\-\-input_methoddir=<path>\fR
-Target location for Input Methods\. The default value is \fB~/Library/Input Methods\fR\.
-.
-.TP
-\fB\-\-internet_plugindir=<path>\fR
-Target location for Internet Plugins\. The default value is \fB~/Library/Internet Plug\-Ins\fR\.
-.
-.TP
-\fB\-\-audio_unit_plugindir=<path>\fR
-Target location for Audio Unit Plugins\. The default value is \fB~/Library/Audio/Plug\-Ins/Components\fR\.
-.
-.TP
-\fB\-\-vst_plugindir=<path>\fR
-Target location for VST Plugins\. The default value is \fB~/Library/Audio/Plug\-Ins/VST\fR\.
-.
-.TP
-\fB\-\-vst3_plugindir=<path>\fR
-Target location for VST3 Plugins\. The default value is \fB~/Library/Audio/Plug\-Ins/VST3\fR\.
-.
-.TP
-\fB\-\-screen_saverdir=<path>\fR
-Target location for Screen Savers\. The default value is \fB~/Library/Screen Savers\fR\.
-.
-.TP
-\fB\-\-no\-binaries\fR
-Do not link "helper" executables to \fB/usr/local/bin\fR\.
-.
-.TP
-\fB\-\-debug\fR
-Output debugging information of use to Cask authors and developers\.
-.
-.SH "INTERACTION WITH HOMEBREW"
-Homebrew Cask is implemented as a external command for Homebrew\. That means this project is entirely built upon the Homebrew infrastructure\. For example, upgrades to the Homebrew Cask tool are received through Homebrew:
-.
-.IP "" 4
-.
-.nf
-
-brew update; brew cask upgrade; brew cleanup
-.
-.fi
-.
-.IP "" 0
-.
-.P
-And updates to individual Cask definitions are received whenever you issue the Homebrew command:
-.
-.IP "" 4
-.
-.nf
-
-brew update
-.
-.fi
-.
-.IP "" 0
-.
-.SH "OTHER WAYS TO SPECIFY A CASK"
-Most Homebrew Cask commands can accept a Cask token as an argument\. As described above, the argument can take the form of:
-.
-.IP "\(bu" 4
-A simple token, e\.g\. \fBgoogle\-chrome\fR
-.
-.IP "" 0
-.
-.P
-Homebrew Cask also accepts three other forms in place of plain tokens:
-.
-.IP "\(bu" 4
-A fully\-qualified token which includes the Tap name, e\.g\. \fBhomebrew/cask\-fonts/font\-symbola\fR
-.
-.IP "\(bu" 4
-A fully\-qualified pathname to a Cask file, e\.g\. \fB/usr/local/Library/Taps/homebrew/homebrew\-cask/Casks/google\-chrome\.rb\fR
-.
-.IP "\(bu" 4
-A \fBcurl\fR\-retrievable URI to a Cask file, e\.g\. \fBhttps://raw\.githubusercontent\.com/Homebrew/homebrew\-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google\-chrome\.rb\fR
-.
-.IP "" 0
-.
-.SH "ENVIRONMENT"
-Homebrew Cask respects many of the environment variables used by the parent command \fBbrew\fR\. Please refer to the \fBbrew\fR(1) man page for more information\.
-.
-.P
-Environment variables specific to Homebrew Cask:
-.
-.TP
-\fBHOMEBREW_CASK_OPTS\fR
-This variable may contain any arguments normally used as options on the command\-line\. This is particularly useful to make options persistent\. For example, you might add to your ~/\.profile, ~/\.bash_profile, or ~/\.zshenv something like:
-.
-.IP "" 4
-.
-.nf
-
-       export HOMEBREW_CASK_OPTS=\'\-\-appdir=~/Applications \-\-fontdir=/Library/Fonts\'
-.
-.fi
-.
-.IP "" 0
-
-.
-.P
-Other environment variables:
-.
-.TP
-\fBSUDO_ASKPASS\fR
-When this variable is set, Homebrew Cask will call \fBsudo\fR(8) with the \fB\-A\fR option\.
-.
-.SH "SEE ALSO"
-The Homebrew home page: \fIhttps://brew\.sh/\fR
-.
-.P
-The Homebrew Cask GitHub page: \fIhttps://github\.com/Homebrew/homebrew\-cask\fR
-.
-.P
-\fBbrew\fR(1), \fBcurl\fR(1)
-.
-.SH "AUTHORS"
-Paul Hinze and Contributors\.
-.
-.P
-Man page format based on \fBbrew\.1\.md\fR from Homebrew\.
-.
-.SH "BUGS"
-We still have bugs \- and we are busy fixing them! If you have a problem, don\'t be shy about reporting it on our GitHub issues page \fIhttps://github\.com/Homebrew/homebrew\-cask/issues?state=open\fR\.
-.
-.P
-When reporting bugs, remember that Homebrew Cask is an separate repository within Homebrew\. Do your best to direct bug reports to the appropriate repository\. If your command\-line started with \fBbrew cask\fR, bring the bug to us first!

manpages/brew.1

@@ -53,6 +53,185 @@ Control Homebrew\'s anonymous aggregate user behaviour analytics\. Read more at
 \fBbrew analytics regenerate\-uuid\fR
     Regenerate the UUID used for Homebrew\'s analytics\.
 .
+.SS "\fBcask\fR \fIcommand\fR [\fIoptions\fR] [\fIcask\fR]"
+Homebrew Cask provides a friendly CLI workflow for the administration of macOS applications distributed as binaries\.
+.
+.P
+Commands:
+.
+.IP "\(bu" 4
+\fB\-\-cache\fR
+.
+.br
+Display the file used to cache a \fIcask\fR
+.
+.IP "\(bu" 4
+\fBaudit\fR
+.
+.br
+Check \fIcask\fR for Homebrew coding style violations
+.
+.IP "\(bu" 4
+\fBcat\fR
+.
+.br
+Dump raw source of a \fIcask\fR to the standard output
+.
+.IP "\(bu" 4
+\fBcreate\fR
+.
+.br
+Creates the given \fIcask\fR and opens it in an editor
+.
+.IP "\(bu" 4
+\fBdoctor\fR
+.
+.br
+Checks for configuration issues
+.
+.IP "\(bu" 4
+\fBedit\fR
+.
+.br
+Open the given \fIcask\fR for editing
+.
+.IP "\(bu" 4
+\fBfetch\fR
+.
+.br
+Downloads remote application files to local cache
+.
+.IP "\(bu" 4
+\fBhelp\fR
+.
+.br
+Print help for \fBcask\fR commands
+.
+.IP "\(bu" 4
+\fBhome\fR
+.
+.br
+Opens the homepage of the given \fIcask\fR
+.
+.IP "\(bu" 4
+\fBinfo\fR
+.
+.br
+Displays information about the given \fIcask\fR
+.
+.IP "\(bu" 4
+\fBinstall\fR
+.
+.br
+Installs the given \fIcask\fR
+.
+.IP "\(bu" 4
+\fBlist\fR
+.
+.br
+Lists installed casks or the casks provided in the arguments
+.
+.IP "\(bu" 4
+\fBoutdated\fR
+.
+.br
+List the outdated installed casks
+.
+.IP "\(bu" 4
+\fBreinstall\fR
+.
+.br
+Reinstalls the given \fIcask\fR
+.
+.IP "\(bu" 4
+\fBstyle\fR
+.
+.br
+Checks style of the given \fIcask\fR using RuboCop
+.
+.IP "\(bu" 4
+\fBuninstall\fR
+.
+.br
+Uninstalls the given \fIcask\fR
+.
+.IP "\(bu" 4
+\fBupgrade\fR
+.
+.br
+Upgrades all outdated casks or the specified casks
+.
+.IP "\(bu" 4
+\fBzap\fR
+.
+.br
+Zaps all files associated with the given \fIcask\fR
+.
+.IP "" 0
+.
+.P
+See also: \fBman brew\fR
+.
+.TP
+\fB\-\-appdir\fR
+Target location for Applications\. Default: \fB/Applications\fR
+.
+.TP
+\fB\-\-colorpickerdir\fR
+Target location for Color Pickers\. Default: \fB~/Library/ColorPickers\fR
+.
+.TP
+\fB\-\-prefpanedir\fR
+Target location for Preference Panes\. Default: \fB~/Library/PreferencePanes\fR
+.
+.TP
+\fB\-\-qlplugindir\fR
+Target location for QuickLook Plugins\. Default: \fB~/Library/QuickLook\fR
+.
+.TP
+\fB\-\-mdimporterdir\fR
+Target location for Spotlight Plugins\. Default: \fB~/Library/Spotlight\fR
+.
+.TP
+\fB\-\-dictionarydir\fR
+Target location for Dictionaries\. Default: \fB~/Library/Dictionaries\fR
+.
+.TP
+\fB\-\-fontdir\fR
+Target location for Fonts\. Default: \fB~/Library/Fonts\fR
+.
+.TP
+\fB\-\-servicedir\fR
+Target location for Services\. Default: \fB~/Library/Services\fR
+.
+.TP
+\fB\-\-input_methoddir\fR
+Target location for Input Methods\. Default: \fB~/Library/Input Methods\fR
+.
+.TP
+\fB\-\-internet_plugindir\fR
+Target location for Internet Plugins\. Default: \fB~/Library/Internet Plug\-Ins\fR
+.
+.TP
+\fB\-\-audio_unit_plugindir\fR
+Target location for Audio Unit Plugins\. Default: \fB~/Library/Audio/Plug\-Ins/Components\fR
+.
+.TP
+\fB\-\-vst_plugindir\fR
+Target location for VST Plugins\. Default: \fB~/Library/Audio/Plug\-Ins/VST\fR
+.
+.TP
+\fB\-\-vst3_plugindir\fR
+Target location for VST3 Plugins\. Default: \fB~/Library/Audio/Plug\-Ins/VST3\fR
+.
+.TP
+\fB\-\-screen_saverdir\fR
+Target location for Screen Savers\. Default: \fB~/Library/Screen Savers\fR
+.
+.TP
+\fB\-\-language\fR
+Set language of the Cask to install\. The first matching language is used, otherwise the default language on the Cask\. The default value is the \fBlanguage of your system\fR
+.
 .SS "\fBcleanup\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR]"
 Remove stale lock files and outdated downloads for all formulae and casks, and remove old versions of installed formulae\. If arguments are specified, only do this for the given formulae and casks\. Removes all downloads more than 120 days old\. This can be adjusted with \fBHOMEBREW_CLEANUP_MAX_AGE_DAYS\fR\.
 .
@@ -1491,6 +1670,10 @@ Install and commit Homebrew\'s vendored gems\.
 These options are applicable across multiple subcommands\.
 .
 .TP
+\fB\-d\fR, \fB\-\-debug\fR
+Display any debugging information\.
+.
+.TP
 \fB\-q\fR, \fB\-\-quiet\fR
 Suppress any warnings\.
 .
@@ -1499,8 +1682,8 @@ Suppress any warnings\.
 Make some output more verbose\.
 .
 .TP
-\fB\-d\fR, \fB\-\-debug\fR
+\fB\-h\fR, \fB\-\-help\fR
-Display any debugging information\.
+Show this message\.
 .
 .SH "OFFICIAL EXTERNAL COMMANDS"
 .
@@ -1765,6 +1948,9 @@ Sometimes a formula from a tapped repository may conflict with one in \fBhomebre
 An arbitrary file
 Homebrew can install formulae from a local path\. It can point to either a formula file or a bottle\.
 .
+.SH "SPECIFYING CASKS"
+Many Homebrew Cask commands accept one or more \fIcask\fR arguments\. These can be specified the same way as the \fIformula\fR arguments described in \fBSPECIFYING FORMULAE\fR above\.
+.
 .SH "ENVIRONMENT"
 Note that environment variables must have a value set to be detected\. For example, run \fBexport HOMEBREW_NO_INSECURE_REDIRECT=1\fR rather than just \fBexport HOMEBREW_NO_INSECURE_REDIRECT\fR\.
 .
@@ -1835,7 +2021,10 @@ Use the specified directory as the download cache\.
 .
 .TP
 \fBHOMEBREW_CASK_OPTS\fR
-Options which should be used for all \fBcask\fR commands\.
+Options which should be used for all \fBcask\fR commands\. All \fB\-\-*dir\fR options, \fB\-\-language\fR, \fB\-\-require\-sha\fR, \fB\-\-no\-quarantine\fR and \fB\-\-no\-binaries\fR are supported\. For example, you might add something like the following to your ~/\.profile, ~/\.bash_profile, or ~/\.zshenv:
+.
+.P
+\fBexport HOMEBREW_CASK_OPTS=\'\-\-appdir=~/Applications \-\-fontdir=/Library/Fonts\'\fR
 .
 .TP
 \fBHOMEBREW_CLEANUP_MAX_AGE_DAYS\fR
@@ -2069,6 +2258,10 @@ Use this HTTPS proxy for \fBcurl\fR(1), \fBgit\fR(1) and \fBsvn\fR(1) when downl
 \fBno_proxy\fR
 A comma\-separated list of hostnames and domain names excluded from proxying by \fBcurl\fR(1), \fBgit\fR(1) and \fBsvn\fR(1) when downloading through Homebrew\.
 .
+.TP
+\fBSUDO_ASKPASS\fR
+When this variable is set, the \fB\-A\fR option is passed when calling \fBsudo\fR(8)
+.
 .SH "USING HOMEBREW BEHIND A PROXY"
 Set the \fBhttp_proxy\fR, \fBhttps_proxy\fR, \fBall_proxy\fR, \fBftp_proxy\fR and/or \fBno_proxy\fR environment variables documented above\.
 .
@@ -2137,4 +2330,8 @@ See our issues on GitHub:
 .TP
 \fBHomebrew/homebrew\-core\fR
 \fIhttps://github\.com/Homebrew/homebrew\-core/issues\fR
+.
+.TP
+\fBHomebrew/homebrew\-cask\fR
+\fIhttps://github\.com/Homebrew/homebrew\-cask/issues\fR