Merge pull request #9316 from EricFromCanada/list-cmd-options

list: refactor command options & move --unbrewed switch

Library/Homebrew/cli/parser.rb

@@ -139,13 +139,19 @@ module Homebrew
         instance_eval(&block) if block
       end
 
-      def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil, method: :on)
+      def switch(*names, description: nil, replacement: nil, env: nil, required_for: nil, depends_on: nil,
+                 method: :on)
         global_switch = names.first.is_a?(Symbol)
         return if global_switch
 
         description = option_to_description(*names) if description.nil?
-        process_option(*names, description)
+        if replacement.nil?
+          process_option(*names, description)
+        else
+          description += " (disabled#{"; replaced by #{replacement}" if replacement.present?})"
+        end
         @parser.public_send(method, *names, *wrap_option_desc(description)) do |value|
+          odisabled "the `#{names.first}` switch", replacement unless replacement.nil?
           value = if names.any? { |name| name.start_with?("--[no-]") }
             value
           else

Library/Homebrew/cmd/--prefix.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: false
 # frozen_string_literal: true
 
 require "cli/parser"
@@ -14,19 +14,28 @@ module Homebrew
       usage_banner <<~EOS
         `--prefix` [<formula>]
 
-        Display Homebrew's install path. *Default:* `/usr/local` on macOS and
+        Display Homebrew's install path. *Default:*
-        `/home/linuxbrew/.linuxbrew` on Linux.
+
+          - macOS Intel: `#{HOMEBREW_DEFAULT_PREFIX}`
+          - macOS ARM: `#{HOMEBREW_MACOS_ARM_DEFAULT_PREFIX}`
+          - Linux: `#{HOMEBREW_LINUX_DEFAULT_PREFIX}`
 
         If <formula> is provided, display the location in the Cellar where <formula>
         is or would be installed.
       EOS
+      switch "--unbrewed",
+             description: "List files in Homebrew's prefix not installed by Homebrew."
     end
   end
 
   def __prefix
     args = __prefix_args.parse
 
-    if args.no_named?
+    if args.unbrewed?
+      raise UsageError, "`--unbrewed` does not take a formula argument." unless args.no_named?
+
+      list_unbrewed
+    elsif args.no_named?
       puts HOMEBREW_PREFIX
     else
       puts args.named.to_resolved_formulae.map { |f|
@@ -34,4 +43,47 @@ module Homebrew
       }
     end
   end
+
+  UNBREWED_EXCLUDE_FILES = %w[.DS_Store].freeze
+  UNBREWED_EXCLUDE_PATHS = %w[
+    */.keepme
+    .github/*
+    bin/brew
+    completions/zsh/_brew
+    docs/*
+    lib/gdk-pixbuf-2.0/*
+    lib/gio/*
+    lib/node_modules/*
+    lib/python[23].[0-9]/*
+    lib/pypy/*
+    lib/pypy3/*
+    lib/ruby/gems/[12].*
+    lib/ruby/site_ruby/[12].*
+    lib/ruby/vendor_ruby/[12].*
+    manpages/brew.1
+    share/pypy/*
+    share/pypy3/*
+    share/info/dir
+    share/man/whatis
+  ].freeze
+
+  def list_unbrewed
+    dirs  = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s }
+    dirs -= %w[Library Cellar Caskroom .git]
+
+    # Exclude cache, logs, and repository, if they are located under the prefix.
+    [HOMEBREW_CACHE, HOMEBREW_LOGS, HOMEBREW_REPOSITORY].each do |dir|
+      dirs.delete dir.relative_path_from(HOMEBREW_PREFIX).to_s
+    end
+    dirs.delete "etc"
+    dirs.delete "var"
+
+    arguments = dirs.sort + %w[-type f (]
+    arguments.concat UNBREWED_EXCLUDE_FILES.flat_map { |f| %W[! -name #{f}] }
+    arguments.concat UNBREWED_EXCLUDE_PATHS.flat_map { |d| %W[! -path #{d}] }
+    arguments.concat %w[)]
+
+    cd HOMEBREW_PREFIX
+    safe_system "find", *arguments
+  end
 end

Library/Homebrew/cmd/list.rb

@@ -20,18 +20,19 @@ module Homebrew
         List all installed formulae and casks.
 
         If <formula> is provided, summarise the paths within its current keg.
+        If <cask> is provided, list its artifacts.
       EOS
       switch "--formula", "--formulae",
-             description: "List only formulae."
+             description: "List only formulae, or treat all named arguments as formulae."
       switch "--cask", "--casks",
-             description: "List only casks, or <cask> if provided."
+             description: "List only casks, or treat all named arguments as casks."
       switch "--unbrewed",
-             description: "List files in Homebrew's prefix not installed by Homebrew."
+             description: "List files in Homebrew's prefix not installed by Homebrew.",
+             replacement: "`brew --prefix --unbrewed`"
       switch "--full-name",
-             depends_on:  "--formula",
+             description: "Print formulae with fully-qualified names. Unless `--full-name`, `--versions` "\
-             description: "Print formulae with fully-qualified names. If `--full-name` is not "\
+                          "or `--pinned` are passed, other options (i.e. `-1`, `-l`, `-r` and `-t`) are "\
-                          "passed, other options (i.e. `-1`, `-l`, `-r` and `-t`) are passed to `ls`(1) "\
+                          "passed to `ls`(1) which produces the actual output."
-                          "which produces the actual output."
       switch "--versions",
              description: "Show the version number for installed formulae, or only the specified "\
                           "formulae if <formula> are provided."
@@ -39,7 +40,7 @@ module Homebrew
              depends_on:  "--versions",
              description: "Only show formulae with multiple versions installed."
       switch "--pinned",
-             description: "Show the versions of pinned formulae, or only the specified (pinned) "\
+             description: "List only pinned formulae, or only the specified (pinned) "\
                           "formulae if <formula> are provided. See also `pin`, `unpin`."
       # passed through to ls
       switch "-1",
@@ -53,14 +54,20 @@ module Homebrew
       switch "-t",
              description: "Sort formulae by time modified, listing most recently modified first."
 
-      ["-1", "-l", "-r", "-t"].each do |flag|
+      conflicts "--formula", "--cask"
-        conflicts "--full-name", flag
+      conflicts "--full-name", "--versions"
+      conflicts "--pinned", "--multiple"
+      conflicts "--cask", "--multiple"
+      ["--formula", "--cask", "--full-name", "--versions", "--pinned"].each do |flag|
         conflicts "--unbrewed", flag
-        conflicts "--pinned", flag
-        conflicts "--versions", flag
       end
-
+      ["-1", "-l", "-r", "-t"].each do |flag|
-      ["--unbrewed", "--formula", "-l", "-r", "-t"].each do |flag|
+        conflicts "--unbrewed", flag
+        conflicts "--versions", flag
+        conflicts "--pinned", flag
+      end
+      ["--pinned", "-l", "-r", "-t"].each do |flag|
+        conflicts "--full-name", flag
         conflicts "--cask", flag
       end
     end
@@ -69,46 +76,50 @@ module Homebrew
   def list
     args = list_args.parse
 
-    return list_casks(args: args) if args.cask?
-
-    if args.unbrewed?
-      raise UsageError, "`--unbrewed` does not take a formula/cask argument." unless args.no_named?
-
-      return list_unbrewed
-    end
-
     # Unbrewed uses the PREFIX, which will exist
     # Things below use the CELLAR, which doesn't until the first formula is installed.
     unless HOMEBREW_CELLAR.exist?
-      raise NoSuchKegError, args.named.first if args.named.present?
+      raise NoSuchKegError, args.named.first if args.named.present? && !args.cask?
 
       return
     end
 
-    if args.pinned? || args.versions?
+    if args.full_name?
+      unless args.cask?
+        formula_names = args.no_named? ? Formula.installed : args.named.to_resolved_formulae
+        full_formula_names = formula_names.map(&:full_name).sort(&tap_and_name_comparison)
+        full_formula_names = Formatter.columns(full_formula_names) unless args.public_send(:'1?')
+        puts full_formula_names unless full_formula_names.blank?
+      end
+      if args.cask? || (!args.formula? && args.no_named?)
+        cask_names = if args.no_named?
+          Cask::Caskroom.casks
+        else
+          args.named.to_formulae_and_casks(only: :cask, method: :resolve)
+        end
+        full_cask_names = cask_names.map(&:full_name).sort(&tap_and_name_comparison)
+        full_cask_names = Formatter.columns(full_cask_names) unless args.public_send(:'1?')
+        puts full_cask_names unless full_cask_names.blank?
+      end
+    elsif args.cask?
+      list_casks(args: args)
+    elsif args.pinned? || args.versions?
       filtered_list args: args
     elsif args.no_named?
-      if args.full_name?
+      ENV["CLICOLOR"] = nil
-        full_names = Formula.installed.map(&:full_name).sort(&tap_and_name_comparison)
-        return if full_names.empty?
 
-        puts Formatter.columns(full_names)
+      ls_args = []
+      ls_args << "-1" if args.public_send(:'1?')
+      ls_args << "-l" if args.l?
+      ls_args << "-r" if args.r?
+      ls_args << "-t" if args.t?
+
+      if !$stdout.tty? && !args.formula? && !args.cask?
+        odeprecated "`brew list` to only list formulae", "`brew list --formula`"
+        safe_system "ls", *ls_args, HOMEBREW_CELLAR
       else
-        ENV["CLICOLOR"] = nil
+        safe_system "ls", *ls_args, HOMEBREW_CELLAR unless args.cask?
-
+        list_casks(args: args) unless args.formula?
-        ls_args = []
-        ls_args << "-1" if args.public_send(:'1?')
-        ls_args << "-l" if args.l?
-        ls_args << "-r" if args.r?
-        ls_args << "-t" if args.t?
-
-        if !$stdout.tty? && !args.formula?
-          odeprecated "`brew list` to only list formulae", "`brew list --formula`"
-          safe_system "ls", *ls_args, HOMEBREW_CELLAR
-        else
-          safe_system "ls", *ls_args, HOMEBREW_CELLAR
-          list_casks(args: args) unless args.formula?
-        end
       end
     elsif args.verbose? || !$stdout.tty?
       system_command! "find", args: args.named.to_kegs.map(&:to_s) + %w[-not -type d -print], print_stdout: true
@@ -117,49 +128,6 @@ module Homebrew
     end
   end
 
-  UNBREWED_EXCLUDE_FILES = %w[.DS_Store].freeze
-  UNBREWED_EXCLUDE_PATHS = %w[
-    */.keepme
-    .github/*
-    bin/brew
-    completions/zsh/_brew
-    docs/*
-    lib/gdk-pixbuf-2.0/*
-    lib/gio/*
-    lib/node_modules/*
-    lib/python[23].[0-9]/*
-    lib/pypy/*
-    lib/pypy3/*
-    lib/ruby/gems/[12].*
-    lib/ruby/site_ruby/[12].*
-    lib/ruby/vendor_ruby/[12].*
-    manpages/brew.1
-    share/pypy/*
-    share/pypy3/*
-    share/info/dir
-    share/man/whatis
-  ].freeze
-
-  def list_unbrewed
-    dirs  = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s }
-    dirs -= %w[Library Cellar Caskroom .git]
-
-    # Exclude cache, logs, and repository, if they are located under the prefix.
-    [HOMEBREW_CACHE, HOMEBREW_LOGS, HOMEBREW_REPOSITORY].each do |dir|
-      dirs.delete dir.relative_path_from(HOMEBREW_PREFIX).to_s
-    end
-    dirs.delete "etc"
-    dirs.delete "var"
-
-    arguments = dirs.sort + %w[-type f (]
-    arguments.concat UNBREWED_EXCLUDE_FILES.flat_map { |f| %W[! -name #{f}] }
-    arguments.concat UNBREWED_EXCLUDE_PATHS.flat_map { |d| %W[! -path #{d}] }
-    arguments.concat %w[)]
-
-    cd HOMEBREW_PREFIX
-    safe_system "find", *arguments
-  end
-
   def filtered_list(args:)
     names = if args.no_named?
       Formula.racks

docs/Manpage.md

@@ -313,21 +313,20 @@ installations.
 List all installed formulae and casks.
 
 If *`formula`* is provided, summarise the paths within its current keg.
+If *`cask`* is provided, list its artifacts.
 
 * `--formula`:
-  List only formulae.
+  List only formulae, or treat all named arguments as formulae.
 * `--cask`:
-  List only casks, or *`cask`* if provided.
+  List only casks, or treat all named arguments as casks.
-* `--unbrewed`:
-  List files in Homebrew's prefix not installed by Homebrew.
 * `--full-name`:
-  Print formulae with fully-qualified names. If `--full-name` is not passed, other options (i.e. `-1`, `-l`, `-r` and `-t`) are passed to `ls`(1) which produces the actual output.
+  Print formulae with fully-qualified names. Unless `--full-name`, `--versions` or `--pinned` are passed, other options (i.e. `-1`, `-l`, `-r` and `-t`) are passed to `ls`(1) which produces the actual output.
 * `--versions`:
   Show the version number for installed formulae, or only the specified formulae if *`formula`* are provided.
 * `--multiple`:
   Only show formulae with multiple versions installed.
 * `--pinned`:
-  Show the versions of pinned formulae, or only the specified (pinned) formulae if *`formula`* are provided. See also `pin`, `unpin`.
+  List only pinned formulae, or only the specified (pinned) formulae if *`formula`* are provided. See also `pin`, `unpin`.
 * `-1`:
   Force output to be one entry per line. This is the default when output is not to a terminal.
 * `-l`:
@@ -696,12 +695,18 @@ the list is formatted for export to `bash`(1) unless `--plain` is passed.
 
 ### `--prefix` [*`formula`*]
 
-Display Homebrew's install path. *Default:* `/usr/local` on macOS and
+Display Homebrew's install path. *Default:*
-`/home/linuxbrew/.linuxbrew` on Linux.
+
+  - macOS Intel: `/usr/local`
+  - macOS ARM: `/opt/homebrew`
+  - Linux: `/home/linuxbrew/.linuxbrew`
 
 If *`formula`* is provided, display the location in the Cellar where *`formula`*
 is or would be installed.
 
+* `--unbrewed`:
+  List files in Homebrew's prefix not installed by Homebrew.
+
 ### `--repository`, `--repo` [*`user`*`/`*`repo`*]
 
 Display where Homebrew's `.git` directory is located.

manpages/brew.1

@@ -420,23 +420,19 @@ Allow keg\-only formulae to be linked\.
 List all installed formulae and casks\.
 .
 .P
-If \fIformula\fR is provided, summarise the paths within its current keg\.
+If \fIformula\fR is provided, summarise the paths within its current keg\. If \fIcask\fR is provided, list its artifacts\.
 .
 .TP
 \fB\-\-formula\fR
-List only formulae\.
+List only formulae, or treat all named arguments as formulae\.
 .
 .TP
 \fB\-\-cask\fR
-List only casks, or \fIcask\fR if provided\.
+List only casks, or treat all named arguments as casks\.
-.
-.TP
-\fB\-\-unbrewed\fR
-List files in Homebrew\'s prefix not installed by Homebrew\.
 .
 .TP
 \fB\-\-full\-name\fR
-Print formulae with fully\-qualified names\. If \fB\-\-full\-name\fR is not passed, other options (i\.e\. \fB\-1\fR, \fB\-l\fR, \fB\-r\fR and \fB\-t\fR) are passed to \fBls\fR(1) which produces the actual output\.
+Print formulae with fully\-qualified names\. Unless \fB\-\-full\-name\fR, \fB\-\-versions\fR or \fB\-\-pinned\fR are passed, other options (i\.e\. \fB\-1\fR, \fB\-l\fR, \fB\-r\fR and \fB\-t\fR) are passed to \fBls\fR(1) which produces the actual output\.
 .
 .TP
 \fB\-\-versions\fR
@@ -448,7 +444,7 @@ Only show formulae with multiple versions installed\.
 .
 .TP
 \fB\-\-pinned\fR
-Show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformula\fR are provided\. See also \fBpin\fR, \fBunpin\fR\.
+List only pinned formulae, or only the specified (pinned) formulae if \fIformula\fR are provided\. See also \fBpin\fR, \fBunpin\fR\.
 .
 .TP
 \fB\-1\fR
@@ -941,11 +937,26 @@ Generate a list of environment variables for the specified shell, or \fB\-\-shel
 Generate plain output even when piped\.
 .
 .SS "\fB\-\-prefix\fR [\fIformula\fR]"
-Display Homebrew\'s install path\. \fIDefault:\fR \fB/usr/local\fR on macOS and \fB/home/linuxbrew/\.linuxbrew\fR on Linux\.
+Display Homebrew\'s install path\. \fIDefault:\fR
+.
+.IP "\(bu" 4
+macOS Intel: \fB/usr/local\fR
+.
+.IP "\(bu" 4
+macOS ARM: \fB/opt/homebrew\fR
+.
+.IP "\(bu" 4
+Linux: \fB/home/linuxbrew/\.linuxbrew\fR
+.
+.IP "" 0
 .
 .P
 If \fIformula\fR is provided, display the location in the Cellar where \fIformula\fR is or would be installed\.
 .
+.TP
+\fB\-\-unbrewed\fR
+List files in Homebrew\'s prefix not installed by Homebrew\.
+.
 .SS "\fB\-\-repository\fR, \fB\-\-repo\fR [\fIuser\fR\fB/\fR\fIrepo\fR]"
 Display where Homebrew\'s \fB\.git\fR directory is located\.
 .