Skip to content

Latest commit

 

History

History
52 lines (35 loc) · 2.27 KB

2.x-DSL-Configuration-Tasks-Desc.md

File metadata and controls

52 lines (35 loc) · 2.27 KB
Raw

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|http://en.wikipedia.org/wiki/Here_document#Ruby]] 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)