capistrano-file-transfer-ext 0.0.3 → 0.0.4

data/README.md

@@ -22,10 +22,74 @@ Add `require` line in your `Capfile` or `config/deploy.rb` or so.
 
     require "capistrano/configuration/actions/file_transfer_ext"
 
-`file_transfer_ext` provides following additional file transfer actions. You can use them in your tasks.
+Now you can use them in your tasks.
+
+* `safe_upload` - Transfers a file from the local host to multiple remote hosts. ([more...](#safe_upload))
+* `safe_put` - Store the contents of multiple servers. ([more...](#safe_put))
+
+## Reference
+
+### `safe_upload`
+
+**Definition**
+
+    safe_upload(from, to, options={}, &block)
+
+**Module**
+
+    Capistrano::Configuration::Actions::FileTransferExt
+
+The `safe_upload` acts like almost as same as `upload`, but with some little enhancements.
+
+1. overwrite remote file only if transmission has been successfully completed.
+2. (if you request) overwrite remote file only if the checksums are different.
+
+#### Arguments
+
+**from**
+
+Thie may be either a String, or an IO object (e.g. an open file handle, or a StringIO instance).
+
+**to**
+
+This must be a string indicating the path on the remote server that should be uploaded to.
+
+**options**
+
+All of the options of `upload` are sensible. In addition, there are some extra options.
+
+* `:install` It must be either `:always` (the default), or `:if_modified`. If `:if_modified` is given, install the file only if the checksums are different.
+* `:digest` Thi is a symbol indicating which algorithm should be used to calculate the checksum of files. `:md5` is default.
+* `:digest_cmd` The command to calculate checksum of files. `md5sum` is default.
+* `:sudo` It must be a boolean. If set true, use `sudo` on placing files. `false` by default.
+
+
+### `safe_put`
+
+**Definition**
+
+    safe_put(data, to, options={})
+
+**Module**
+
+    Capistrano::Configuration::Actions::FileTransferExt
+
+The `safe_put` action is `safe_upload`'s little brother.
+
+#### Arguments
+
+**data**
+
+This is a string containing the contents of the file you want to upload.
+
+**to**
+
+This is a string naming the file on the remote server(s) that should be created (or overwritten) with the given data.
+
+**options**
+
+All of the options of `safe_upload` are sensible.
 
-  * `safe_put` - Store the contents of multiple servers, with comparing the difference of the contents.
-  * `safe_upload` - Transfers a file from the local host to multiple remote hosts, with comparing the difference of the contents.
 
 ## Contributing
 

data/lib/capistrano/configuration/actions/file_transfer_ext.rb

@@ -20,7 +20,7 @@ module Capistrano
     }
   }
 }
-                            }.gsub(/\s+/, "").strip
+        }.gsub(/\s+/, "").strip
 
         def safe_put(data, path, options={})
           opts = options.dup
@@ -33,18 +33,23 @@ module Capistrano
         # The +options+ hash may include any of the following keys:
         #
         # * :transfer - use transfer_if_modified if :if_modified is set
-        # * :place - use place_if_modified if :if_modified is set
+        # * :install - use install_if_modified if :if_modified is set
         # * :run_method - the default is :run.
         def safe_upload(from, to, options={}, &block)
           transfer_method = options.delete(:transfer) == :if_modified ? :transfer_if_modified : :transfer
-          place_method = options.delete(:place) == :if_modified ? :place_if_modified : :place
+          if options.has_key?(:install)
+            install_method = options.delete(:install) == :if_modified ? :install_if_modified : :install
+          else
+            # for backward compatibility before v0.0.4.
+            install_method = options.delete(:place)   == :if_modified ? :install_if_modified : :install
+          end
           run_method = ( options.delete(:run_method) || :run )
           begin
             tempname = File.join("/tmp", File.basename(to) + ".XXXXXXXXXX")
             tempfile = capture("mktemp #{tempname.dump}").strip
             run("rm -f #{tempfile.dump}", options)
             send(transfer_method, :up, from, tempfile, options, &block)
-            send(place_method, tempfile, to, options.merge(:via => run_method), &block)
+            send(install_method, tempfile, to, options.merge(:via => run_method), &block)
           ensure
             run("rm -f #{tempfile.dump}", options) rescue nil
           end
@@ -92,14 +97,14 @@ module Capistrano
           end
         end
 
-        # place a file on remote.
+        # install a file on remote.
         #
         # The +options+ hash may include any of the following keys:
         #
         # * :mode - permission of the file.
         # * :sudo - use sudo if set true. the default is false.
         #
-        def place(from, to, options={}, &block)
+        def install(from, to, options={}, &block)
           mode = options.delete(:mode)
           try_sudo = options.delete(:sudo) ? sudo : ""
           execute = []
@@ -111,8 +116,9 @@ module Capistrano
           end
           invoke_command(execute.join(" && "), options)
         end
+        alias place install
 
-        # place a file on remote, only if the destination is differ from source.
+        # install a file on remote, only if the destination is differ from source.
         #
         # The +options+ hash may include any of the following keys:
         #
@@ -121,7 +127,7 @@ module Capistrano
         # * :digest - digest algorithm. the default is "md5".
         # * :digest_cmd - the digest command. the default is "#{digest}sum".
         #
-        def place_if_modified(from, to, options={}, &block)
+        def install_if_modified(from, to, options={}, &block)
           mode = options.delete(:mode)
           try_sudo = options.delete(:sudo) ? sudo : ""
           digest_method = options.fetch(:digest, "md5")
@@ -149,6 +155,7 @@ module Capistrano
           end
           invoke_command(execute.join(" && "), options)
         end
+        alias place_if_modified install_if_modified
       end
     end
   end

data/lib/capistrano/configuration/actions/file_transfer_ext/version.rb

@@ -2,7 +2,7 @@ module Capistrano
   class Configuration
     module Actions
       module FileTransferExt
-        VERSION = "0.0.3"
+        VERSION = "0.0.4"
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-file-transfer-ext
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-27 00:00:00.000000000 Z
+date: 2013-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano