list: fix flag handling.

Fix `-1` and other flags so they're handled correctly with casks. Use
the "right" exceptions for declaring invalid combinations and change
their parent class so that `--help` is printed nicely too.

Fixes #9033

Author: MikeMcQuaid

Library/Homebrew/cli/parser.rb

@@ -506,7 +506,7 @@ def formulae(argv)
       end
     end
 
-    class OptionConstraintError < RuntimeError
+    class OptionConstraintError < UsageError
       def initialize(arg1, arg2, missing: false)
         message = if !missing
           "`#{arg1}` and `#{arg2}` should be passed together."
@@ -517,15 +517,15 @@ def initialize(arg1, arg2, missing: false)
       end
     end
 
-    class OptionConflictError < RuntimeError
+    class OptionConflictError < UsageError
       def initialize(args)
         args_list = args.map(&Formatter.public_method(:option))
                         .join(" and ")
         super "Options #{args_list} are mutually exclusive."
       end
     end
 
-    class InvalidConstraintError < RuntimeError
+    class InvalidConstraintError < UsageError
       def initialize(arg1, arg2)
         super "`#{arg1}` and `#{arg2}` cannot be mutually exclusive and mutually dependent simultaneously."
       end

Library/Homebrew/cmd/list.rb

@@ -18,38 +18,51 @@ def list_args
 
         If <formula> is provided, summarise the paths within its current keg.
       EOS
+      switch "--formula", "--formulae",
+             description: "List only formulae. `This is the default action on non TTY.`"
+      switch "--cask", "--casks",
+             description: "List only casks, or <cask> if provided."
+      switch "--unbrewed",
+             description: "List files in Homebrew's prefix not installed by Homebrew."
       switch "--full-name",
+             depends_on:  "--formula",
              description: "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."
-      switch "--unbrewed",
-             description: "List files in Homebrew's prefix not installed by Homebrew."
       switch "--versions",
+             depends_on:  "--formula",
              description: "Show the version number for installed formulae, or only the specified "\
                           "formulae if <formula> are provided."
       switch "--multiple",
              depends_on:  "--versions",
              description: "Only show formulae with multiple versions installed."
       switch "--pinned",
+             depends_on:  "--formula",
              description: "Show the versions of pinned formulae, or only the specified (pinned) "\
                           "formulae if <formula> are provided. See also `pin`, `unpin`."
-      switch "--formula", "--formulae",
-             description: "List only formulae. `This is the default action on non TTY.`"
-      switch "--cask", "--casks",
-             description: "List only casks, or <cask> if provided."
       # passed through to ls
       switch "-1",
              description: "Force output to be one entry per line. " \
                           "This is the default when output is not to a terminal."
       switch "-l",
-             description: "List in long format. If the output is to a terminal, "\
+             depends_on:  "--formula",
+             description: "List formulae in long format. If the output is to a terminal, "\
                           "a total sum for all the file sizes is printed before the long listing."
       switch "-r",
-             description: "Reverse the order of the sort to list the oldest entries first."
+             depends_on:  "--formula",
+             description: "Reverse the order of the formulae sort to list the oldest entries first."
       switch "-t",
-             description: "Sort by time modified, listing most recently modified first."
+             depends_on:  "--formula",
+             description: "Sort formulae by time modified, listing most recently modified first."
+
+      ["-1", "-l", "-r", "-t"].each do |flag|
+        conflicts "--full-name", flag
+        conflicts "--unbrewed", flag
+        conflicts "--pinned", flag
+        conflicts "--versions", flag
+      end
 
-      ["--formula", "--unbrewed", "--multiple", "--pinned", "-l", "-r", "-t"].each do |flag|
+      ["--unbrewed", "--formula", "-l", "-r", "-t"].each do |flag|
         conflicts "--cask", flag
       end
     end
@@ -104,6 +117,7 @@ def list
 
   UNBREWED_EXCLUDE_FILES = %w[.DS_Store].freeze
   UNBREWED_EXCLUDE_PATHS = %w[
+    */.keepme
     .github/*
     bin/brew
     completions/zsh/_brew
@@ -126,7 +140,7 @@ def list
 
   def list_unbrewed
     dirs  = HOMEBREW_PREFIX.subdirs.map { |dir| dir.basename.to_s }
-    dirs -= %w[Library Cellar .git]
+    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|

docs/Manpage.md

@@ -353,28 +353,28 @@ List all installed formulae or casks
 
 If *`formula`* is provided, summarise the paths within its current keg.
 
-* `--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.
+* `--formula`:
+  List only formulae. `This is the default action on non TTY.`
+* `--cask`:
+  List only casks, or *`cask`* if provided.
 * `--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.
 * `--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`.
-* `--formula`:
-  List only formulae. `This is the default action on non TTY.`
-* `--cask`:
-  List only casks, or *`cask`* if provided.
 * `-1`:
   Force output to be one entry per line. This is the default when output is not to a terminal.
 * `-l`:
-  List in long format. If the output is to a terminal, a total sum for all the file sizes is printed before the long listing.
+  List formulae in long format. If the output is to a terminal, a total sum for all the file sizes is printed before the long listing.
 * `-r`:
-  Reverse the order of the sort to list the oldest entries first.
+  Reverse the order of the formulae sort to list the oldest entries first.
 * `-t`:
-  Sort by time modified, listing most recently modified first.
+  Sort formulae by time modified, listing most recently modified first.
 
 ### `log` [*`options`*] [*`formula`*]
 

manpages/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "October 2020" "Homebrew" "brew"
+.TH "BREW" "1" "November 2020" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The Missing Package Manager for macOS
@@ -512,14 +512,22 @@ List all installed formulae or casks
 If \fIformula\fR is provided, summarise the paths within its current keg\.
 .
 .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\.
+\fB\-\-formula\fR
+List only formulae\. \fBThis is the default action on non TTY\.\fR
+.
+.TP
+\fB\-\-cask\fR
+List only casks, or \fIcask\fR if provided\.
 .
 .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\.
+.
+.TP
 \fB\-\-versions\fR
 Show the version number for installed formulae, or only the specified formulae if \fIformula\fR are provided\.
 .
@@ -532,28 +540,20 @@ Only show formulae with multiple versions installed\.
 Show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformula\fR are provided\. See also \fBpin\fR, \fBunpin\fR\.
 .
 .TP
-\fB\-\-formula\fR
-List only formulae\. \fBThis is the default action on non TTY\.\fR
-.
-.TP
-\fB\-\-cask\fR
-List only casks, or \fIcask\fR if provided\.
-.
-.TP
 \fB\-1\fR
 Force output to be one entry per line\. This is the default when output is not to a terminal\.
 .
 .TP
 \fB\-l\fR
-List in long format\. If the output is to a terminal, a total sum for all the file sizes is printed before the long listing\.
+List formulae in long format\. If the output is to a terminal, a total sum for all the file sizes is printed before the long listing\.
 .
 .TP
 \fB\-r\fR
-Reverse the order of the sort to list the oldest entries first\.
+Reverse the order of the formulae sort to list the oldest entries first\.
 .
 .TP
 \fB\-t\fR
-Sort by time modified, listing most recently modified first\.
+Sort formulae by time modified, listing most recently modified first\.
 .
 .SS "\fBlog\fR [\fIoptions\fR] [\fIformula\fR]"
 Show the \fBgit log\fR for \fIformula\fR, or show the log for the Homebrew repository if no formula is provided\.