unlinkapps: add --dry-run option

Add `--dry-run` option as is customary for destructive commands. Update
`bash` completion and man page accordingly. Also correct and update
documentation for both `brew linkapps` and `brew unlinkapps` in more
general terms.

2 files changed, 25 insertions, 14 deletions

diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
index 37519d67e..ed21c8ffb 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -214,14 +214,13 @@ be linked or which would be deleted by <code>brew link --overwrite</code>, but w
 actually link or delete any files.</p>
 
 <p>If <code>--force</code> is passed, Homebrew will allow keg-only formulae to be linked.</p></dd>
-<dt><code>linkapps</code> [<code>--local</code>] [<var>formulae</var>]</dt><dd><p>Find installed formulae that have compiled <code>.app</code>-style "application"
-packages for OS X, and symlink those apps into <code>/Applications</code>, allowing
-for easier access.</p>
+<dt><code>linkapps</code> [<code>--local</code>] [<var>formulae</var>]</dt><dd><p>Find installed formulae that provide <code>.app</code>-style OS X apps and symlink them
+into <code>/Applications</code>, allowing for easier access.</p>
 
-<p>If no <var>formulae</var> are provided, all of them will have their .apps symlinked.</p>
+<p>If no <var>formulae</var> are provided, all of them will have their apps symlinked.</p>
 
-<p>If provided, <code>--local</code> will move them into the user's <code>~/Applications</code>
-directory instead of the system directory. It may need to be created, first.</p></dd>
+<p>If provided, <code>--local</code> will symlink them into the user's <code>~/Applications</code>
+directory instead of the system directory.</p></dd>
 <dt><code>ls</code>, <code>list</code> [<code>--full-name</code>]</dt><dd><p>List all installed formulae. If <code>--full-name</code> is passed, print formulae with
 full-qualified names.</p></dd>
 <dt><code>ls</code>, <code>list</code> <code>--unbrewed</code></dt><dd><p>List all files in the Homebrew prefix not installed by Homebrew.</p></dd>
@@ -341,9 +340,15 @@ for temporarily disabling a formula:
 
 <p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all files which would
 be unlinked, but will not actually unlink or delete any files.</p></dd>
-<dt><code>unlinkapps</code> [<code>--local</code>] [<var>formulae</var>]</dt><dd><p>Removes links created by <code>brew linkapps</code>.</p>
+<dt><code>unlinkapps</code> [<code>--local</code>] [<code>--dry-run</code>] [<var>formulae</var>]</dt><dd><p>Remove symlinks created by <code>brew linkapps</code> from <code>/Applications</code>.</p>
 
-<p>If no <var>formulae</var> are provided, all linked app will be removed.</p></dd>
+<p>If no <var>formulae</var> are provided, all linked apps will be removed.</p>
+
+<p>If provided, <code>--local</code> will remove symlinks from the user's <code>~/Applications</code>
+directory instead of the system directory.</p>
+
+<p>If <code>--dry-run</code> or <code>-n</code> is passed, Homebrew will list all symlinks which
+would be removed, but will not actually delete any files.</p></dd>
 <dt><code>unpack</code> [<code>--git</code>|<code>--patch</code>] [<code>--destdir=</code><var>path</var>] <var>formulae</var></dt><dd><p>Unpack the source files for <var>formulae</var> into subdirectories of the current
 working directory. If <code>--destdir=</code><var>path</var> is given, the subdirectories will
 be created in the directory named by <code>&lt;path></code> instead.</p>
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index c9adf6bea..386fc39d1 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -286,13 +286,13 @@ If \fB\-\-force\fR is passed, Homebrew will allow keg\-only formulae to be linke
 .
 .TP
 \fBlinkapps\fR [\fB\-\-local\fR] [\fIformulae\fR]
-Find installed formulae that have compiled \fB\.app\fR\-style "application" packages for OS X, and symlink those apps into \fB/Applications\fR, allowing for easier access\.
+Find installed formulae that provide \fB\.app\fR\-style OS X apps and symlink them into \fB/Applications\fR, allowing for easier access\.
 .
 .IP
-If no \fIformulae\fR are provided, all of them will have their \.apps symlinked\.
+If no \fIformulae\fR are provided, all of them will have their apps symlinked\.
 .
 .IP
-If provided, \fB\-\-local\fR will move them into the user\'s \fB~/Applications\fR directory instead of the system directory\. It may need to be created, first\.
+If provided, \fB\-\-local\fR will symlink them into the user\'s \fB~/Applications\fR directory instead of the system directory\.
 .
 .TP
 \fBls\fR, \fBlist\fR [\fB\-\-full\-name\fR]
@@ -476,11 +476,17 @@ Remove symlinks for \fIformula\fR from the Homebrew prefix\. This can be useful
 If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which would be unlinked, but will not actually unlink or delete any files\.
 .
 .TP
-\fBunlinkapps\fR [\fB\-\-local\fR] [\fIformulae\fR]
-Removes links created by \fBbrew linkapps\fR\.
+\fBunlinkapps\fR [\fB\-\-local\fR] [\fB\-\-dry\-run\fR] [\fIformulae\fR]
+Remove symlinks created by \fBbrew linkapps\fR from \fB/Applications\fR\.
 .
 .IP
-If no \fIformulae\fR are provided, all linked app will be removed\.
+If no \fIformulae\fR are provided, all linked apps will be removed\.
+.
+.IP
+If provided, \fB\-\-local\fR will remove symlinks from the user\'s \fB~/Applications\fR directory instead of the system directory\.
+.
+.IP
+If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all symlinks which would be removed, but will not actually delete any files\.
 .
 .TP
 \fBunpack\fR [\fB\-\-git\fR|\fB\-\-patch\fR] [\fB\-\-destdir=\fR\fIpath\fR] \fIformulae\fR