Merge pull request #4004 from MikeMcQuaid/usability

Address some usability issues.

Library/Homebrew/cmd/help.rb

@@ -1,7 +1,7 @@
 HOMEBREW_HELP = <<~EOS.freeze
   Example usage:
     brew search [TEXT|/REGEX/]
-    brew (info|home|options) [FORMULA...]
+    brew info [FORMULA...]
     brew install FORMULA...
     brew update
     brew upgrade [FORMULA...]
@@ -11,17 +11,17 @@ HOMEBREW_HELP = <<~EOS.freeze
   Troubleshooting:
     brew config
     brew doctor
-    brew install -vd FORMULA
+    brew install --verbose --debug FORMULA
 
-  Developers:
+  Contributing:
     brew create [URL [--no-fetch]]
     brew edit [FORMULA...]
-    https://docs.brew.sh/Formula-Cookbook
 
   Further help:
-    man brew
+    brew commands
     brew help [COMMAND]
-    brew home
+    man brew
+    https://docs.brew.sh
 EOS
 
 # NOTE Keep the lenth of vanilla --help less than 25 lines!

Library/Homebrew/cmd/install.rb

@@ -166,7 +166,8 @@ module Homebrew
             formulae << f
           else
             opoo <<~EOS
-              #{f.full_name} #{f.pkg_version} is already installed
+              #{f.full_name} #{f.pkg_version} is already installed and up-to-date
+              To reinstall #{f.pkg_version}, run `brew reinstall #{f.name}`
             EOS
           end
         elsif (ARGV.build_head? && new_head_installed) || prefix_installed
@@ -190,12 +191,17 @@ module Homebrew
             EOS
           elsif !f.linked? || f.keg_only?
             msg = <<~EOS
-              #{msg}, it's just not linked.
+              #{msg}, it's just not linked
               You can use `brew link #{f}` to link this version.
             EOS
           elsif ARGV.only_deps?
             msg = nil
             formulae << f
+          else
+            msg = <<~EOS
+              #{msg} and up-to-date
+              To reinstall #{f.pkg_version}, run `brew reinstall #{f.name}`
+            EOS
           end
           opoo msg if msg
         elsif !f.any_version_installed? && old_formula = f.old_installed_formulae.first

Library/Homebrew/cmd/switch.rb

@@ -1,5 +1,5 @@
-#:  * `switch` <name> <version>:
+#:  * `switch` <formula> <version>:
-#:    Symlink all of the specific <version> of <name>'s install to Homebrew prefix.
+#:    Symlink all of the specific <version> of <formula>'s install to Homebrew prefix.
 
 require "formula"
 require "keg"
@@ -9,14 +9,15 @@ module Homebrew
   module_function
 
   def switch
-    if ARGV.named.length != 2
+    name = ARGV.first
-      onoe "Usage: brew switch <name> <version>"
+
+    usage = "Usage: brew switch <formula> <version>"
+
+    unless name
+      onoe usage
       exit 1
     end
 
-    name = ARGV.shift
-    version = ARGV.shift
-
     rack = Formulary.to_rack(name)
 
     unless rack.directory?
@@ -24,13 +25,21 @@ module Homebrew
       exit 2
     end
 
-    # Does the target version exist?
+    versions = rack.subdirs
+                   .map { |d| Keg.new(d).version }
+                   .sort
+                   .join(", ")
+    version = ARGV[1]
+
+    if !version || ARGV.named.length > 2
+      onoe usage
+      puts "#{name} installed versions: #{versions}"
+      exit 1
+    end
+
     unless (rack/version).directory?
       onoe "#{name} does not have a version \"#{version}\" in the Cellar."
-
+      puts "#{name} installed versions: #{versions}"
-      versions = rack.subdirs.map { |d| Keg.new(d).version }.sort
-      puts "Versions available: #{versions.join(", ")}"
-
       exit 3
     end
 

Library/Homebrew/cmd/upgrade.rb

@@ -67,7 +67,14 @@ module Homebrew
       oh1 "No packages to upgrade"
     else
       oh1 "Upgrading #{Formatter.pluralize(formulae_to_install.length, "outdated package")}, with result:"
-      puts formulae_to_install.map { |f| "#{f.full_specified_name} #{f.pkg_version}" } * ", "
+      formulae_upgrades = formulae_to_install.map do |f|
+        if f.optlinked?
+          "#{f.full_specified_name} #{Keg.new(f.opt_prefix).version} -> #{f.pkg_version}"
+        else
+          "#{f.full_specified_name} #{f.pkg_version}"
+        end
+      end
+      puts formulae_upgrades.join(", ")
     end
 
     # Sort keg_only before non-keg_only formulae to avoid any needless conflicts

Library/Homebrew/test/cmd/switch_spec.rb

@@ -1,7 +1,7 @@
 describe "brew switch", :integration_test do
   it "allows switching between Formula versions" do
     expect { brew "switch" }
-      .to output(/Usage: brew switch <name> <version>/).to_stderr
+      .to output(/Usage: brew switch <formula> <version>/).to_stderr
       .and not_to_output.to_stdout
       .and be_a_failure
 
@@ -25,7 +25,7 @@ describe "brew switch", :integration_test do
       .and be_a_success
 
     expect { brew "switch", "testball", "0.3" }
-      .to output("Versions available: 0.1, 0.2\n").to_stdout
+      .to output("testball installed versions: 0.1, 0.2\n").to_stdout
       .and output(/testball does not have a version "0.3"/).to_stderr
       .and be_a_failure
   end

docs/Manpage.md

@@ -444,8 +444,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
     Exits with a non-zero status if any style violations are found.
 
-  * `switch` `name` `version`:
+  * `switch` `formula` `version`:
-    Symlink all of the specific `version` of `name`'s install to Homebrew prefix.
+    Symlink all of the specific `version` of `formula`'s install to Homebrew prefix.
 
   * `tap`:
     List all installed taps.

manpages/brew.1

@@ -455,8 +455,8 @@ Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the li
 Exits with a non\-zero status if any style violations are found\.
 .
 .TP
-\fBswitch\fR \fIname\fR \fIversion\fR
+\fBswitch\fR \fIformula\fR \fIversion\fR
-Symlink all of the specific \fIversion\fR of \fIname\fR\'s install to Homebrew prefix\.
+Symlink all of the specific \fIversion\fR of \fIformula\fR\'s install to Homebrew prefix\.
 .
 .TP
 \fBtap\fR