brew upgrade: provides an option `--cleanup`

Closes Homebrew/homebrew#44305.

Signed-off-by: Xu Cheng <xucheng@me.com>

4 files changed, 24 insertions, 5 deletions

diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
index e1b7dd0dc..e9d46fa92 100644
--- a/Library/Homebrew/cmd/upgrade.rb
+++ b/Library/Homebrew/cmd/upgrade.rb
@@ -1,5 +1,6 @@
 require "cmd/install"
 require "cmd/outdated"
+require "cmd/cleanup"
 
 module Homebrew
   def upgrade
@@ -41,7 +42,10 @@ module Homebrew
       puts pinned.map { |f| "#{f.full_name} #{f.pkg_version}" } * ", "
     end
 
-    outdated.each { |f| upgrade_formula(f) }
+    outdated.each do |f|
+      upgrade_formula(f)
+      cleanup_formula(f) if ARGV.include?("--cleanup") && f.installed?
+    end
   end
 
   def upgrade_pinned?
diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md
index 06df14196..4009178db 100644
--- a/Library/Homebrew/manpages/brew.1.md
+++ b/Library/Homebrew/manpages/brew.1.md
@@ -476,11 +476,13 @@ Note that these flags should only appear after a command.
 
     If `--rebase` is specified then `git pull --rebase` is used.
 
-  * `upgrade [install-options]` [<formulae>]:
+  * `upgrade [install-options] [--cleanup]` [<formulae>]:
     Upgrade outdated, unpinned brews.
 
     Options for the `install` command are also valid here.
 
+    If `--cleanup` is specified then remove previously installed <formula> version(s).
+
     If <formulae> are given, upgrade only the specified brews (but do so even
     if they are pinned; see `pin`, `unpin`).
 
diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
index 62d11cee8..dcee76bef 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -116,6 +116,14 @@ instead of the intersection.</p>
 <p>By default, <code>deps</code> shows dependencies for <var>formulae</var>. To skip the <code>:build</code>
 type dependencies, pass <code>--skip-build</code>. Similarly, pass <code>--skip-optional</code>
 to skip <code>:optional</code> dependencies.</p></li>
+<li><p><code>desc</code> <var>formula</var>:
+Display <var>formula</var>'s name and one-line description.</p></li>
+<li><p><code>desc [-s|-n|-d] &lt;pattern></code>:
+Search both name and description (<code>-s</code>), just the names (<code>-n</code>), or just  the
+descriptions (<code>-d</code>) for <code>&lt;pattern></code>. <code>&lt;pattern></code> is by default interpreted
+as a literal string; if flanked by slashes, it is instead interpreted as a
+regular expression. Formula descriptions are cached; the cache is created on
+the first search, making that search slower than subsequent ones.</p></li>
 <li><p><code>diy [--name=&lt;name>] [--version=&lt;version>]</code>:
 Automatically determine the installation prefix for non-Homebrew software.</p>
 
@@ -409,11 +417,13 @@ Fetch the newest version of Homebrew and all formulae from GitHub using
  <code>git</code>(1).</p>
 
 <p>If <code>--rebase</code> is specified then <code>git pull --rebase</code> is used.</p></li>
-<li><p><code>upgrade [install-options]</code> [<var>formulae</var>]:
+<li><p><code>upgrade [install-options] [--cleanup]</code> [<var>formulae</var>]:
 Upgrade outdated, unpinned brews.</p>
 
 <p>Options for the <code>install</code> command are also valid here.</p>
 
+<p>If <code>--cleanup</code> is specified then remove previously installed <var>formula</var> version(s).</p>
+
 <p>If <var>formulae</var> are given, upgrade only the specified brews (but do so even
 if they are pinned; see <code>pin</code>, <code>unpin</code>).</p></li>
 <li><p><code>uses [--installed] [--recursive] [--skip-build] [--skip-optional] [--devel|--HEAD]</code> <var>formulae</var>:
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index 0179f0ef4..639768398 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "September 2015" "Homebrew" "brew"
+.TH "BREW" "1" "October 2015" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for OS X
@@ -448,12 +448,15 @@ If \fB\-\-git\fR is passed, a Git repository will be initalized in the unpacked
 If \fB\-\-rebase\fR is specified then \fBgit pull \-\-rebase\fR is used\.
 .
 .IP "\(bu" 4
-\fBupgrade [install\-options]\fR [\fIformulae\fR]: Upgrade outdated, unpinned brews\.
+\fBupgrade [install\-options] [\-\-cleanup]\fR [\fIformulae\fR]: Upgrade outdated, unpinned brews\.
 .
 .IP
 Options for the \fBinstall\fR command are also valid here\.
 .
 .IP
+If \fB\-\-cleanup\fR is specified then remove previously installed \fIformula\fR version(s)\.
+.
+.IP
 If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see \fBpin\fR, \fBunpin\fR)\.
 .
 .IP "\(bu" 4