Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

2.x DSL Configuration Tasks Desc

josegonzalez edited this page · 2 revisions

Definition

desc(text) 

Module

Capistrano::Configuration::Namespaces

By itself, desc does nothing. But when a task declaration immediately follows it, the text parameter to desc gets applied as the description of the subsequent task.

Arguments

text

This should be a string containing the description of the next task to be declared. Typically, the first sentence of the description is used as the "quick" description, or summary, and should be fairly short. (Less than thirty characters, if possible.) The remaining text is the full description.

Because descriptions are generally longer than a single line, it is convenient to use here-documents for them.

Examples

desc "Backup the database."
task :backup_database, :roles => :db do
  # ...
end

desc <<-DESC
  Ensure that all network volumes are mounted. Tests each volume to be sure \
  it is live, and if it isn't, tries to mount it. Failures are printed to \
  the terminal. If you specify the VOLUMES variable as a comma-delimited list \
  only the volumes you specify will be checked:

    # check all volumes
    cap network_volumes

    # check only these volumes
    cap VOLUMES=disk1,disk2 network_volumes

  This is a fairly expensive operation, so expect it to take some time on \
  systems with multiple network volumes.
DESC
task :network_volumes do
  # ...
end

In the previous example, notice that newlines are escaped. This ensures that the raw newlines aren't included in the description string, which allows Capistrano to format them more nicely. You certainly aren't required to do likewise, but it does result in nicer output if you do.

In general, Capistrano will do some minimal formatting of your help text (when using the --explain-task switch, for instance).

  • newlines are interpreted as line breaks
  • lines will be reflowed to fit the terminal width (or 80 characters)
  • whitespace before the first line of text will be removed, and the same amount of whitespace will be removed from subsequent lines
  • lines with more leading whitespace than the first will preserve the extra whitespace (so examples can be easily distinguised if you indent them extra)
Something went wrong with that request. Please try again.