Put

Definition
put(data, path, options={})
Module
Capistrano::Configuration::Actions::FileTransfer
File
capistrano/configuration/actions/file_transfer.rb

The put action is upload's little brother. Rather than uploading from a file (or directory) locally, it takes a string and uploads that as the contents of a file on the remote servers. This lets you upload generated content without having to write it to a file locally, first.

Arguments

data

This is a string containing the contents of the file you want to upload.

path

This is a string naming the file on the remote server(s) that should be created (or overwritten) with the given data. It may include the string $CAPISTRANO:HOST$, which will be replaced with the actual host name when the file is uploaded.

options

The options hash can be used to modify the default behavior of put. Recognized options are:

:mode
This should a string indicating the desired permissions of the destination file or directory, after it is uploaded. Permissions are changed via a separate call to chmod, so any valid argument to chmod will work (either octal numbers or symbolic permissions).
:via
This is a symbol indicating which protocol should be used to transfer the file or directory. If given, it must be either :sftp (the default), or :scp.
:hosts
Either a string (for a single target host) or an array of strings, indicating which hosts should be uploaded to. By default, the hosts are determined from current task's roles.
:roles
Either a string or symbol (for a single target role) or an array of strings or symbols, indicating which roles should be uploaded to. If :hosts is specified, :roles will be ignored. By default, the roles are taken from the current task.
:only
Specifies a condition limiting which hosts will be selected to receive the upload. This should refer to values set in the role. For example, if a role is defined with :primary => true, then you could select only hosts with that setting by specifying :only => { :primary => true }.
:except
Specifies a condition limiting which hosts will be selected to receive the upload. This is the inverse of :only (hosts that do not match the condition will be selected).
:once
If true, only the first matching server will be selected. The default is false (all matching servers will be selected).
:max_hosts
Specifies the maximum number of hosts that should be selected at a time. If this value is less than the number of hosts that are selected to receive the upload, then the hosts will be uploaded to in groups of max_hosts. The default is nil, which indicates that there is no maximum host limit. Warning: this setting will probably be removed in a future release.

Note that the options are also passed directly through to the Net::SFTP (for :sftp) and Net::SCP (for :scp) libraries. Options exposed by those libraries are documented in those libraries. (For SFTP, see the Net::SFTP::Operations::Upload module. For SCP, see the Net::SCP#upload method.)

Examples

For example, suppose you wanted to generate a Rails database configuration file in-memory. Since it's just a YAML file, you can easily create the configuration as a Ruby Hash object, and convert it to YAML and upload it, like this: 

config = { "adapter"  => "mysql",
           "database" => "social_prod",
           "host"     => "db.social",
           "username" => "social",
           "password" => "social-password" }
put config.to_yaml, "/u/apps/social/current/config/database.yml"

Another common use for the put helper is to generate something from an (e.g.) ERB template, to upload. To use Rails again as an example, suppose you want to upload a maintenance.html page to display while you do some scheduled maintenance on your web app: 

require 'erb'
reason = ENV['REASON']
until = ENV['UNTIL']
html = ERB.new(File.read("maintenance.rhtml")).result(binding)
put html, "/u/apps/social/current/public/maintenance.html"

See Also