Desc
- Definition
- desc(text)
- Module
- Capistrano::Configuration::Namespaces
- File
- capistrano/configuration/namespaces.rb
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.
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)