1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2 <html xmlns=
"http://www.w3.org/1999/xhtml" lang=
"en" xml:
lang=
"en">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
5 <title>A Guide to The Rails Command Line
</title>
7 <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
9 <link href=
"stylesheets/base.css" media=
"screen" rel=
"Stylesheet" type=
"text/css" />
10 <link href=
"stylesheets/forms.css" media=
"screen" rel=
"Stylesheet" type=
"text/css" />
11 <link href=
"stylesheets/more.css" media=
"screen" rel=
"Stylesheet" type=
"text/css" />
12 <style type=
"text/css">
36 border: solid
1px #cccccc;
52 #content dt tt, #content pre tt {
81 div#header h1#site_title {
82 background: url('images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
108 .left-floaty, .right-floaty {
120 .admonitionblock .icon {
124 .admonitionblock .content {
125 border: solid
1px #ffda78;
132 .admonitionblock .title {
134 margin-bottom:
0.5em;
138 border: solid
1px #aaaaff;
156 border: solid
1px #ccccbb;
161 .sidebarblock .sidebar-title {
164 margin-bottom:
0.3em;
167 .sidebarblock .sidebar-content
> .para:last-child
> p {
171 .sidebarblock .sidebar-title a {
172 text-decoration: none;
175 .sidebarblock .sidebar-title a:hover {
176 text-decoration: underline;
184 <a href=
"index.html" title=
"Ruby on Rails"><img src=
"images/rails_logo_remix.gif" alt=
"Rails" height=
"140" width=
"110" /></a>
187 <h1 id=
"site_title"><span>Ruby on Rails
</span></h1>
188 <h2 id=
"site_title_tagline">Sustainable productivity for web-application development
</h2>
191 <li class=
"first-child"><a href=
"http://www.rubyonrails.org/" title=
"Ruby on Rails" class=
"ruby_on_rails">Ruby on Rails
</a></li>
192 <li><a class=
"manuals" href=
"index.html" title=
"Manuals Index">Guides Index
</a></li>
202 <a href=
"#_command_line_basics">Command Line Basics
</a>
205 <li><a href=
"#_rails">rails
</a></li>
207 <li><a href=
"#_server">server
</a></li>
209 <li><a href=
"#_generate">generate
</a></li>
217 <h1>A Guide to The Rails Command Line
</h1>
219 <div class=
"sectionbody">
220 <div class=
"para"><p>Rails comes with every command line tool you'll need to
</p></div>
221 <div class=
"ilist"><ul>
224 Create a Rails application
229 Generate models, controllers, database migrations, and unit tests
234 Start a development server
239 Mess with objects through an interactive shell
244 Profile and benchmark your new creation
248 <div class=
"para"><p>… and much, much more! (Buy now!)
</p></div>
249 <div class=
"para"><p>This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.
</p></div>
252 <h2 id=
"_command_line_basics">1. Command Line Basics
</h2>
253 <div class=
"sectionbody">
254 <div class=
"para"><p>There are a few commands that are absolutely critical to your everyday usage of Rails. In the order of how much you'll probably use them are:
</p></div>
255 <div class=
"ilist"><ul>
282 <div class=
"para"><p>Let's create a simple Rails application to step through each of these commands in context.
</p></div>
283 <h3 id=
"_rails">1.1. rails
</h3>
284 <div class=
"para"><p>The first thing we'll want to do is create a new Rails application by running the
<tt>rails
</tt> command after installing Rails.
</p></div>
285 <div class=
"admonitionblock">
288 <img src=
"./images/icons/note.png" alt=
"Note" />
290 <td class=
"content">You know you need the rails gem installed by typing
<tt>gem install rails
</tt> first, right? Okay, okay, just making sure.
</td>
293 <div class=
"listingblock">
294 <div class=
"content"><!-- Generator: GNU source-highlight 2.9
296 http://www.lorenzobettini.it
297 http://www.gnu.org/software/src-highlite -->
298 <pre><tt>$ rails commandsapp
301 create app/controllers
304 <span style=
"color: #990000">...
</span>
305 <span style=
"color: #990000">...
</span>
306 create log/production
<span style=
"color: #990000">.
</span>log
307 create log/development
<span style=
"color: #990000">.
</span>log
308 create log/test
<span style=
"color: #990000">.
</span>log
309 </tt></pre></div></div>
310 <div class=
"para"><p>Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box.
</p></div>
311 <div class=
"admonitionblock">
314 <img src=
"./images/icons/note.png" alt=
"Note" />
316 <td class=
"content">This output will seem very familiar when we get to the
<tt>generate
</tt> command. Creepy foreshadowing!
</td>
319 <h3 id=
"_server">1.2. server
</h3>
320 <div class=
"para"><p>Let's try it! The
<tt>server
</tt> command launches a small web server written in Ruby named WEBrick which was also installed when you installed Rails. You'll use this any time you want to view your work through a web browser.
</p></div>
321 <div class=
"admonitionblock">
324 <img src=
"./images/icons/note.png" alt=
"Note" />
326 <td class=
"content">WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section]
</td>
329 <div class=
"para"><p>Here we'll flex our
<tt>server
</tt> command, which without any prodding of any kind will run our new shiny Rails app:
</p></div>
330 <div class=
"listingblock">
331 <div class=
"content"><!-- Generator: GNU source-highlight 2.9
333 http://www.lorenzobettini.it
334 http://www.gnu.org/software/src-highlite -->
335 <pre><tt>$ cd commandsapp
336 $
<span style=
"color: #990000">.
</span>/script/server
337 <span style=
"color: #990000">=
></span> Booting WEBrick
<span style=
"color: #990000">...
</span>
338 <span style=
"color: #990000">=
></span> Rails
<span style=
"color: #993399">2.2</span><span style=
"color: #990000">.
</span><span style=
"color: #993399">0</span> application started on http
<span style=
"color: #990000">://
</span><span style=
"color: #993399">0.0</span><span style=
"color: #990000">.
</span><span style=
"color: #993399">0.0</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">3000</span>
339 <span style=
"color: #990000">=
></span> Ctrl-C to shutdown server
<span style=
"color: #990000">;
</span> call with --help
<span style=
"font-weight: bold"><span style=
"color: #0000FF">for
</span></span> options
340 <span style=
"color: #990000">[
</span><span style=
"color: #993399">2008</span>-
<span style=
"color: #993399">11</span>-
<span style=
"color: #993399">04</span> <span style=
"color: #993399">10</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">11</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">38</span><span style=
"color: #990000">]
</span> INFO WEBrick
<span style=
"color: #993399">1.3</span><span style=
"color: #990000">.
</span><span style=
"color: #993399">1</span>
341 <span style=
"color: #990000">[
</span><span style=
"color: #993399">2008</span>-
<span style=
"color: #993399">11</span>-
<span style=
"color: #993399">04</span> <span style=
"color: #993399">10</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">11</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">38</span><span style=
"color: #990000">]
</span> INFO ruby
<span style=
"color: #993399">1.8</span><span style=
"color: #990000">.
</span><span style=
"color: #993399">5</span> <span style=
"color: #990000">(
</span><span style=
"color: #993399">2006</span>-
<span style=
"color: #993399">12</span>-
<span style=
"color: #993399">04</span><span style=
"color: #990000">)
</span> <span style=
"color: #990000">[
</span>i486-linux
<span style=
"color: #990000">]
</span>
342 <span style=
"color: #990000">[
</span><span style=
"color: #993399">2008</span>-
<span style=
"color: #993399">11</span>-
<span style=
"color: #993399">04</span> <span style=
"color: #993399">10</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">11</span><span style=
"color: #990000">:
</span><span style=
"color: #993399">38</span><span style=
"color: #990000">]
</span> INFO WEBrick
<span style=
"color: #990000">::
</span>HTTPServer
<span style=
"font-style: italic"><span style=
"color: #9A1900">#start: pid=
18994 port=
3000</span></span>
343 </tt></pre></div></div>
344 <div class=
"para"><p>WHOA. With just three commands we whipped up a Rails server listening on port
3000. Go! Go right now to your browser and go to
<a href=
"http://localhost:3000">http://localhost:
3000</a>. I'll wait.
</p></div>
345 <div class=
"para"><p>See? Cool! It doesn't do much yet, but we'll change that.
</p></div>
346 <h3 id=
"_generate">1.3. generate
</h3>
347 <div class=
"para"><p>The
<tt>generate
</tt> command uses templates to create a whole lot of things. You can always find out what's available by running
<tt>generate
</tt> by itself. Let's do that:
</p></div>
348 <div class=
"listingblock">
349 <div class=
"content"><!-- Generator: GNU source-highlight 2.9
351 http://www.lorenzobettini.it
352 http://www.gnu.org/software/src-highlite -->
353 <pre><tt>$
<span style=
"color: #990000">.
</span>/script/generate
354 Usage
<span style=
"color: #990000">:
</span> <span style=
"color: #990000">.
</span>/script/generate generator
<span style=
"color: #990000">[
</span>options
<span style=
"color: #990000">]
</span> <span style=
"color: #990000">[
</span>args
<span style=
"color: #990000">]
</span>
356 <span style=
"color: #990000">...
</span>
357 <span style=
"color: #990000">...
</span>
360 Builtin
<span style=
"color: #990000">:
</span> controller
<span style=
"color: #990000">,
</span> integration_test
<span style=
"color: #990000">,
</span> mailer
<span style=
"color: #990000">,
</span> migration
<span style=
"color: #990000">,
</span> model
<span style=
"color: #990000">,
</span> observer
<span style=
"color: #990000">,
</span> performance_test
<span style=
"color: #990000">,
</span> plugin
<span style=
"color: #990000">,
</span> resource
<span style=
"color: #990000">,
</span> scaffold
<span style=
"color: #990000">,
</span> session_migration
362 <span style=
"color: #990000">...
</span>
363 <span style=
"color: #990000">...
</span>
364 </tt></pre></div></div>
365 <div class=
"admonitionblock">
368 <img src=
"./images/icons/note.png" alt=
"Note" />
370 <td class=
"content">You can install more generators through generator gems, portions of plugins you'll undoubtedly install, and you can even create your own!
</td>
373 <div class=
"para"><p>Using generators will save you a large amount of time by writing
<strong>boilerplate code
</strong> for you
— necessary for the darn thing to work, but not necessary for you to spend time writing. That's what we have computers for, right?
</p></div>
374 <div class=
"para"><p>Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:
</p></div>
375 <div class=
"admonitionblock">
378 <img src=
"./images/icons/note.png" alt=
"Note" />
380 <td class=
"content">All Rails console utilities have help text. For commands that require a lot of input to run correctly, you can just try the command without any parameters (like
<tt>rails
</tt> or
<tt>./script/generate
</tt>). For others, you can try adding
<tt>—help
</tt> or
<tt>-h
</tt> to the end, as in
<tt>./script/server
—help
</tt>.
</td>
383 <div class=
"listingblock">
384 <div class=
"content"><!-- Generator: GNU source-highlight 2.9
386 http://www.lorenzobettini.it
387 http://www.gnu.org/software/src-highlite -->
388 <pre><tt>$
<span style=
"color: #990000">.
</span>/script/generate controller
389 Usage
<span style=
"color: #990000">:
</span> <span style=
"color: #990000">.
</span>/script/generate controller ControllerName
<span style=
"color: #990000">[
</span>options
<span style=
"color: #990000">]
</span>
391 <span style=
"color: #990000">...
</span>
392 <span style=
"color: #990000">...
</span>
394 Example
<span style=
"color: #990000">:
</span>
395 `
<span style=
"color: #990000">.
</span>/script/generate controller CreditCard open debit credit close`
397 Credit card controller with URLs like /credit_card/debit
<span style=
"color: #990000">.
</span>
398 Controller
<span style=
"color: #990000">:
</span> app/controllers/credit_card_controller
<span style=
"color: #990000">.
</span>rb
399 Views
<span style=
"color: #990000">:
</span> app/views/credit_card/debit
<span style=
"color: #990000">.
</span>html
<span style=
"color: #990000">.
</span>erb
<span style=
"color: #990000">[...]
</span>
400 Helper
<span style=
"color: #990000">:
</span> app/helpers/credit_card_helper
<span style=
"color: #990000">.
</span>rb
401 Test
<span style=
"color: #990000">:
</span> test/functional/credit_card_controller_test
<span style=
"color: #990000">.
</span>rb
403 Modules Example
<span style=
"color: #990000">:
</span>
404 `
<span style=
"color: #990000">.
</span>/script/generate controller
<span style=
"color: #FF0000">'admin/credit_card'
</span> <span style=
"font-weight: bold"><span style=
"color: #0000FF">suspend
</span></span> late_fee`
406 Credit card admin controller with URLs /admin/credit_card/suspend
<span style=
"color: #990000">.
</span>
407 Controller
<span style=
"color: #990000">:
</span> app/controllers/admin/credit_card_controller
<span style=
"color: #990000">.
</span>rb
408 Views
<span style=
"color: #990000">:
</span> app/views/admin/credit_card/debit
<span style=
"color: #990000">.
</span>html
<span style=
"color: #990000">.
</span>erb
<span style=
"color: #990000">[...]
</span>
409 Helper
<span style=
"color: #990000">:
</span> app/helpers/admin/credit_card_helper
<span style=
"color: #990000">.
</span>rb
410 Test
<span style=
"color: #990000">:
</span> test/functional/admin/credit_card_controller_test
<span style=
"color: #990000">.
</span>rb
411 </tt></pre></div></div>
412 <div class=
"para"><p>Ah, the controller generator is expecting parameters in the form of
<tt>generate controller ControllerName action1 action2
</tt>. Let's make a
<tt>Greetings
</tt> controller with an action of
<strong>hello
</strong>, which will say something nice to us.
</p></div>
413 <div class=
"listingblock">
414 <div class=
"content"><!-- Generator: GNU source-highlight 2.9
416 http://www.lorenzobettini.it
417 http://www.gnu.org/software/src-highlite -->
418 <pre><tt>$
<span style=
"color: #990000">.
</span>/script/generate controller Greeting hello
419 exists app/controllers
<span style=
"color: #990000">/
</span>
420 exists app/helpers
<span style=
"color: #990000">/
</span>
421 create app/views/greeting
422 exists test/functional
<span style=
"color: #990000">/
</span>
423 create app/controllers/greetings_controller
<span style=
"color: #990000">.
</span>rb
424 create test/functional/greetings_controller_test
<span style=
"color: #990000">.
</span>rb
425 create app/helpers/greetings_helper
<span style=
"color: #990000">.
</span>rb
426 create app/views/greetings/hello
<span style=
"color: #990000">.
</span>html
<span style=
"color: #990000">.
</span>erb
427 </tt></pre></div></div>
428 <div class=
"para"><p>Look there! Now what all did this generate? It looks like it made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file. All from one command!
</p></div>