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.

5 files changed, 64 insertions, 28 deletions

diff --git a/Library/Homebrew/cmd/unlinkapps.rb b/Library/Homebrew/cmd/unlinkapps.rb
index 86a816050..68ee9d94e 100644
--- a/Library/Homebrew/cmd/unlinkapps.rb
+++ b/Library/Homebrew/cmd/unlinkapps.rb
@@ -4,13 +4,14 @@ module Homebrew
   def unlinkapps
     target_dir = linkapps_target(:local => ARGV.include?("--local"))
 
-    unlinkapps_from_dir(target_dir)
+    unlinkapps_from_dir(target_dir, :dry_run => ARGV.dry_run?)
   end
 
   private
 
-  def unlinkapps_from_dir(target_dir)
+  def unlinkapps_from_dir(target_dir, opts = {})
     return unless target_dir.directory?
+    dry_run = opts.fetch(:dry_run, false)
 
     apps = Pathname.glob("#{target_dir}/*.app").select do |app|
       unlinkapps_unlink?(app)
@@ -20,10 +21,16 @@ module Homebrew
 
     apps.each do |app|
       app.extend(ObserverPathnameExtension)
-      puts "Unlinking: #{app}"
-      app.unlink
+      if dry_run
+        puts "Would unlink: #{app}"
+      else
+        puts "Unlinking: #{app}"
+        app.unlink
+      end
     end
 
+    return if dry_run
+
     if ObserverPathnameExtension.total.zero?
       puts "No apps unlinked from #{target_dir}" if ARGV.verbose?
     else
diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md
index 47b0517ef..9e3c2cd07 100644
--- a/Library/Homebrew/manpages/brew.1.md
+++ b/Library/Homebrew/manpages/brew.1.md
@@ -267,14 +267,13 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--force` is passed, Homebrew will allow keg-only formulae to be linked.
 
   * `linkapps` [`--local`] [<formulae>]:
-    Find installed formulae that have compiled `.app`-style "application"
-    packages for OS X, and symlink those apps into `/Applications`, allowing
-    for easier access.
+    Find installed formulae that provide `.app`-style OS X apps and symlink them
+    into `/Applications`, allowing for easier access.
 
-    If no <formulae> are provided, all of them will have their .apps symlinked.
+    If no <formulae> are provided, all of them will have their apps symlinked.
 
-    If provided, `--local` will move them into the user's `~/Applications`
-    directory instead of the system directory. It may need to be created, first.
+    If provided, `--local` will symlink them into the user's `~/Applications`
+    directory instead of the system directory.
 
   * `ls`, `list` [`--full-name`]:
     List all installed formulae. If `--full-name` is passed, print formulae with
@@ -451,10 +450,16 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--dry-run` or `-n` is passed, Homebrew will list all files which would
     be unlinked, but will not actually unlink or delete any files.
 
-  * `unlinkapps` [`--local`] [<formulae>]:
-    Removes links created by `brew linkapps`.
+  * `unlinkapps` [`--local`] [`--dry-run`] [<formulae>]:
+    Remove symlinks created by `brew linkapps` from `/Applications`.
 
-    If no <formulae> are provided, all linked app will be removed.
+    If no <formulae> are provided, all linked apps will be removed.
+
+    If provided, `--local` will remove symlinks from the user's `~/Applications`
+    directory instead of the system directory.
+
+    If `--dry-run` or `-n` is passed, Homebrew will list all symlinks which
+    would be removed, but will not actually delete any files.
 
   * `unpack` [`--git`|`--patch`] [`--destdir=`<path>] <formulae>:
     Unpack the source files for <formulae> into subdirectories of the current
diff --git a/etc/bash_completion.d/brew b/etc/bash_completion.d/brew
index 6e3cc76c3..4f52205bc 100644
--- a/etc/bash_completion.d/brew
+++ b/etc/bash_completion.d/brew
@@ -487,6 +487,18 @@ _brew_uninstall ()
     __brew_complete_installed
 }
 
+_brew_unlinkapps ()
+{
+    local cur="${COMP_WORDS[COMP_CWORD]}"
+    case "$cur" in
+    --*)
+        __brewcomp "--dry-run --local"
+        return
+        ;;
+    esac
+    __brew_complete_installed
+}
+
 _brew_unpack ()
 {
     local cur="${COMP_WORDS[COMP_CWORD]}"
@@ -589,7 +601,7 @@ _brew ()
     install|instal|reinstall)   _brew_install ;;
     irb)                        _brew_irb ;;
     link|ln)                    _brew_link ;;
-    linkapps|unlinkapps)        _brew_linkapps ;;
+    linkapps)                   _brew_linkapps ;;
     list|ls)                    _brew_list ;;
     log)                        _brew_log ;;
     man)                        _brew_man ;;
@@ -609,6 +621,7 @@ _brew ()
     tap-unpin)                  _brew_tap_unpin ;;
     tests)                      _brew_tests ;;
     uninstall|remove|rm)        _brew_uninstall ;;
+    unlinkapps)                 _brew_unlinkapps ;;
     unpack)                     _brew_unpack ;;
     unpin)                      __brew_complete_formulae ;;
     untap|tap-info|tap-pin)     __brew_complete_tapped ;;
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