From 74fe58add5d6d83038e7db3c79024b6789a2ec25 Mon Sep 17 00:00:00 2001
From: Colin Curtin <colin@procore.com>
Date: Thu, 19 Feb 2009 21:05:27 -0800
Subject: Added Rake section to the command line guide.

---
 railties/guides/source/command_line.textile | 67 ++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

(limited to 'railties/guides/source/command_line.textile')

diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile
index f02677d760..54756655b4 100644
--- a/railties/guides/source/command_line.textile
+++ b/railties/guides/source/command_line.textile
@@ -466,7 +466,7 @@ We take whatever args are supplied, save them to an instance variable, and liter
 * Check there's a *public* directory. You bet there is.
 * Run the ERb template called "tutorial.erb".
 * Save it into "RAILS_ROOT/public/tutorial.txt".
-* Pass in the args we saved through the +:assign+ parameter.
+* Pass in the arguments we saved through the +:assign+ parameter.
 
 Next we'll build the template:
 
@@ -511,3 +511,68 @@ I got assigned some args:
 </shell>
 
 Tada!
+
+h4. Rake is Ruby Make
+
+Rake is a standalone Ruby utility that replaces the Unix utility `make`, and uses a `Rakefile` and `.rake` files to build up a list of tasks. In Rails, Rake is used for common administration tasks, especially sophisticated ones that build off of each other.
+
+You can get a list of Rake tasks available to you, which will often depend on your current directory, by typing `rake --tasks`. Each task has a description, and should help you find the thing you need.
+
+<shell>
+ rake --tasks
+(in /home/developer/commandsapp)
+rake db:abort_if_pending_migrations       # Raises an error if there are pending migrations
+rake db:charset                           # Retrieves the charset for the current environment's database
+rake db:collation                         # Retrieves the collation for the current environment's database
+rake db:create                            # Create the database defined in config/database.yml for the current RAILS_ENV
+...
+...
+rake tmp:pids:clear                       # Clears all files in tmp/pids
+rake tmp:sessions:clear                   # Clears all files in tmp/sessions
+rake tmp:sockets:clear                    # Clears all files in tmp/sockets
+</shell>
+
+Let's take a look at some of these 80 or so rake tasks.
+
+h5. db: Database
+The most common of the `db:` Rake namespace are migrate and create, and it will pay off to try out all of the migration rake tasks (up, down, redo, reset). `rake db:version` is useful when troubleshooting, telling you the current version of the database.
+
+h5. doc: Documentation
+If you want to strip out or rebuild any of the Rails documentation (including this guide!), the `doc:` namespace has the tools. Stripping documentation is mainly useful for slimming your codebase, like if you're writing a Rails application for an embedded platform.
+
+h5. gems: Ruby gems
+You can specify which gems your application uses, and `rake gems:install` will install them for you. Look at your environment.rb to learn how with the *config.gem* directive.
+
+NOTE: `gems:unpack` will unpack, that is internalize your application's Gem dependencies by copying the Gem code into your vendor/gems directory. By doing this you increase your codebase size, but simplify installation on new hosts by eliminating the need to run `rake gems:install`, or finding and installing the gems your application uses.
+
+h5. notes: Code note enumeration
+These tasks will search through your code for commented lines beginning with "FIXME", "OPTIMIZE", "TODO", or any custom annotation (like XXX) and show you them.
+
+h5. rails: Rails-specific tasks
+In addition to the `gems:unpack` task above, you can also unpack the Rails backend specific gems into vendor/rails by calling `rake rails:freeze:gems`, to unpack the version of Rails you are currently using, or `rake rails:freeze:edge` to unpack the most recent (cutting, bleeding edge) version.
+
+When you have frozen the Rails gems, Rails will prefer to use the code in vendor/rails instead of the system Rails gems. You can "thaw" by running `rake rails:unfreeze`.
+
+After upgrading Rails, it is useful to run `rails:update`, which will update your config and scripts directories, and upgrade your Rails-specific javascript (like Scriptaculous).
+
+h5. test: Rails tests
+
+INFO: A good description of unit testing in Rails is given in "A Guide to Testing Rails Applications":testing.html
+
+Rails comes with a test suite called Test::Unit. It is through the use of tests that Rails itself is so stable, and the slew of people working on Rails can prove that everything works as it should. 
+
+The `test:` namespace helps in running the different tests you will (hopefully!) write.
+
+h5. time: Timezones
+You can list all the timezones Rails knows about with `rake time:zones:all`, which is useful just in day-to-day life.
+
+h5. tmp: Temporary files
+The tmp directory is, like in the *nix /tmp directory, the holding place for temporary files like sessions (if you're using a file store for files), process id files, and cached actions. The `tmp:` namespace tasks will help you clear them if you need to if they've become overgrown, or create them in case of an rm -rf * gone awry.
+  
+h5. Miscellaneous tasks
+`rake stats` is great for looking at statistics on your code, displaying things like KLOCs (thousands of lines of code) and your code to test ratio.
+
+`rake secret` will give you a psuedo-random key to use for your session secret.
+
+`rake routes` will list all of your defined routes, which is useful for tracking down routing problems in your app, or giving you a good overview of the URLs in an app you're trying to get familiar with.
+
-- 
cgit v1.2.3

