Add 'Writing Rake Tasks' subsection to Command Line Guide

1 files changed, 47 insertions, 0 deletions

diff --git a/guides/source/command_line.textile b/guides/source/command_line.textile
index 19e42cea93..1ed0c48933 100644
--- a/guides/source/command_line.textile
+++ b/guides/source/command_line.textile
@@ -477,6 +477,53 @@ h4. Miscellaneous
 * +rake secret+ will give you a pseudo-random key to use for your session secret.
 * <tt>rake time:zones:all</tt> lists all the timezones Rails knows about.
 
+h4. Writing Rake Tasks
+
+If you have (or want to write) any automation scripts outside your app (data import, checks, etc), you can make them as rake tasks. It's easy.
+
+INFO: "Complete guide about how to write tasks":http://rake.rubyforge.org/files/doc/rakefile_rdoc.html is available in the official documentation.
+
+Tasks should be placed in <tt>Rails.root/lib/tasks</tt> and should have a +.rake+ extension.
+
+Each task should be defined in next format (dependencies are optional):
+
+<ruby>
+desc "I am short, but comprehensive description for my cool task"
+task :task_name => [:prerequisite_task, :another_task_we_depend_on] do
+  # All your magick here
+  # Any valid Ruby code is allowed
+end
+</ruby>
+
+If you need to pass parameters, you can use next format (both arguments and dependencies are optional):
+
+<ruby>
+task :task_name, [:arg_1] => [:pre_1, :pre_2] do |t, args|
+  # You can use args from here
+end
+</ruby>
+
+You can group tasks by placing them in namespaces:
+
+<ruby>
+namespace :do
+  desc "This task does nothing"
+  task :nothing do
+    # Seriously, nothing
+  end
+end
+</ruby>
+
+You can see your tasks to be listed by <tt>rake -T</tt> command. And, according to the examples above, you can invoke them as follows:
+
+<shell>
+rake task_name
+rake "task_name[value 1]" # entire argument string should be quoted
+rake do:nothing
+</shell>   
+
+NOTE: If your need to interact with your application models, perform database queries and so on, your task should depend on the +environment+ task, which will load your application code.
+
 h3. The Rails Advanced Command Line
 
 More advanced use of the command line is focused around finding useful (even surprising at times) options in the utilities, and fitting those to your needs and specific work flow. Listed here are some tricks up Rails' sleeve.