Set

Definition
set(name, value)
set(name, &block)
Module
Capistrano::Configuration::Variables
File
capistrano/configuration/variables.rb

This method is the primary way of defining variables that can be accessed anywhere within a Capistrano configuration. It allows you to set both immediate and deferred variables, depending on whether or not you used a block to define the variable.

Arguments

name

This should be a symbol naming the variable. Although the only real constraint is that the name must begin with an underscore or a lower-case letter, you should probably embrace the following constraints. too:

  • Only use names that are valid Ruby identifiers (start with a letter or underscore, and contain only letters, digits, and underscores). Otherwise, you'll find it hard to get the value of your variable except via fetch.
  • Do not use the same name for a variable as you have for a task or namespace. Otherwise, the task or namespace will take precedence and you won't be able to access your variable except via fetch.
  • Do not use the same name for a Capistrano variable as you have for a local variable. Otherwise, the local variable will take precedence. (This can happen when, for instance, you try to assign to a Capistrano variable using the x = y syntax, instead of using set.

value

This will be the value of the variable. 

set :user, "bob"
set :keep_releases, 10
set :ssh_options, { :user => "bob", :port => 1234 }

Any valid Ruby object is allowable, except for Proc objects. If you set a variable to a Proc object, it has the same effect as passing a block to set (see below).

&block

If, instead of an explicit value, you use a block to set the variable's value, you're creating a deferred variable. Such a variable will be lazily evaluated. What this means in practice is the block will not be evaluated immedately. Instead, the block will be saved until the first time the variable is referenced. At that time, the block will be invoked, it's return value cached, and the result returned as the value of the variable. The block will not be invoked again; instead, subsequent requests for the variable will return the cached value.

For example: 

x = 0
set(:demonstration) { x += 1 }
puts x             #<-- prints "0"
puts demonstration #<-- prints "1"
puts x             #<-- prints "1"
puts demonstration #<-- prints "1"
puts x             #<-- prints "1"

This is commonly used to avoid putting passwords or other sensitive data in a Capistrano recipe. Instead of hard-coding it, you use a deferred variable to prompt for it, and then cache the result. For example:

See Also