brew upgrade: provides an option `--cleanup`

Closes Homebrew/homebrew#44305.

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

2 files changed, 16 insertions, 3 deletions

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