Remerged Zander's changes, previously merged with other changes from [f74957..312b37]

Also fixes the documentaion problem in #107 (my thoughts, and a tip from dreamcat)
Patches the changelog with whats new

CHANGELOG.rdoc

@@ -1,3 +1,8 @@
+== 2.5.10 / 3 November 2009
+
+* Fixes Darcs remote repository problem when using the copy strategy [Alex `regularfry` Young]
+* Documentation improvements for embedding Capistrano [Lee Hambley]
+
 == 2.5.9 / 1 August 2009
 
 * Adds support for customizing which `tar` command to use. [Jeremy Wells]

lib/capistrano/cli.rb

@@ -17,12 +17,11 @@ module Capistrano
     # different set of parameters (such as when embedded cap in a program):
     #
     #   require 'capistrano/cli'
-    #   Capistrano::CLI.parse(%w(-vvvv -r config/deploy update_code)).execute!
+    #   Capistrano::CLI.parse(%W(-vvvv -f config/deploy update_code)).execute!
     #
     # Note that you can also embed cap directly by creating a new Configuration
-    # instance and setting it up, but you'll often wind up duplicating logic
+    # instance and setting it up, The above snippet, redone using the 
-    # defined in the CLI class. The above snippet, redone using the Configuration
+    # Configuration class directly, would look like:
-    # class directly, would look like:
     #
     #   require 'capistrano'
     #   require 'capistrano/cli'
@@ -43,5 +42,6 @@ module Capistrano
     # Mix-in the actual behavior
     include Execute, Options, UI
     include Help # needs to be included last, because it overrides some methods
+
   end
 end

lib/capistrano/recipes/deploy/scm/darcs.rb

@@ -18,11 +18,22 @@ module Capistrano
           :head
         end
 
+        def to_match(revision)
+          if revision.nil? || revision == self.head
+            nil
+          else
+            "--to-match='hash #{revision}'"
+          end
+        end
+        
         # Returns the command that will check out the given revision to the
         # given destination. The 'revision' parameter must be the 'hash' value
         # for the revision in question, as given by 'darcs changes --xml-output'.
         def checkout(revision, destination)
-          scm :get, verbose, "--repo-name=#{destination}", "--to-match='hash #{revision}'", repository
+          scm :get, *[verbose, 
+                      "--repo-name=#{destination}", 
+                      to_match(revision),
+                      repository].compact
         end
 
         # Tries to update the destination repository in-place, to bring it up

test/deploy/scm/darcs_test.rb

@@ -0,0 +1,37 @@
+require "utils"
+require 'capistrano/recipes/deploy/scm/darcs'
+
+class DeploySCMDarcsTest < Test::Unit::TestCase
+  class TestSCM < Capistrano::Deploy::SCM::Darcs
+    default_command "darcs"
+  end
+  def setup
+    @config = { :repository => "." }
+  #  def @config.exists?(name); key?(name); end
+
+    @source = TestSCM.new(@config)
+  end
+
+  # We should be able to pick a specific hash.
+  def test_checkout_hash
+    hsh = "*version_hash*"
+    assert_match(%r{--to-match=.hash #{Regexp.quote(hsh)}}, 
+                 @source.checkout(hsh, "*foo_location*"),
+                "Specifying a revision hash got the --to-match option wrong.")
+  end
+
+  # Picking the head revision should leave out the hash, because head is the
+  # default and we don't have a HEAD pseudotag
+  def test_checkout_head
+    hsh = @source.head
+    assert_no_match(%r{--to-match}, @source.checkout(hsh, "*foo_location*"),
+                    "Selecting the head revision incorrectly produced a --to-match option.")
+  end
+
+  # Leaving the revision as nil shouldn't break anything.
+  def test_checkout_nil
+    assert_no_match(%r{--to-match}, @source.checkout(nil, "*foo_location*"),
+                    "Leaving the revision as nil incorrectly produced a --to-match option.") 
+  end
+end
+