brew ln --force is now brew ln --overwrite

* Renames --force to --overwrite, freeing up brew ln --force for #13349
* Changes --dry-run to preview linking by default, rather than
  overwriting. An overwrite dry-run can be simulated via both
  --dry-run --overwrite
* Adds some basic Keg tests

6 files changed, 119 insertions, 22 deletions

diff --git a/Library/Contributions/manpages/brew.1.md b/Library/Contributions/manpages/brew.1.md
index f87c8a96c..21839477f 100644
--- a/Library/Contributions/manpages/brew.1.md
+++ b/Library/Contributions/manpages/brew.1.md
@@ -185,17 +185,17 @@ For the full command list, see the COMMANDS section.
     If `--git` is passed, Homebrew will create a Git repository, useful for
     creating patches to the software.
 
-  * `ln`, `link [--force] [--dry-run]` <formula>:
+  * `ln`, `link [--overwrite] [--dry-run]` <formula>:
     Symlink all of <formula>'s installed files into the Homebrew prefix. This
     is done automatically when you install formula, but can be useful for DIY
     installations.
 
-    If `--force` is passed, Homebrew will delete files which already exist in
+    If `--overwrite` is passed, Homebrew will delete files which already exist in
     the prefix while linking.
 
     If `--dry-run` or `-n` is passed, Homebrew will list all files which would
-    be deleted by `brew link --force`, but will not actually link or delete
-    any files.
+    be linked or which would be deleted by `brew link --overwrite`, but will not
+    actually link or delete any files.
 
   * `ls, list [--unbrewed] [--versions]` [<formulae>]:
     Without any arguments, list all installed formulae.
diff --git a/Library/Homebrew/cmd/link.rb b/Library/Homebrew/cmd/link.rb
index 8e942cd91..66d8e9583 100644
--- a/Library/Homebrew/cmd/link.rb
+++ b/Library/Homebrew/cmd/link.rb
@@ -1,3 +1,5 @@
+require 'ostruct'
+
 module Homebrew extend self
 
   def link
@@ -7,10 +9,10 @@ module Homebrew extend self
       raise "Cowardly refusing to `sudo brew link'\n#{SUDO_BAD_ERRMSG}"
     end
 
-    if ARGV.force? then mode = :force
-    elsif ARGV.dry_run? then mode = :dryrun
-    else mode = nil
-    end
+    mode = OpenStruct.new
+
+    mode.overwrite = true if ARGV.include? '--overwrite'
+    mode.dry_run = true if ARGV.dry_run?
 
     ARGV.kegs.each do |keg|
       if keg.linked?
@@ -18,12 +20,18 @@ module Homebrew extend self
         next
       end
 
-      if mode == :dryrun
+      if mode.dry_run and mode.overwrite
         print "Would remove:\n" do
           keg.link(mode)
         end
 
         next
+      elsif mode.dry_run
+        print "Would link:\n" do
+          keg.link(mode)
+        end
+
+        next
       end
 
       print "Linking #{keg}... " do
diff --git a/Library/Homebrew/extend/pathname.rb b/Library/Homebrew/extend/pathname.rb
index bab1064d8..054e5b078 100644
--- a/Library/Homebrew/extend/pathname.rb
+++ b/Library/Homebrew/extend/pathname.rb
@@ -269,10 +269,10 @@ class Pathname
             Could not symlink file: #{src.expand_path}
             Target #{self} already exists. You may need to delete it.
             To force the link and delete this file, do:
-              brew link -f formula_name
+              brew link --overwrite formula_name
 
             To list all files that would be deleted:
-              brew link -n formula_name
+              brew link --overwrite --dry-run formula_name
             EOS
         elsif !dirname.writable_real?
           raise <<-EOS.undent
diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index 04196099a..ba394266c 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -83,7 +83,7 @@ class Keg < Pathname
     Pathname.new(self.to_s).basename
   end
 
-  def link mode=nil
+  def link mode=OpenStruct.new
     raise "Cannot link #{fname}\nAnother version is already linked: #{linked_keg_record.realpath}" if linked_keg_record.directory?
 
     $n=0
@@ -131,9 +131,9 @@ class Keg < Pathname
       end
     end
 
-    linked_keg_record.make_relative_symlink(self) unless mode == :dryrun
+    linked_keg_record.make_relative_symlink(self) unless mode.dry_run
 
-    optlink unless mode == :dryrun
+    optlink unless mode.dry_run
 
     return $n + $d
   rescue Exception
@@ -170,21 +170,25 @@ protected
     puts "Won't resolve conflicts for symlink #{dst} as it doesn't resolve into the Cellar" if ARGV.verbose?
   end
 
-  def make_relative_symlink dst, src, mode=nil
+  def make_relative_symlink dst, src, mode=OpenStruct.new
     if dst.exist? and dst.realpath == src.realpath
       puts "Skipping; already exists: #{dst}" if ARGV.verbose?
     # cf. git-clean -n: list files to delete, don't really link or delete
-    elsif mode == :dryrun
+    elsif mode.dry_run and mode.overwrite
       puts dst if dst.exist?
       return
+    # list all link targets
+    elsif mode.dry_run
+      puts dst
+      return
     else
-      dst.delete if mode == :force && dst.exist?
+      dst.delete if mode.overwrite && dst.exist?
       dst.make_relative_symlink src
     end
   end
 
   # symlinks the contents of self+foo recursively into /usr/local/foo
-  def link_dir foo, mode=nil
+  def link_dir foo, mode=OpenStruct.new
     root = self+foo
     return unless root.exist?
 
diff --git a/Library/Homebrew/test/test_keg.rb b/Library/Homebrew/test/test_keg.rb
new file mode 100644
index 000000000..c9e5990a0
--- /dev/null
+++ b/Library/Homebrew/test/test_keg.rb
@@ -0,0 +1,85 @@
+require 'testing_env'
+require 'test/testball'
+require 'keg'
+require 'stringio'
+
+class LinkTests < Test::Unit::TestCase
+  def setup
+    @formula = TestBall.new
+    shutup do
+      @formula.brew { @formula.install }
+    end
+    @keg = Keg.for @formula.prefix
+    @keg.unlink
+
+    @old_stdout = $stdout
+    $stdout = StringIO.new
+
+    FileUtils.mkpath HOMEBREW_PREFIX/"bin"
+  end
+
+  def test_linking_keg
+    assert_equal @keg.link, 3
+  end
+
+  def test_unlinking_keg
+    @keg.link
+    assert_equal @keg.unlink, 3
+  end
+
+  def test_link_dry_run
+    mode = OpenStruct.new
+    mode.dry_run = true
+
+    assert_equal @keg.link(mode), 0
+    assert !@keg.linked?
+
+    assert_equal $stdout.string, <<-EOS.undent
+      /private/tmp/testbrew/prefix/bin/hiworld
+      /private/tmp/testbrew/prefix/bin/helloworld
+      /private/tmp/testbrew/prefix/bin/goodbye_cruel_world
+      EOS
+  end
+
+  def test_linking_fails_when_already_linked
+    @keg.link
+    assert_raise RuntimeError, "Cannot link testball" do
+      @keg.link
+    end
+  end
+
+  def test_linking_fails_when_files_exist
+    FileUtils.touch HOMEBREW_PREFIX/"bin/helloworld"
+    assert_raise RuntimeError do
+      @keg.link
+    end
+  end
+
+  def test_link_overwrite
+    FileUtils.touch HOMEBREW_PREFIX/"bin/helloworld"
+    mode = OpenStruct.new
+    mode.overwrite = true
+    assert_equal @keg.link(mode), 3
+  end
+
+  def test_link_overwrite_dryrun
+    FileUtils.touch HOMEBREW_PREFIX/"bin/helloworld"
+    mode = OpenStruct.new
+    mode.overwrite = true
+    mode.dry_run = true
+
+    assert_equal @keg.link(mode), 0
+    assert !@keg.linked?
+
+    assert_equal $stdout.string, "/private/tmp/testbrew/prefix/bin/helloworld\n"
+  end
+
+  def teardown
+    @keg.unlink
+    @keg.rmtree
+
+    $stdout = @old_stdout
+
+    FileUtils.rmtree HOMEBREW_PREFIX/"bin"
+  end
+end
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index 2208043cb..4113a999b 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" "August 2012" "Homebrew" "brew"
+.TH "BREW" "1" "October 2012" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for OS X
@@ -208,14 +208,14 @@ Download and patch \fIformula\fR, then open a shell\. This allows the user to ru
 If \fB\-\-git\fR is passed, Homebrew will create a Git repository, useful for creating patches to the software\.
 .
 .TP
-\fBln\fR, \fBlink [\-\-force] [\-\-dry\-run]\fR \fIformula\fR
+\fBln\fR, \fBlink [\-\-overwrite] [\-\-dry\-run]\fR \fIformula\fR
 Symlink all of \fIformula\fR\'s installed files into the Homebrew prefix\. This is done automatically when you install formula, but can be useful for DIY installations\.
 .
 .IP
-If \fB\-\-force\fR is passed, Homebrew will delete files which already exist in the prefix while linking\.
+If \fB\-\-overwrite\fR is passed, Homebrew will delete files which already exist in the prefix while linking\.
 .
 .IP
-If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which would be deleted by \fBbrew link \-\-force\fR, but will not actually link or delete any files\.
+If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which would be linked or which would be deleted by \fBbrew link \-\-overwrite\fR, but will not actually link or delete any files\.
 .
 .TP
 \fBls, list [\-\-unbrewed] [\-\-versions]\fR [\fIformulae\fR]