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.
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).