-
Notifications
You must be signed in to change notification settings - Fork 36
/
Copy pathbeginning.html
1545 lines (887 loc) · 165 KB
/
beginning.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>beginning</title>
<link rel="stylesheet" href="pygments.css" type="text/css" />
<link rel="stylesheet" href="polytexnic.css" type="text/css" />
</head>
<body>
<div id="book">
<h1 class="title">Ruby on Rails Tutorial </h1>
<h1 class="subtitle"> Learn Web Development with Rails</h1>
<h2 class="author">Michael Hartl</h2>
<h2 class="contents">Contents</h2>
<div id="table_of_contents"><ol><li class="chapter"><a href="beginning.html#top"><span class="number">Chapter 1</span> From zero to deploy</a></li><li><ol><li class="section"><a href="beginning.html#sec-introduction"><span class="number">1.1</span> Introduction</a></li><li><ol><li class="subsection"><a href="beginning.html#sec-comments_for_various_readers"><span class="number">1.1.1</span> Comments for various readers</a></li><li class="subsection"><a href="beginning.html#sec-1_1_2"><span class="number">1.1.2</span> “Scaling” Rails</a></li><li class="subsection"><a href="beginning.html#sec-conventions"><span class="number">1.1.3</span> Conventions in this book</a></li></ol></li><li class="section"><a href="beginning.html#sec-up_and_running"><span class="number">1.2</span> Up and running</a></li><li><ol><li class="subsection"><a href="beginning.html#sec-development_tools"><span class="number">1.2.1</span> Development environments</a></li><li><ol><li class="subsubsection"><a href="beginning.html#sec-1_2_1_1">IDEs</a></li><li class="subsubsection"><a href="beginning.html#sec-1_2_1_2">Text editors and command lines</a></li><li class="subsubsection"><a href="beginning.html#sec-1_2_1_3">Browsers</a></li><li class="subsubsection"><a href="beginning.html#sec-1_2_1_4">A note about tools</a></li></ol></li><li class="subsection"><a href="beginning.html#sec-rubygems"><span class="number">1.2.2</span> Ruby, RubyGems, Rails, and Git</a></li><li><ol><li class="subsubsection"><a href="beginning.html#sec-rails_installer_windows">Rails Installer (Windows)</a></li><li class="subsubsection"><a href="beginning.html#sec-install_git">Install Git</a></li><li class="subsubsection"><a href="beginning.html#sec-install_ruby">Install Ruby</a></li><li class="subsubsection"><a href="beginning.html#sec-install_rubygems">Install RubyGems</a></li><li class="subsubsection"><a href="beginning.html#sec-install_rails">Install Rails</a></li></ol></li><li class="subsection"><a href="beginning.html#sec-the_first_application"><span class="number">1.2.3</span> The first application</a></li><li class="subsection"><a href="beginning.html#sec-bundler"><span class="number">1.2.4</span> Bundler</a></li><li class="subsection"><a href="beginning.html#sec-rails_server"><span class="number">1.2.5</span> <tt>rails server</tt></a></li><li class="subsection"><a href="beginning.html#sec-mvc"><span class="number">1.2.6</span> Model-view-controller (MVC)</a></li></ol></li><li class="section"><a href="beginning.html#sec-version_control"><span class="number">1.3</span> Version control with Git</a></li><li><ol><li class="subsection"><a href="beginning.html#sec-git_setup"><span class="number">1.3.1</span> Installation and setup</a></li><li><ol><li class="subsubsection"><a href="beginning.html#sec-1_3_1_1">First-time system setup</a></li><li class="subsubsection"><a href="beginning.html#sec-1_3_1_2">First-time repository setup</a></li></ol></li><li class="subsection"><a href="beginning.html#sec-adding_and_committing"><span class="number">1.3.2</span> Adding and committing</a></li><li class="subsection"><a href="beginning.html#sec-1_3_3"><span class="number">1.3.3</span> What good does Git do you?</a></li><li class="subsection"><a href="beginning.html#sec-github"><span class="number">1.3.4</span> GitHub</a></li><li class="subsection"><a href="beginning.html#sec-git_commands"><span class="number">1.3.5</span> Branch, edit, commit, merge</a></li><li><ol><li class="subsubsection"><a href="beginning.html#sec-git_branch">Branch</a></li><li class="subsubsection"><a href="beginning.html#sec-git_edit">Edit</a></li><li class="subsubsection"><a href="beginning.html#sec-git_commit">Commit</a></li><li class="subsubsection"><a href="beginning.html#sec-git_merge">Merge</a></li><li class="subsubsection"><a href="beginning.html#sec-git_push">Push</a></li></ol></li></ol></li><li class="section"><a href="beginning.html#sec-deploying"><span class="number">1.4</span> Deploying</a></li><li><ol><li class="subsection"><a href="beginning.html#sec-heroku_setup"><span class="number">1.4.1</span> Heroku setup</a></li><li class="subsection"><a href="beginning.html#sec-heroku_step_one"><span class="number">1.4.2</span> Heroku deployment, step one</a></li><li class="subsection"><a href="beginning.html#sec-1_4_3"><span class="number">1.4.3</span> Heroku deployment, step two</a></li><li class="subsection"><a href="beginning.html#sec-heroku_commands"><span class="number">1.4.4</span> Heroku commands</a></li></ol></li><li class="section"><a href="beginning.html#sec-beginning_conclusion"><span class="number">1.5</span> Conclusion</a></li></ol></li><li class="chapter"><a href="a-demo-app.html#top"><span class="number">Chapter 2</span> A demo app</a></li><li><ol><li class="section"><a href="a-demo-app.html#sec-planning_the_application"><span class="number">2.1</span> Planning the application</a></li><li><ol><li class="subsection"><a href="a-demo-app.html#sec-modeling_demo_users"><span class="number">2.1.1</span> Modeling demo users</a></li><li class="subsection"><a href="a-demo-app.html#sec-modeling_demo_microposts"><span class="number">2.1.2</span> Modeling demo microposts</a></li></ol></li><li class="section"><a href="a-demo-app.html#sec-demo_users_resource"><span class="number">2.2</span> The Users resource</a></li><li><ol><li class="subsection"><a href="a-demo-app.html#sec-a_user_tour"><span class="number">2.2.1</span> A user tour</a></li><li class="subsection"><a href="a-demo-app.html#sec-mvc_in_action"><span class="number">2.2.2</span> MVC in action</a></li><li class="subsection"><a href="a-demo-app.html#sec-weaknesses_of_this_users_resource"><span class="number">2.2.3</span> Weaknesses of this Users resource</a></li></ol></li><li class="section"><a href="a-demo-app.html#sec-microposts_resource"><span class="number">2.3</span> The Microposts resource</a></li><li><ol><li class="subsection"><a href="a-demo-app.html#sec-a_micropost_microtour"><span class="number">2.3.1</span> A micropost microtour</a></li><li class="subsection"><a href="a-demo-app.html#sec-putting_the_micro_in_microposts"><span class="number">2.3.2</span> Putting the <em>micro</em> in microposts</a></li><li class="subsection"><a href="a-demo-app.html#sec-demo_user_has_many_microposts"><span class="number">2.3.3</span> A user <tt>has_many</tt> microposts</a></li><li class="subsection"><a href="a-demo-app.html#sec-inheritance_hierarchies"><span class="number">2.3.4</span> Inheritance hierarchies</a></li><li class="subsection"><a href="a-demo-app.html#sec-deploying_the_demo_app"><span class="number">2.3.5</span> Deploying the demo app</a></li></ol></li><li class="section"><a href="a-demo-app.html#sec-2_4"><span class="number">2.4</span> Conclusion</a></li></ol></li><li class="chapter"><a href="static-pages.html#top"><span class="number">Chapter 3</span> Mostly static pages</a></li><li><ol><li class="section"><a href="static-pages.html#sec-static_pages"><span class="number">3.1</span> Static pages</a></li><li><ol><li class="subsection"><a href="static-pages.html#sec-truly_static_pages"><span class="number">3.1.1</span> Truly static pages</a></li><li class="subsection"><a href="static-pages.html#sec-static_pages_with_rails"><span class="number">3.1.2</span> Static pages with Rails</a></li></ol></li><li class="section"><a href="static-pages.html#sec-first_tests"><span class="number">3.2</span> Our first tests</a></li><li><ol><li class="subsection"><a href="static-pages.html#sec-TDD"><span class="number">3.2.1</span> Test-driven development</a></li><li class="subsection"><a href="static-pages.html#sec-adding_a_page"><span class="number">3.2.2</span> Adding a page</a></li><li><ol><li class="subsubsection"><a href="static-pages.html#sec-red">Red</a></li><li class="subsubsection"><a href="static-pages.html#sec-green">Green</a></li><li class="subsubsection"><a href="static-pages.html#sec-refactor">Refactor</a></li></ol></li></ol></li><li class="section"><a href="static-pages.html#sec-slightly_dynamic_pages"><span class="number">3.3</span> Slightly dynamic pages</a></li><li><ol><li class="subsection"><a href="static-pages.html#sec-testing_a_title_change"><span class="number">3.3.1</span> Testing a title change</a></li><li class="subsection"><a href="static-pages.html#sec-passing_title_tests"><span class="number">3.3.2</span> Passing title tests</a></li><li class="subsection"><a href="static-pages.html#sec-embedded_ruby"><span class="number">3.3.3</span> Embedded Ruby</a></li><li class="subsection"><a href="static-pages.html#sec-layouts"><span class="number">3.3.4</span> Eliminating duplication with layouts</a></li></ol></li><li class="section"><a href="static-pages.html#sec-static_pages_conclusion"><span class="number">3.4</span> Conclusion</a></li><li class="section"><a href="static-pages.html#sec-static_pages_exercises"><span class="number">3.5</span> Exercises</a></li><li class="section"><a href="static-pages.html#sec-advanced_setup"><span class="number">3.6</span> Advanced setup</a></li><li><ol><li class="subsection"><a href="static-pages.html#sec-eliminating_bundle_exec"><span class="number">3.6.1</span> Eliminating <tt>bundle exec</tt></a></li><li><ol><li class="subsubsection"><a href="static-pages.html#sec-rvm_bundler_integration">RVM Bundler integration</a></li><li class="subsubsection"><a href="static-pages.html#sec-binstubs">binstubs</a></li></ol></li><li class="subsection"><a href="static-pages.html#sec-guard"><span class="number">3.6.2</span> Automated tests with Guard</a></li><li class="subsection"><a href="static-pages.html#sec-spork"><span class="number">3.6.3</span> Speeding up tests with Spork</a></li><li><ol><li class="subsubsection"><a href="static-pages.html#sec-spork_and_guard">Guard with Spork</a></li></ol></li><li class="subsection"><a href="static-pages.html#sec-tests_inside_sublime_text"><span class="number">3.6.4</span> Tests inside Sublime Text</a></li></ol></li></ol></li><li class="chapter"><a href="rails-flavored-ruby.html#top"><span class="number">Chapter 4</span> Rails-flavored Ruby</a></li><li><ol><li class="section"><a href="rails-flavored-ruby.html#sec-motivation"><span class="number">4.1</span> Motivation</a></li><li class="section"><a href="rails-flavored-ruby.html#sec-strings_and_methods"><span class="number">4.2</span> Strings and methods</a></li><li><ol><li class="subsection"><a href="rails-flavored-ruby.html#sec-comments"><span class="number">4.2.1</span> Comments</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-strings"><span class="number">4.2.2</span> Strings</a></li><li><ol><li class="subsubsection"><a href="rails-flavored-ruby.html#sec-printing">Printing</a></li><li class="subsubsection"><a href="rails-flavored-ruby.html#sec-single_quoted_strings">Single-quoted strings</a></li></ol></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-objects_and_message_passing"><span class="number">4.2.3</span> Objects and message passing</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-method_definitions"><span class="number">4.2.4</span> Method definitions</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-back_to_the_title_helper"><span class="number">4.2.5</span> Back to the title helper</a></li></ol></li><li class="section"><a href="rails-flavored-ruby.html#sec-other_data_structures"><span class="number">4.3</span> Other data structures</a></li><li><ol><li class="subsection"><a href="rails-flavored-ruby.html#sec-arrays_and_ranges"><span class="number">4.3.1</span> Arrays and ranges</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-blocks"><span class="number">4.3.2</span> Blocks</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-hashes_and_symbols"><span class="number">4.3.3</span> Hashes and symbols</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-css_revisited"><span class="number">4.3.4</span> CSS revisited</a></li></ol></li><li class="section"><a href="rails-flavored-ruby.html#sec-ruby_classes"><span class="number">4.4</span> Ruby classes</a></li><li><ol><li class="subsection"><a href="rails-flavored-ruby.html#sec-constructors"><span class="number">4.4.1</span> Constructors</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-a_class_of_our_own"><span class="number">4.4.2</span> Class inheritance</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-modifying_built_in_classes"><span class="number">4.4.3</span> Modifying built-in classes</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-a_controller_class"><span class="number">4.4.4</span> A controller class</a></li><li class="subsection"><a href="rails-flavored-ruby.html#sec-a_user_class"><span class="number">4.4.5</span> A user class</a></li></ol></li><li class="section"><a href="rails-flavored-ruby.html#sec-conclusion"><span class="number">4.5</span> Conclusion</a></li><li class="section"><a href="rails-flavored-ruby.html#sec-exercises"><span class="number">4.6</span> Exercises</a></li></ol></li><li class="chapter"><a href="filling-in-the-layout.html#top"><span class="number">Chapter 5</span> Filling in the layout</a></li><li><ol><li class="section"><a href="filling-in-the-layout.html#sec-structure"><span class="number">5.1</span> Adding some structure</a></li><li><ol><li class="subsection"><a href="filling-in-the-layout.html#sec-adding_to_the_layout"><span class="number">5.1.1</span> Site navigation</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-custom_css"><span class="number">5.1.2</span> Bootstrap and custom CSS</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-partials"><span class="number">5.1.3</span> Partials</a></li></ol></li><li class="section"><a href="filling-in-the-layout.html#sec-sass_and_the_asset_pipeline"><span class="number">5.2</span> Sass and the asset pipeline</a></li><li><ol><li class="subsection"><a href="filling-in-the-layout.html#sec-the_asset_pipeline"><span class="number">5.2.1</span> The asset pipeline</a></li><li><ol><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_1_1">Asset directories</a></li><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_1_2">Manifest files</a></li><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_1_3">Preprocessor engines</a></li><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_1_4">Efficiency in production</a></li></ol></li><li class="subsection"><a href="filling-in-the-layout.html#sec-sass"><span class="number">5.2.2</span> Syntactically awesome stylesheets</a></li><li><ol><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_2_1">Nesting</a></li><li class="subsubsection"><a href="filling-in-the-layout.html#sec-5_2_2_2">Variables</a></li></ol></li></ol></li><li class="section"><a href="filling-in-the-layout.html#sec-layout_links"><span class="number">5.3</span> Layout links</a></li><li><ol><li class="subsection"><a href="filling-in-the-layout.html#sec-route_tests"><span class="number">5.3.1</span> Route tests</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-rails_routes"><span class="number">5.3.2</span> Rails routes</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-named_routes"><span class="number">5.3.3</span> Named routes</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-pretty_rspec"><span class="number">5.3.4</span> Pretty RSpec</a></li></ol></li><li class="section"><a href="filling-in-the-layout.html#sec-user_signup"><span class="number">5.4</span> User signup: A first step</a></li><li><ol><li class="subsection"><a href="filling-in-the-layout.html#sec-users_controller"><span class="number">5.4.1</span> Users controller</a></li><li class="subsection"><a href="filling-in-the-layout.html#sec-signup_url"><span class="number">5.4.2</span> Signup URI</a></li></ol></li><li class="section"><a href="filling-in-the-layout.html#sec-layout_conclusion"><span class="number">5.5</span> Conclusion</a></li><li class="section"><a href="filling-in-the-layout.html#sec-layout_exercises"><span class="number">5.6</span> Exercises</a></li></ol></li><li class="chapter"><a href="modeling-users.html#top"><span class="number">Chapter 6</span> Modeling users</a></li><li><ol><li class="section"><a href="modeling-users.html#sec-user_model"><span class="number">6.1</span> User model</a></li><li><ol><li class="subsection"><a href="modeling-users.html#sec-database_migrations"><span class="number">6.1.1</span> Database migrations</a></li><li class="subsection"><a href="modeling-users.html#sec-the_model_file"><span class="number">6.1.2</span> The model file</a></li><li><ol><li class="subsubsection"><a href="modeling-users.html#sec-model_annotation">Model annotation</a></li><li class="subsubsection"><a href="modeling-users.html#sec-accessible_attributes">Accessible attributes</a></li></ol></li><li class="subsection"><a href="modeling-users.html#sec-creating_user_objects"><span class="number">6.1.3</span> Creating user objects</a></li><li class="subsection"><a href="modeling-users.html#sec-finding_user_objects"><span class="number">6.1.4</span> Finding user objects</a></li><li class="subsection"><a href="modeling-users.html#sec-updating_user_objects"><span class="number">6.1.5</span> Updating user objects</a></li></ol></li><li class="section"><a href="modeling-users.html#sec-user_validations"><span class="number">6.2</span> User validations</a></li><li><ol><li class="subsection"><a href="modeling-users.html#sec-initial_user_tests"><span class="number">6.2.1</span> Initial user tests</a></li><li class="subsection"><a href="modeling-users.html#sec-presence_validation"><span class="number">6.2.2</span> Validating presence</a></li><li class="subsection"><a href="modeling-users.html#sec-length_validation"><span class="number">6.2.3</span> Length validation</a></li><li class="subsection"><a href="modeling-users.html#sec-format_validation"><span class="number">6.2.4</span> Format validation</a></li><li class="subsection"><a href="modeling-users.html#sec-uniqueness_validation"><span class="number">6.2.5</span> Uniqueness validation</a></li><li><ol><li class="subsubsection"><a href="modeling-users.html#sec-the_caveat">The uniqueness caveat</a></li></ol></li></ol></li><li class="section"><a href="modeling-users.html#sec-adding_a_secure_password"><span class="number">6.3</span> Adding a secure password</a></li><li><ol><li class="subsection"><a href="modeling-users.html#sec-an_encrypted_password"><span class="number">6.3.1</span> An encrypted password</a></li><li class="subsection"><a href="modeling-users.html#sec-password_and_confirmation"><span class="number">6.3.2</span> Password and confirmation</a></li><li class="subsection"><a href="modeling-users.html#sec-user_authentication"><span class="number">6.3.3</span> User authentication</a></li><li class="subsection"><a href="modeling-users.html#sec-has_secure_password"><span class="number">6.3.4</span> User has secure password</a></li><li class="subsection"><a href="modeling-users.html#sec-creating_a_user"><span class="number">6.3.5</span> Creating a user</a></li></ol></li><li class="section"><a href="modeling-users.html#sec-6_4"><span class="number">6.4</span> Conclusion</a></li><li class="section"><a href="modeling-users.html#sec-6_5"><span class="number">6.5</span> Exercises</a></li></ol></li><li class="chapter"><a href="sign-up.html#top"><span class="number">Chapter 7</span> Sign up</a></li><li><ol><li class="section"><a href="sign-up.html#sec-showing_users"><span class="number">7.1</span> Showing users</a></li><li><ol><li class="subsection"><a href="sign-up.html#sec-rails_environments"><span class="number">7.1.1</span> Debug and Rails environments</a></li><li class="subsection"><a href="sign-up.html#sec-a_users_resource"><span class="number">7.1.2</span> A Users resource</a></li><li class="subsection"><a href="sign-up.html#sec-tests_with_factories"><span class="number">7.1.3</span> Testing the user show page (with factories)</a></li><li class="subsection"><a href="sign-up.html#sec-a_gravatar_image"><span class="number">7.1.4</span> A Gravatar image and a sidebar</a></li></ol></li><li class="section"><a href="sign-up.html#sec-signup_form"><span class="number">7.2</span> Signup form</a></li><li><ol><li class="subsection"><a href="sign-up.html#sec-tests_for_user_signup"><span class="number">7.2.1</span> Tests for user signup</a></li><li class="subsection"><a href="sign-up.html#sec-using_form_for"><span class="number">7.2.2</span> Using <tt>form_for</tt></a></li><li class="subsection"><a href="sign-up.html#sec-the_form_html"><span class="number">7.2.3</span> The form HTML</a></li></ol></li><li class="section"><a href="sign-up.html#sec-signup_failure"><span class="number">7.3</span> Signup failure</a></li><li><ol><li class="subsection"><a href="sign-up.html#sec-a_working_form"><span class="number">7.3.1</span> A working form</a></li><li class="subsection"><a href="sign-up.html#sec-signup_error_messages"><span class="number">7.3.2</span> Signup error messages</a></li></ol></li><li class="section"><a href="sign-up.html#sec-signup_success"><span class="number">7.4</span> Signup success</a></li><li><ol><li class="subsection"><a href="sign-up.html#sec-the_finished_signup_form"><span class="number">7.4.1</span> The finished signup form</a></li><li class="subsection"><a href="sign-up.html#sec-the_flash"><span class="number">7.4.2</span> The flash</a></li><li class="subsection"><a href="sign-up.html#sec-the_first_signup"><span class="number">7.4.3</span> The first signup</a></li><li class="subsection"><a href="sign-up.html#sec-deploying_to_production_with_ssl"><span class="number">7.4.4</span> Deploying to production with SSL</a></li></ol></li><li class="section"><a href="sign-up.html#sec-7_5"><span class="number">7.5</span> Conclusion</a></li><li class="section"><a href="sign-up.html#sec-signup_exercises"><span class="number">7.6</span> Exercises</a></li></ol></li><li class="chapter"><a href="sign-in-sign-out.html#top"><span class="number">Chapter 8</span> Sign in, sign out</a></li><li><ol><li class="section"><a href="sign-in-sign-out.html#sec-signin_failure"><span class="number">8.1</span> Sessions and signin failure</a></li><li><ol><li class="subsection"><a href="sign-in-sign-out.html#sec-sessions_controller"><span class="number">8.1.1</span> Sessions controller</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-signin_tests"><span class="number">8.1.2</span> Signin tests</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-signin_form"><span class="number">8.1.3</span> Signin form</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-reviewing_form_submission"><span class="number">8.1.4</span> Reviewing form submission</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-rendering_with_a_flash_message"><span class="number">8.1.5</span> Rendering with a flash message</a></li></ol></li><li class="section"><a href="sign-in-sign-out.html#sec-signin_success"><span class="number">8.2</span> Signin success</a></li><li><ol><li class="subsection"><a href="sign-in-sign-out.html#sec-remember_me"><span class="number">8.2.1</span> Remember me</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-a_working_sign_in_method"><span class="number">8.2.2</span> A working <tt>sign_in</tt> method</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-current_user"><span class="number">8.2.3</span> Current user</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-changing_the_layout_links"><span class="number">8.2.4</span> Changing the layout links</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-signin_upon_signup"><span class="number">8.2.5</span> Signin upon signup</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-signing_out"><span class="number">8.2.6</span> Signing out</a></li></ol></li><li class="section"><a href="sign-in-sign-out.html#sec-cucumber"><span class="number">8.3</span> Introduction to Cucumber (optional)</a></li><li><ol><li class="subsection"><a href="sign-in-sign-out.html#sec-installation_and_setup"><span class="number">8.3.1</span> Installation and setup</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-features_and_steps"><span class="number">8.3.2</span> Features and steps</a></li><li class="subsection"><a href="sign-in-sign-out.html#sec-rspec_custom_matchers"><span class="number">8.3.3</span> Counterpoint: RSpec custom matchers</a></li></ol></li><li class="section"><a href="sign-in-sign-out.html#sec-8_4"><span class="number">8.4</span> Conclusion</a></li><li class="section"><a href="sign-in-sign-out.html#sec-sign_in_out_exercises"><span class="number">8.5</span> Exercises</a></li></ol></li><li class="chapter"><a href="updating-showing-and-deleting-users.html#top"><span class="number">Chapter 9</span> Updating, showing, and deleting users</a></li><li><ol><li class="section"><a href="updating-showing-and-deleting-users.html#sec-updating_users"><span class="number">9.1</span> Updating users</a></li><li><ol><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-edit_form"><span class="number">9.1.1</span> Edit form</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-unsuccessful_edits"><span class="number">9.1.2</span> Unsuccessful edits</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-successful_edits"><span class="number">9.1.3</span> Successful edits</a></li></ol></li><li class="section"><a href="updating-showing-and-deleting-users.html#sec-authorization"><span class="number">9.2</span> Authorization</a></li><li><ol><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-requiring_signed_in_users"><span class="number">9.2.1</span> Requiring signed-in users</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-requiring_the_right_user"><span class="number">9.2.2</span> Requiring the right user</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-friendly_forwarding"><span class="number">9.2.3</span> Friendly forwarding</a></li></ol></li><li class="section"><a href="updating-showing-and-deleting-users.html#sec-showing_all_users"><span class="number">9.3</span> Showing all users</a></li><li><ol><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-user_index"><span class="number">9.3.1</span> User index</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-sample_users"><span class="number">9.3.2</span> Sample users</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-pagination"><span class="number">9.3.3</span> Pagination</a></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-partial_refactoring"><span class="number">9.3.4</span> Partial refactoring</a></li></ol></li><li class="section"><a href="updating-showing-and-deleting-users.html#sec-destroying_users"><span class="number">9.4</span> Deleting users</a></li><li><ol><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-administrative_users"><span class="number">9.4.1</span> Administrative users</a></li><li><ol><li class="subsubsection"><a href="updating-showing-and-deleting-users.html#sec-revisiting_attr_accessible">Revisiting <tt>attr_accessible</tt></a></li></ol></li><li class="subsection"><a href="updating-showing-and-deleting-users.html#sec-the_destroy_action"><span class="number">9.4.2</span> The <tt>destroy</tt> action</a></li></ol></li><li class="section"><a href="updating-showing-and-deleting-users.html#sec-updating_and_deleting_users_conclusion"><span class="number">9.5</span> Conclusion</a></li><li class="section"><a href="updating-showing-and-deleting-users.html#sec-updating_deleting_exercises"><span class="number">9.6</span> Exercises</a></li></ol></li><li class="chapter"><a href="user-microposts.html#top"><span class="number">Chapter 10</span> User microposts</a></li><li><ol><li class="section"><a href="user-microposts.html#sec-a_micropost_model"><span class="number">10.1</span> A Micropost model</a></li><li><ol><li class="subsection"><a href="user-microposts.html#sec-the_basic_model"><span class="number">10.1.1</span> The basic model</a></li><li class="subsection"><a href="user-microposts.html#sec-accessible_attribute"><span class="number">10.1.2</span> Accessible attributes and the first validation</a></li><li class="subsection"><a href="user-microposts.html#sec-user_micropost_associations"><span class="number">10.1.3</span> User/Micropost associations</a></li><li class="subsection"><a href="user-microposts.html#sec-ordering_and_dependency"><span class="number">10.1.4</span> Micropost refinements</a></li><li><ol><li class="subsubsection"><a href="user-microposts.html#sec-default_scope">Default scope</a></li><li class="subsubsection"><a href="user-microposts.html#sec-dependent_destroy">Dependent: destroy</a></li></ol></li><li class="subsection"><a href="user-microposts.html#sec-micropost_validations"><span class="number">10.1.5</span> Content validations</a></li></ol></li><li class="section"><a href="user-microposts.html#sec-showing_microposts"><span class="number">10.2</span> Showing microposts</a></li><li><ol><li class="subsection"><a href="user-microposts.html#sec-augmenting_the_user_show_page"><span class="number">10.2.1</span> Augmenting the user show page</a></li><li class="subsection"><a href="user-microposts.html#sec-sample_microposts"><span class="number">10.2.2</span> Sample microposts</a></li></ol></li><li class="section"><a href="user-microposts.html#sec-manipulating_microposts"><span class="number">10.3</span> Manipulating microposts</a></li><li><ol><li class="subsection"><a href="user-microposts.html#sec-access_control"><span class="number">10.3.1</span> Access control</a></li><li class="subsection"><a href="user-microposts.html#sec-creating_microposts"><span class="number">10.3.2</span> Creating microposts</a></li><li class="subsection"><a href="user-microposts.html#sec-a_proto_feed"><span class="number">10.3.3</span> A proto-feed</a></li><li class="subsection"><a href="user-microposts.html#sec-destroying_microposts"><span class="number">10.3.4</span> Destroying microposts</a></li></ol></li><li class="section"><a href="user-microposts.html#sec-10_4"><span class="number">10.4</span> Conclusion</a></li><li class="section"><a href="user-microposts.html#sec-micropost_exercises"><span class="number">10.5</span> Exercises</a></li></ol></li><li class="chapter"><a href="following-users.html#top"><span class="number">Chapter 11</span> Following users</a></li><li><ol><li class="section"><a href="following-users.html#sec-the_relationship_model"><span class="number">11.1</span> The Relationship model</a></li><li><ol><li class="subsection"><a href="following-users.html#sec-a_problem_with_the_data_model"><span class="number">11.1.1</span> A problem with the data model (and a solution)</a></li><li class="subsection"><a href="following-users.html#sec-relationship_user_associations"><span class="number">11.1.2</span> User/relationship associations</a></li><li class="subsection"><a href="following-users.html#sec-relationship_validations"><span class="number">11.1.3</span> Validations</a></li><li class="subsection"><a href="following-users.html#sec-following"><span class="number">11.1.4</span> Followed users</a></li><li class="subsection"><a href="following-users.html#sec-followers"><span class="number">11.1.5</span> Followers</a></li></ol></li><li class="section"><a href="following-users.html#sec-a_web_interface_for_following_and_followers"><span class="number">11.2</span> A web interface for following users</a></li><li><ol><li class="subsection"><a href="following-users.html#sec-sample_following_data"><span class="number">11.2.1</span> Sample following data</a></li><li class="subsection"><a href="following-users.html#sec-stats_and_a_follow_form"><span class="number">11.2.2</span> Stats and a follow form</a></li><li class="subsection"><a href="following-users.html#sec-following_and_followers_pages"><span class="number">11.2.3</span> Following and followers pages</a></li><li class="subsection"><a href="following-users.html#sec-a_working_follow_button_the_standard_way"><span class="number">11.2.4</span> A working follow button the standard way</a></li><li class="subsection"><a href="following-users.html#sec-a_working_follow_button_with_ajax"><span class="number">11.2.5</span> A working follow button with Ajax</a></li></ol></li><li class="section"><a href="following-users.html#sec-the_status_feed"><span class="number">11.3</span> The status feed</a></li><li><ol><li class="subsection"><a href="following-users.html#sec-motivation_and_strategy"><span class="number">11.3.1</span> Motivation and strategy</a></li><li class="subsection"><a href="following-users.html#sec-a_first_feed_implementation"><span class="number">11.3.2</span> A first feed implementation</a></li><li class="subsection"><a href="following-users.html#sec-scopes_subselects_and_a_lambda"><span class="number">11.3.3</span> Subselects</a></li><li class="subsection"><a href="following-users.html#sec-the_new_status_feed"><span class="number">11.3.4</span> The new status feed</a></li></ol></li><li class="section"><a href="following-users.html#sec-following_conclusion"><span class="number">11.4</span> Conclusion</a></li><li><ol><li class="subsection"><a href="following-users.html#sec-extensions_to_the_sample_application"><span class="number">11.4.1</span> Extensions to the sample application</a></li><li><ol><li class="subsubsection"><a href="following-users.html#sec-replies">Replies</a></li><li class="subsubsection"><a href="following-users.html#sec-messaging">Messaging</a></li><li class="subsubsection"><a href="following-users.html#sec-follower_notifications">Follower notifications</a></li><li class="subsubsection"><a href="following-users.html#sec-password_reminders">Password reminders</a></li><li class="subsubsection"><a href="following-users.html#sec-signup_confirmation">Signup confirmation</a></li><li class="subsubsection"><a href="following-users.html#sec-rss_feed">RSS feed</a></li><li class="subsubsection"><a href="following-users.html#sec-rest_api">REST API</a></li><li class="subsubsection"><a href="following-users.html#sec-search">Search</a></li></ol></li><li class="subsection"><a href="following-users.html#sec-guide_to_further_resources"><span class="number">11.4.2</span> Guide to further resources</a></li></ol></li><li class="section"><a href="following-users.html#sec-following_exercises"><span class="number">11.5</span> Exercises</a></li></ol></li><li class="chapter"><a href="supplement.html#top"><span class="number">Chapter 12</span> Rails 4.0 supplement</a></li><li><ol><li class="section"><a href="supplement.html#sec-upgrading_from_rails_3_2_to_4_0"><span class="number">12.1</span> Upgrading from Rails 3.2 to 4.0</a></li><li><ol><li class="subsection"><a href="supplement.html#sec-rails_4_0_setup"><span class="number">12.1.1</span> Rails 4.0 setup</a></li><li class="subsection"><a href="supplement.html#sec-getting_to_green"><span class="number">12.1.2</span> Getting to green</a></li><li class="subsection"><a href="supplement.html#sec-some_specific_issues"><span class="number">12.1.3</span> Some specific issues</a></li><li><ol><li class="subsubsection"><a href="supplement.html#sec-models">Models</a></li><li class="subsubsection"><a href="supplement.html#sec-controllers_and_views">Controllers and views</a></li></ol></li><li class="subsection"><a href="supplement.html#sec-finishing_up"><span class="number">12.1.4</span> Finishing up</a></li><li class="subsection"><a href="supplement.html#sec-additional_resources"><span class="number">12.1.5</span> Additional resources</a></li></ol></li><li class="section"><a href="supplement.html#sec-strong_parameters"><span class="number">12.2</span> Strong parameters</a></li><li class="section"><a href="supplement.html#sec-security_updates"><span class="number">12.3</span> Security updates</a></li><li><ol><li class="subsection"><a href="supplement.html#sec-secret_key"><span class="number">12.3.1</span> Secret key</a></li><li class="subsection"><a href="supplement.html#sec-encrypted_remember_tokens"><span class="number">12.3.2</span> Hashed remember tokens</a></li></ol></li></ol></li></ol></div>
<div id="main_content"></div>
<p> <span class="preamble">
<span id="foreword">
<strong> Foreword</strong> <br />
</span>
</span></p>
<p>My former company (CD Baby) was one of the first to loudly switch to Ruby on Rails, and then even more loudly switch back to PHP (Google me to read about the drama). This book by Michael Hartl came so highly recommended that I had to try it, and the <em>Ruby on Rails Tutorial</em> is what I used to switch back to Rails again.</p>
<p>Though I’ve worked my way through many Rails books, this is the one that finally made me “get” it. Everything is done very much “the Rails way”—a way that felt very unnatural to me before, but now after doing this book finally feels natural. This is also the only Rails book that does test-driven development the entire time, an approach highly recommended by the experts but which has never been so clearly demonstrated before. Finally, by including Git, GitHub, and Heroku in the demo examples, the author really gives you a feel for what it’s like to do a real-world project. The tutorial’s code examples are not in isolation.</p>
<p>The linear narrative is such a great format. Personally, I powered through the <em>Rails Tutorial</em> in three long days, doing all the examples and challenges at the end of each chapter. Do it from start to finish, without jumping around, and you’ll get the ultimate benefit.</p>
<p>Enjoy!</p>
<p><a href="http://sivers.org/">Derek Sivers</a> (<a href="http://sivers.org/">sivers.org</a>) <br />
<em>Founder, CD Baby</em> <br /></p>
<p> <span class="preamble">
<strong> Acknowledgments</strong> <br />
</span></p>
<p>The <em>Ruby on Rails Tutorial</em> owes a lot to my previous Rails book, <em>RailsSpace</em>, and hence to my coauthor <a href="http://aure.com/">Aurelius Prochazka</a>. I’d like to thank Aure both for the work he did on that book and for his support of this one. I’d also like to thank Debra Williams Cauley, my editor on both <em>RailsSpace</em> and the <em>Ruby on Rails Tutorial</em>; as long as she keeps taking me to baseball games, I’ll keep writing books for her.</p>
<p>I’d like to acknowledge a long list of Rubyists who have taught and inspired me over the years: David Heinemeier Hansson, Yehuda Katz, Carl Lerche, Jeremy Kemper, Xavier Noria, Ryan Bates, Geoffrey Grosenbach, Peter Cooper, Matt Aimonetti, Gregg Pollack, Wayne E. Seguin, Amy Hoy, Dave Chelimsky, Pat Maddox, Tom Preston-Werner, Chris Wanstrath, Chad Fowler, Josh Susser, Obie Fernandez, Ian McFarland, Steven Bristol, Pratik Naik, Sarah Mei, Sarah Allen, Wolfram Arnold, Alex Chaffee, Giles Bowkett, Evan Dorn, Long Nguyen, James Lindenbaum, Adam Wiggins, Tikhon Bernstam, Ron Evans, Wyatt Greene, Miles Forrest, the good people at Pivotal Labs, the Heroku gang, the thoughtbot guys, and the GitHub crew. Finally, many, many readers—far too many to list—have contributed a huge number of bug reports and suggestions during the writing of this book, and I gratefully acknowledge their help in making it as good as it can be. <br /></p>
<p> <span class="preamble">
<span id="author">
<strong> About the author</strong> <br />
</span>
</span></p>
<p><a href="http://michaelhartl.com/">Michael Hartl</a> is the author of the <a href="http://ruby.railstutorial.org/"><em>Ruby on Rails Tutorial</em></a>, the leading introduction to web development with <a href="http://rubyonrails.org/">Ruby on Rails</a>. His prior experience includes writing and developing <em>RailsSpace</em>, an extremely obsolete Rails tutorial book, and developing Insoshi, a once-popular and now-obsolete social networking platform in Ruby on Rails. In 2011, Michael received a <a href="http://rubyheroes.com/heroes">Ruby Hero Award</a> for his contributions to the Ruby community. He is a graduate of <a href="http://college.harvard.edu/">Harvard College</a>, has a <a href="http://resolver.caltech.edu/CaltechETD:etd-05222003-161626">Ph.D. in Physics</a> from <a href="http://www.caltech.edu/">Caltech</a>, and is an alumnus of the <a href="http://ycombinator.com/">Y Combinator</a> entrepreneur program. <br /></p>
<p> <span id="license" class="preamble">
<strong> Copyright and license</strong> <br />
</span></p>
<p><em>Ruby on Rails Tutorial: Learn Web Development with Rails</em>. Copyright © 2012 by Michael Hartl. All source code in the <em>Ruby on Rails Tutorial</em> is available jointly under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a> and the <a href="http://people.freebsd.org/~phk/">Beerware License</a>.</p>
<div class="code"><div class="highlight"><pre>The MIT License
Copyright (c) 2012 Michael Hartl
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
</pre></div>
</div>
<div class="code"><div class="highlight"><pre>/*
* ----------------------------------------------------------------------------
* "THE BEER-WARE LICENSE" (Revision 42):
* Michael Hartl wrote this code. As long as you retain this notice you
* can do whatever you want with this stuff. If we meet some day, and you think
* this stuff is worth it, you can buy me a beer in return.
* ----------------------------------------------------------------------------
*/
</pre></div>
</div>
<div id="top"></div>
<h1 class="chapter"><a id="sec-1" href="beginning.html#top" class="heading"><span class="number">Chapter 1</span> From zero to deploy</a></h1>
<p>Welcome to the <a href="http://ruby.railstutorial.org/ruby-on-rails-tutorial-book"><em>Ruby on Rails Tutorial</em></a>. The goal of this book is to be the best answer to the question, “If I want to learn web development with <a href="http://rubyonrails.org/">Ruby on Rails</a>, where should I start?” By the time you finish the <em>Ruby on Rails Tutorial</em>, you will have all the skills you need to develop and deploy your own custom web applications with Rails. You will also be ready to benefit from the many more advanced books, blogs, and screencasts that are part of the thriving Rails educational ecosystem. Finally, since the <em>Ruby on Rails Tutorial</em> uses Rails 3, the knowledge you gain here represents the state of the art in web development (<a class="ref" href="beginning.html#sidebar-rails_3_4">Box 1.1</a>). (The most up-to-date version of the <em>Ruby on Rails Tutorial</em> can be found on the book’s website at <a href="http://railstutorial.org/">http://railstutorial.org/</a>; if you are reading this book offline, be sure to check the <a href="http://railstutorial.org/book?version=3.2">online version of the Rails Tutorial book</a> at <a href="http://railstutorial.org/book?version=3.2">http://railstutorial.org/book?version=3.2</a> for the latest updates.)</p>
<div class="label" id="sidebar-rails_3_4"></div>
<div class="sidebar"><span class="title"><span class="header">Box 1.1.</span><span class="description">Rails 3 or Rails 4?</span></span>
<p>As of this writing, both Rails 3.2 and Rails 4.0 are officially supported versions of Rails, so the question naturally arises whether it might be better to start with the latest version (Rails 4.0) rather than the one used in this tutorial (Rails 3.2). The answer depends on your background, but if you have never used Rails before I suggest using Rails 3.2. This is partially because the Rails 4.0 ecosystem is still somewhat unstable; in addition, the differences between the two versions are slight, with only the introduction of so-called “strong parameters” representing a significant change from the perspective of an introductory tutorial.</p>
<p>In order to ease the transition to Rails 4.0, both this book and the <a href="http://railstutorial.org/screencasts">Rails Tutorial screencasts</a> contain supplementary material on upgrading to Rails 4.0, as well an additional discussion of strong parameters and important security updates (<a class="ref" href="supplement.html#top">Chapter 12</a>). My recommendation is to learn web development first with Rails 3.2 (using the book and optionally the screencasts), and then use the supplement to learn the small number of things needed to bring your knowledge up to date with Rails 4.0.</p>
<p>On the other hand, if you already have a background in Rails and want to live on the bleeding edge, you are welcome to use the <a href="http://railstutorial.org/book?version=4.0">Rails 4.0 version of the <em>Rails Tutorial</em></a>, which uses Rails 4.0 throughout. <a href="http://railstutorial.org/chapters/beginning?version=4.0#sidebar-diffs">Box 1.1 of the 4.0 version</a> also contains a nearly comprehensive (but still quite short) list of the differences between the Rails 3.2 and Rails 4.0 versions of the book.</p>
</div>
<p>Note that the goal of this book is <em>not</em> merely to teach Rails, but rather to teach <em>web development with Rails</em>, which means acquiring (or expanding) the skills needed to develop software for the World Wide Web. In addition to Ruby on Rails, this skillset includes HTML & CSS, databases, version control, testing, and deployment. To accomplish this goal, the <em>Ruby on Rails Tutorial</em> takes an integrated approach: you will learn Rails by example by building a substantial sample application from scratch. As <a href="http://sivers.org">Derek Sivers</a> notes in the foreword, this book is structured as a linear narrative, designed to be read from start to finish. If you are used to skipping around in technical books, taking this linear approach might require some adjustment, but I suggest giving it a try. You can think of the <em>Ruby on Rails Tutorial</em> as a video game where you are the main character, and where you level up as a Rails developer in each chapter. (The exercises are the <a href="http://en.wikipedia.org/wiki/Boss_(video_gaming)#Miniboss">minibosses</a>.)</p>
<p>In this first chapter, we’ll get started with Ruby on Rails by installing all the necessary software and by setting up our development environment (<a class="ref" href="beginning.html#sec-up_and_running">Section 1.2</a>). We’ll then create our first Rails application, called (appropriately enough) <code>first_app</code>. The <em>Rails Tutorial</em> emphasizes good software development practices, so immediately after creating our fresh new Rails project we’ll put it under version control with Git (<a class="ref" href="beginning.html#sec-version_control">Section 1.3</a>). And, believe it or not, in this chapter we’ll even put our first app on the wider web by <em>deploying</em> it to production (<a class="ref" href="beginning.html#sec-deploying">Section 1.4</a>).</p>
<p>In <a class="ref" href="a-demo-app.html#top">Chapter 2</a>, we’ll make a second project, whose purpose is to demonstrate the basic workings of a Rails application. To get up and running quickly, we’ll build this <em>demo app</em> (called <code>demo_app</code>) using scaffolding (<a class="ref" href="beginning.html#sidebar-scaffolding">Box 1.2</a>) to generate code; since this code is both ugly and complex, <a class="ref" href="a-demo-app.html#top">Chapter 2</a> will focus on interacting with the demo app through its <em>URIs</em> (sometimes called <em>URLs</em>)<sup class="footnote" id="fnref-1_1"><a href="#fn-1_1">1</a></sup> using a web browser.</p>
<p>The rest of the tutorial focuses on developing a single large <em>sample application</em> (called <code>sample_app</code>), writing all the code from scratch. We’ll develop the sample app using <em>test-driven development</em> (TDD), getting started in <a class="ref" href="static-pages.html#top">Chapter 3</a> by creating static pages and then adding a little dynamic content. We’ll take a quick detour in <a class="ref" href="rails-flavored-ruby.html#top">Chapter 4</a> to learn a little about the Ruby language underlying Rails. Then, in <a class="ref" href="filling-in-the-layout.html#top">Chapter 5</a> through <a class="ref" href="updating-showing-and-deleting-users.html#top">Chapter 9</a>, we’ll complete the foundation for the sample application by making a site layout, a user data model, and a full registration and authentication system. Finally, in <a class="ref" href="user-microposts.html#top">Chapter 10</a> and <a class="ref" href="following-users.html#top">Chapter 11</a> we’ll add microblogging and social features to make a working example site.</p>
<p>The final sample application will bear more than a passing resemblance to a certain popular <a href="http://twitter.com/">social microblogging site</a>—a site which, coincidentally, was also originally written in Rails. Though of necessity our efforts will focus on this specific sample application, the emphasis throughout the <em>Rails Tutorial</em> will be on general principles, so that you will have a solid foundation no matter what kinds of web applications you want to build.</p>
<div class="label" id="sidebar-scaffolding"></div>
<div class="sidebar"><span class="title"><span class="header">Box 1.2.</span><span class="description">Scaffolding: Quicker, easier, more seductive</span></span>
<p>From the beginning, Rails has benefited from a palpable sense of excitement, starting with the famous <a href="http://www.youtube.com/watch?v=Gzj723LkRJY">15-minute weblog video</a> by Rails creator David Heinemeier Hansson. That video and its successors are a great way to get a taste of Rails’ power, and I recommend watching them. But be warned: they accomplish their amazing fifteen-minute feat using a feature called <em>scaffolding</em>, which relies heavily on <em>generated code</em>, magically created by the Rails <code>generate</code> command.</p>
<p>When writing a Ruby on Rails tutorial, it is tempting to rely on the scaffolding approach—it’s <a href="http://en.wikipedia.org/wiki/Dark_side_(Star_Wars)">quicker, easier, more seductive</a>. But the complexity and sheer amount of code in the scaffolding can be utterly overwhelming to a beginning Rails developer; you may be able to use it, but you probably won’t understand it. Following the scaffolding approach risks turning you into a virtuoso script generator with little (and brittle) actual knowledge of Rails.</p>
<p>In the <em>Ruby on Rails Tutorial</em>, we’ll take the (nearly) polar opposite approach: although <a class="ref" href="a-demo-app.html#top">Chapter 2</a> will develop a small demo app using scaffolding, the core of the <em>Rails Tutorial</em> is the sample app, which we’ll start writing in <a class="ref" href="static-pages.html#top">Chapter 3</a>. At each stage of developing the sample application, we will write <em>small, bite-sized</em> pieces of code—simple enough to understand, yet novel enough to be challenging. The cumulative effect will be a deeper, more flexible knowledge of Rails, giving you a good background for writing nearly any type of web application.</p>
</div>
<div class="label" id="sec-introduction"></div>
<h2><a id="sec-1_1" href="beginning.html#sec-introduction" class="heading"><span class="number">1.1</span> Introduction</a></h2>
<p>Since its debut in 2004, Ruby on Rails has rapidly become one of the most powerful and popular frameworks for building dynamic web applications. Everyone from scrappy startups to huge companies have used Rails: <a href="http://37signals.com/">37signals</a>, <a href="http://github.com/">GitHub</a>, <a href="http://shopify.com/">Shopify</a>, <a href="http://scribd.com/">Scribd</a>, <a href="http://twitter.com/">Twitter</a>, <a href="http://livingsocial.com/">LivingSocial</a>, <a href="http://groupon.com/">Groupon</a>, <a href="http://hulu.com/">Hulu</a>, the <a href="http://yellowpages.com/">Yellow Pages</a>—the <a href="http://rubyonrails.org/applications">list of sites using Rails</a> goes on and on. There are also many web development shops that specialize in Rails, such as <a href="http://entp.com/">ENTP</a>, <a href="http://thoughtbot.com/">thoughtbot</a>, <a href="http://pivotallabs.com/">Pivotal Labs</a>, and <a href="http://hashrocket.com/">Hashrocket</a>, plus innumerable independent consultants, trainers, and contractors.</p>
<p>What makes Rails so great? First of all, Ruby on Rails is 100% open-source, available under the permissive <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, and as a result it also costs nothing to download or use. Rails also owes much of its success to its elegant and compact design; by exploiting the malleability of the underlying <a href="http://ruby-lang.org/">Ruby</a> language, Rails effectively creates a <a href="http://en.wikipedia.org/wiki/Domain_Specific_Language">domain-specific language</a> for writing web applications. As a result, many common web programming tasks—such as generating HTML, making data models, and routing URIs—are easy with Rails, and the resulting application code is concise and readable.</p>
<p>Rails also adapts rapidly to new developments in web technology and framework design. For example, Rails was one of the first frameworks to fully digest and implement the REST architectural style for structuring web applications (which we’ll be learning about throughout this tutorial). And when other frameworks develop successful new techniques, Rails creator <a href="http://loudthinking.com/">David Heinemeier Hansson</a> and the <a href="http://rubyonrails.org/core">Rails core team</a> don’t hesitate to incorporate their ideas. Perhaps the most dramatic example is the merger of Rails and Merb, a rival Ruby web framework, so that Rails now benefits from Merb’s modular design, stable <a href="http://en.wikipedia.org/wiki/Application_programming_interface">API</a>, and improved performance.</p>
<p>Finally, Rails benefits from an unusually enthusiastic and diverse community. The results include hundreds of open-source <a href="http://contributors.rubyonrails.org/">contributors</a>, well-attended <a href="http://railsconf.com/">conferences</a>, a huge number of <a href="http://agilewebdevelopment.com/plugins">plugins</a> and <a href="https://rubygems.org/">gems</a> (self-contained solutions to specific problems such as pagination and image upload), a rich variety of informative blogs, and a cornucopia of discussion forums and IRC channels. The large number of Rails programmers also makes it easier to handle the inevitable application errors: the “Google the error message” algorithm nearly always produces a relevant blog post or discussion-forum thread.</p>
<div class="label" id="sec-comments_for_various_readers"></div>
<h3><a id="sec-1_1_1" href="beginning.html#sec-comments_for_various_readers" class="heading"><span class="number">1.1.1</span> Comments for various readers</a></h3>
<p>The <em>Rails Tutorial</em> contains integrated tutorials not only for Rails, but also for the underlying Ruby language, the RSpec testing framework, <a href="http://en.wikipedia.org/wiki/HTML">HTML</a>, <a href="http://en.wikipedia.org/wiki/CSS">CSS</a>, a small amount of <a href="http://en.wikipedia.org/wiki/JavaScript">JavaScript</a>, and even a little <a href="http://en.wikipedia.org/wiki/SQL">SQL</a>. This means that, no matter where you currently are in your knowledge of web development, by the time you finish this tutorial you will be ready for more advanced Rails resources, as well as for the more systematic treatments of the other subjects mentioned. It also means that there’s a <em>lot</em> of material to cover; if you don’t already have much experience programming computers, you might find it overwhelming. The comments below contain some suggestions for approaching the <em>Rails Tutorial</em> depending on your background. <br /></p>
<p><strong>All readers:</strong> One common question when learning Rails is whether to learn Ruby first. The answer depends on your personal learning style and how much programming experience you already have. If you prefer to learn everything systematically from the ground up, or if you have never programmed before, then learning Ruby first might work well for you, and in this case I recommend <a href="http://www.amazon.com/gp/product/1430223634"><em>Beginning Ruby</em></a> by Peter Cooper. On the other hand, many beginning Rails developers are excited about making <em>web</em> applications, and would rather not slog through a 500-page book on pure Ruby before ever writing a single web page. In this case, I recommend following the short interactive tutorial at <a href="http://tryruby.org/">Try Ruby</a>,<sup class="footnote" id="fnref-1_2"><a href="#fn-1_2">2</a></sup> and then optionally do the free tutorial at <a href="http://railsforzombies.org/">Rails for Zombies</a><sup class="footnote" id="fnref-1_3"><a href="#fn-1_3">3</a></sup> to get a taste of what Rails can do.</p>
<p>Another common question is whether to use tests from the start. As noted in the introduction, the <em>Rails Tutorial</em> uses test-driven development (also called test-first development), which in my view is the best way to develop Rails applications, but it does introduce a substantial amount of overhead and complexity. If you find yourself getting bogged down by the tests, I suggest either skipping them on a first reading or (even better) using them as a tool to verify your code’s correctness without worrying about how they work. This latter strategy involves creating the necessary test files (called <em>specs</em>) and filling them with the test code <em>exactly</em> as it appears in the book. You can then run the test suite (as described in <a class="ref" href="filling-in-the-layout.html#top">Chapter 5</a>) to watch it fail, then write the application code as described in the tutorial, and finally re-run the test suite to watch it pass. <br /></p>
<p><strong>Inexperienced programmers:</strong> The <em>Rails Tutorial</em> is not aimed principally at beginning programmers, and web applications, even relatively simple ones, are by their nature fairly complex. If you are completely new to web programming and find the <em>Rails Tutorial</em> too difficult, I suggest learning the basics of HTML and CSS and then giving the <em>Rails Tutorial</em> another go. (Unfortunately, I don’t have a personal recommendation here, but <a href="http://headfirstlabs.com/books/hfhtml/"><em>Head First HTML</em></a> looks promising, and one reader recommends <a href="http://www.amazon.com/gp/product/0596526873"><em>CSS: The Missing Manual</em></a> by David Sawyer McFarland.) You might also consider reading the first few chapters of <a href="http://www.amazon.com/gp/product/1430223634"><em>Beginning Ruby</em></a> by Peter Cooper, which starts with sample applications much smaller than a full-blown web app. That said, a surprising number of beginners have used this tutorial to learn web development, so I suggest giving it a try, and I especially recommend the <a href="http://railstutorial.org/screencasts"><em>Rails Tutorial</em> screencast series</a><sup class="footnote" id="fnref-1_4"><a href="#fn-1_4">4</a></sup> to give you an “over-the-shoulder” look at Rails software development. <br /></p>
<p><strong>Experienced programmers new to web development:</strong> Your previous experience means you probably already understand ideas like classes, methods, data structures, etc., which is a big advantage. Be warned that if your background is in C/C++ or Java, you may find Ruby a bit of an odd duck, and it might take time to get used to it; just stick with it and eventually you’ll be fine. (Ruby even lets you put semicolons at the ends of lines if you miss them too much.) The <em>Rails Tutorial</em> covers all the web-specific ideas you’ll need, so don’t worry if you don’t currently know a <tt>PUT</tt> from a <tt>POST</tt>.<br /></p>
<p><strong>Experienced web developers new to Rails:</strong> You have a great head start, especially if you have used a dynamic language such as PHP or (even better) Python. The basics of what we cover will likely be familiar, but test-driven development may be new to you, as may be the structured REST style favored by Rails. Ruby has its own idiosyncrasies, so those will likely be new, too.<br /></p>
<p><strong>Experienced Ruby programmers:</strong> The set of Ruby programmers who don’t know Rails is a small one nowadays, but if you are a member of this elite group you can fly through this book and then move on to <a href="http://www.amazon.com/gp/product/0321601661"><em>The Rails 3 Way</em></a> by Obie Fernandez. <br /></p>
<p><strong>Inexperienced Rails programmers:</strong> You’ve perhaps read some other tutorials and made a few small Rails apps yourself. Based on reader feedback, I’m confident that you can still get a lot out of this book. Among other things, the techniques here may be more up-to-date than the ones you picked up when you originally learned Rails. <br /></p>
<p><strong>Experienced Rails programmers:</strong> This book is unnecessary for you, but many experienced Rails developers have expressed surprise at how much they learned from this book, and you might enjoy seeing Rails from a different perspective. <br /></p>
<p>After finishing the <em>Ruby on Rails Tutorial</em>, I recommend that experienced programmers read <a href="http://www.amazon.com/gp/product/1933988657"><em>The Well-Grounded Rubyist</em></a> by David A. Black, which is an excellent in-depth discussion of Ruby from the ground up, or <a href="http://www.amazon.com/gp/product/0672328844"><em>The Ruby Way</em></a> by Hal Fulton, which is also fairly advanced but takes a more topical approach. Then move on to <a href="http://www.amazon.com/gp/product/0321601661"><em>The Rails 3 Way</em></a> to deepen your Rails expertise.<br /></p>
<p>At the end of this process, no matter where you started, you should be ready for the many more intermediate-to-advanced Rails resources out there. Here are some I particularly recommend:</p>
<ul>
<li><a href="http://railscasts.com/">RailsCasts</a> by Ryan Bates: Excellent (mostly) free Rails screencasts</li>
<li><a href="http://peepcode.com/">PeepCode</a>: Excellent commercial screencasts</li>
<li><a href="http://www.codeschool.com/">Code School</a>: Interactive programming courses</li>
<li><a href="http://guides.rubyonrails.org/">Rails Guides</a>: Good topical and up-to-date Rails references</li>
<li><a href="http://railscasts.com/">RailsCasts</a> by Ryan Bates: Did I already mention <a href="http://railscasts.com/">RailsCasts</a>? Seriously: <a href="http://railscasts.com/"><em>RailsCasts</em></a>.</li>
</ul>
<h3><a id="sec-1_1_2" href="beginning.html#sec-1_1_2" class="heading"><span class="number">1.1.2</span> “Scaling” Rails</a></h3>
<p>Before moving on with the rest of the introduction, I’d like to take a moment to address the one issue that dogged the Rails framework the most in its early days: the supposed inability of Rails to “scale”—i.e., to handle large amounts of traffic. Part of this issue relied on a misconception; <a href="http://idleprocess.wordpress.com/2009/11/24/presentation-summary-high-performance-at-massive-scale-lessons-learned-at-facebook/">you scale a <em>site</em>, not a framework</a>, and Rails, as awesome as it is, is only a framework. So the real question should have been, “Can a site built with Rails scale?” In any case, the question has now been definitively answered in the affirmative: some of the most heavily trafficked sites in the world use Rails. Actually <em>doing</em> the scaling is beyond the scope of just Rails, but rest assured that if <em>your</em> application ever needs to handle the load of Hulu or the Yellow Pages, Rails won’t stop you from taking over the world.</p>
<div class="label" id="sec-conventions"></div>
<h3><a id="sec-1_1_3" href="beginning.html#sec-conventions" class="heading"><span class="number">1.1.3</span> Conventions in this book</a></h3>
<p>The conventions in this book are mostly self-explanatory. In this section, I’ll mention some that may not be.</p>
<p>Both the <a href="http://railstutorial.org/book">HTML</a> and <a href="http://railstutorial.org/">PDF</a> editions of this book are full of links, both to internal sections (such as <a class="ref" href="beginning.html#sec-up_and_running">Section 1.2</a>) and to external sites (such as the main <a href="http://rubyonrails.org/download">Ruby on Rails download</a> page).<sup class="footnote" id="fnref-1_5"><a href="#fn-1_5">5</a></sup></p>
<p>Many examples in this book use command-line commands. For simplicity, all command line examples use a Unix-style command line prompt (a dollar sign), as follows:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"hello, world"</span>
<span class="go">hello, world</span>
</pre></div>
</div>
<p>Windows users should understand that their systems will use the analogous angle prompt <code>></code>:</p>
<div class="code"><div class="highlight"><pre><span class="go">C:\Sites> echo "hello, world"</span>
<span class="go">hello, world</span>
</pre></div>
</div>
<p>On Unix systems, some commands should be executed with <code>sudo</code>, which stands for “substitute user do”.<sup class="footnote" id="fnref-1_6"><a href="#fn-1_6">6</a></sup> By default, a command executed with <code>sudo</code> is run as an administrative user, which has access to files and directories that normal users can’t touch, such as in this example from <a class="ref" href="beginning.html#sec-rubygems">Section 1.2.2</a>:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> sudo ruby setup.rb
</pre></div>
</div>
<p>Most Unix/Linux/OS X systems require <code>sudo</code> by default, unless you are using Ruby Version Manager as suggested in <a class="ref" href="beginning.html#sec-install_ruby">Section 1.2.2.3</a>; in this case, you would type this instead:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> ruby setup.rb
</pre></div>
</div>
<p>Rails comes with lots of commands that can be run at the command line. For example, in <a class="ref" href="beginning.html#sec-rails_server">Section 1.2.5</a> we’ll run a local development web server as follows:</p>
<div class="code"><div class="highlight"><pre><span class="nv">$ </span>rails server
</pre></div>
</div>
<p>As with the command-line prompt, the <em>Rails Tutorial</em> uses the Unix convention for directory separators (i.e., a forward slash <code>/</code>). My Rails Tutorial sample application, for instance, lives in</p>
<div class="code"><div class="highlight"><pre>/Users/mhartl/rails_projects/sample_app
</pre></div>
</div>
<p>On Windows, the analogous directory would be</p>
<div class="code"><div class="highlight"><pre>C:\Sites\sample_app
</pre></div>
</div>
<p>The root directory for any given app is known as the <em>Rails root</em>, but this terminology is confusing and many people mistakenly believe that the “Rails root” is the root directory for Rails itself. For clarity, the <em>Rails Tutorial</em> will refer to the Rails root as the <em>application root</em>, and henceforth all directories will be relative to this directory. For example, the <code>config</code> directory of my sample application is</p>
<div class="code"><div class="highlight"><pre>/Users/mhartl/rails_projects/sample_app/config
</pre></div>
</div>
<p>The application root directory here is everything before <code>config</code>, i.e.,</p>
<div class="code"><div class="highlight"><pre>/Users/mhartl/rails_projects/sample_app
</pre></div>
</div>
<p>For brevity, when referring to the file</p>
<div class="code"><div class="highlight"><pre>/Users/mhartl/rails_projects/sample_app/config/routes.rb
</pre></div>
</div>
<p>I’ll omit the application root and simply write <code>config/routes.rb</code>.</p>
<p>The <em>Rails Tutorial</em> often shows output from various programs (shell commands, version control status, Ruby programs, etc.). Because of the innumerable small differences between different computer systems, the output you see may not always agree exactly with what is shown in the text,
but this is not cause for concern.</p>
<p>Some commands may produce errors depending on your system; rather than attempt the <a href="http://en.wikipedia.org/wiki/Sisyphus">Sisyphean</a> task of documenting all such errors in this tutorial, I will delegate to the “Google the error message” algorithm, which among other things is good practice for real-life software development. If you run into any problems while following the tutorial, I suggest consulting the resources listed on the <a href="http://railstutorial.org/help">Rails Tutorial help page</a>.<sup class="footnote" id="fnref-1_7"><a href="#fn-1_7">7</a></sup></p>
<div class="label" id="sec-up_and_running"></div>
<h2><a id="sec-1_2" href="beginning.html#sec-up_and_running" class="heading"><span class="number">1.2</span> Up and running</a></h2>
<blockquote><p>I think of Chapter 1 as the “weeding out phase” in law school—if you can get your dev environment set up, the rest is easy to get through. <br /> —Bob Cavezza, <em>Rails Tutorial</em> reader</p>
</blockquote>
<p>It’s time now to get going with a Ruby on Rails development environment and our first application. There is quite a bit of overhead here, especially if you don’t have extensive programming experience, so don’t get discouraged if it takes a while to get started. It’s not just you; every developer goes through it (often more than once), but rest assured that the effort will be richly rewarded.</p>
<div class="label" id="sec-development_tools"></div>
<h3><a id="sec-1_2_1" href="beginning.html#sec-development_tools" class="heading"><span class="number">1.2.1</span> Development environments</a></h3>
<p>Considering various idiosyncratic customizations, there are probably as many development environments as there are Rails programmers, but there are at least two broad types: text editor/command line environments, and integrated development environments (IDEs). Let’s consider the latter first.</p>
<h4><a id="sec-1_2_1_1" href="beginning.html#sec-1_2_1_1" class="heading">IDEs</a></h4>
<p>There is no shortage of Rails IDEs, including <a href="http://www.aptana.com/rails/">RadRails</a>, <a href="http://www.jetbrains.com/ruby/index.html">RubyMine</a>, and <a href="http://www.codegear.com/products/3rdrail">3rd Rail</a>. I’ve heard especially good things about RubyMine, and one reader (David Loeffler) has assembled <a href="https://github.com/perfectionist/sample_project/wiki">notes on how to use RubyMine with this tutorial</a>.<sup class="footnote" id="fnref-1_8"><a href="#fn-1_8">8</a></sup> If you’re comfortable using an IDE, I suggest taking a look at the options mentioned to see what fits with the way you work.</p>
<h4><a id="sec-1_2_1_2" href="beginning.html#sec-1_2_1_2" class="heading">Text editors and command lines</a></h4>
<p>Instead of using an IDE, I prefer to use a <em>text editor</em> to edit text, and a <em>command line</em> to issue commands (<a class="ref" href="beginning.html#fig-editor_shell">Figure 1.1</a>). Which combination you use depends on your tastes and your platform.</p>
<ul>
<li><strong>Text editor:</strong> I recommend <a href="http://www.sublimetext.com/2">Sublime Text 2</a>, an outstanding cross-platform text editor that is in beta as of this writing but has already proven to be exceptionally powerful. Sublime Text is heavily influenced by <a href="http://macromates.com">TextMate</a>, and in fact is compatible with most TextMate customizations, such as snippets and color schemes. (TextMate, which is available only on OS X, is still a good choice if you use a Mac.) A second excellent choice is <a href="http://www.vim.org/">Vim</a>,<sup class="footnote" id="fnref-1_9"><a href="#fn-1_9">9</a></sup> versions of which are available for all major platforms. Sublime Text can be obtained commercially, whereas Vim can be obtained at no cost; both are industrial-strength editors, but in my experience Sublime Text is <em>much</em> more accessible to beginners.</li>
<li><strong>Terminal:</strong> On OS X, I recommend either use <a href="http://iterm.sourceforge.net/">iTerm</a> or the native Terminal app. On Linux, the default terminal is fine. On Windows, many users prefer to develop Rails applications in a virtual machine running Linux, in which case your command-line options reduce to the previous case. If developing within Windows itself, I recommend using the command prompt that comes with <a href="http://railsinstaller.org/">Rails Installer</a> (<a class="ref" href="beginning.html#sec-rails_installer_windows">Section 1.2.2.1</a>).</li>
</ul>
<p>If you decide to use Sublime Text, you might want to follow the optional setup instructions for <a href="https://github.com/mhartl/rails_tutorial_sublime_text">Rails Tutorial Sublime Text</a>.<sup class="footnote" id="fnref-1_10"><a href="#fn-1_10">10</a></sup> (Such configuration settings can be fiddly and error-prone, so I mainly recommend them for more advanced users; Sublime Text is an excellent choice for editing Rails applications even without the advanced setup.)</p>
<div class="label" id="fig-editor_shell"></div>
<div class="figure"><div class="center"><span class="graphic"><img src="images/figures/editor_shell.png" alt="editor_shell" /></span></div><div class="caption"><span class="header">Figure 1.1: </span><span class="description">A text editor/command line development environment (TextMate/iTerm). <a href="http://railstutorial.org/images/figures/editor_shell-full.png">(full size)</a></span></div></div>
<h4><a id="sec-1_2_1_3" href="beginning.html#sec-1_2_1_3" class="heading">Browsers</a></h4>
<p>Although there are many web browsers to choose from, the vast majority of Rails programmers use Firefox, Safari, or Chrome when developing. The screenshots in Rails Tutorial will generally be of a Firefox browser. If you use Firefox, I suggest using the <a href="http://getfirebug.com/">Firebug</a> add-on, which lets you perform all sorts of magic, such as dynamically inspecting (and even editing) the HTML structure and CSS rules on any page. For those not using Firefox, both Safari and Chrome have a built-in “Inspect element” feature available by right-clicking on any part of the page.</p>
<h4><a id="sec-1_2_1_4" href="beginning.html#sec-1_2_1_4" class="heading">A note about tools</a></h4>
<p>In the process of getting your development environment up and running, you may find that you spend a <em>lot</em> of time getting everything just right. The learning process for editors and IDEs is particularly long; you can spend weeks on Sublime Text or Vim tutorials alone. If you’re new to this game, I want to assure you that <em>spending time learning tools is normal</em>. Everyone goes through it. Sometimes it is frustrating, and it’s easy to get impatient when you have an awesome web app in your head and you <em>just want to learn Rails already</em>, but have to spend a week learning some weird ancient Unix editor just to get started. But a craftsman has to know his tools, and in the end the reward is worth the effort.</p>
<div class="label" id="sec-rubygems"></div>
<h3><a id="sec-1_2_2" href="beginning.html#sec-rubygems" class="heading"><span class="number">1.2.2</span> Ruby, RubyGems, Rails, and Git</a></h3>
<blockquote><p>Practically all the software
in the world is either broken or very difficult to use. So users dread software. They’ve been trained that whenever they try to install something, or even fill out a form online, it’s not going to work. <em>I</em> dread installing stuff, and I have a Ph.D. in computer science. <br /> —Paul Graham, in <em>Founders at Work</em> by Jessica Livingston</p>
</blockquote>
<p>Now it’s time to install Ruby and Rails. I’ve done my best to cover as many bases as possible, but systems vary, and many things can go wrong during these steps. Be sure to Google the error message or consult the <a href="http://railstutorial.org/help">Rails Tutorial help page</a> if you run into trouble.</p>
<p><strong>Unless otherwise noted, you should use the exact versions of all software used in the tutorial, including Rails itself, if you want the same results.</strong> Sometimes minor version differences will yield identical results, but you shouldn’t count on this, especially with respect to Rails versions. The main exception is Ruby itself: 1.9.2 and 1.9.3 are virtually identical for the purposes of this tutorial, so feel free to use either one.</p>
<div class="label" id="sec-rails_installer_windows"></div>
<h4><a id="sec-1_2_2_1" href="beginning.html#sec-rails_installer_windows" class="heading">Rails Installer (Windows)</a></h4>
<p>Installing Rails on Windows used to be a real pain, but thanks to the efforts of the good people at <a href="http://engineyard.com/">Engine Yard</a>—especially Dr. Nic Williams and Wayne E. Seguin—installing Rails and related software on Windows is now easy. If you are using Windows, go to <a href="http://railsinstaller.org/">Rails Installer</a> and download the Rails Installer executable and view the excellent installation video. Double-click the executable and follow the instructions to install Git (so you can skip <a class="ref" href="beginning.html#sec-install_git">Section 1.2.2.2</a>), Ruby (skip <a class="ref" href="beginning.html#sec-install_ruby">Section 1.2.2.3</a>), RubyGems (skip <a class="ref" href="beginning.html#sec-install_rubygems">Section 1.2.2.4</a>), and Rails itself (skip <a class="ref" href="beginning.html#sec-install_rails">Section 1.2.2.5</a>). Once the installation has finished, you can skip right to the creation of the first application in <a class="ref" href="beginning.html#sec-the_first_application">Section 1.2.3</a>.</p>
<p>Bear in mind that the Rails Installer might use a slightly different version of Rails from the one installed in <a class="ref" href="beginning.html#sec-install_rails">Section 1.2.2.5</a>, which might cause incompatibilities. To fix this, I am currently working with Nic and Wayne to create a list of Rails Installers ordered by Rails version number.</p>
<div class="label" id="sec-install_git"></div>
<h4><a id="sec-1_2_2_2" href="beginning.html#sec-install_git" class="heading">Install Git</a></h4>
<p>Much of the Rails ecosystem depends in one way or another on a <a href="http://en.wikipedia.org/wiki/Revision_control">version control system</a> called <a href="http://git-scm.com/">Git</a> (covered in more detail in <a class="ref" href="beginning.html#sec-version_control">Section 1.3</a>). Because its use is ubiquitous, you should install Git even at this early stage; I suggest following the installation instructions for your platform at the <a href="http://www.git-scm.com/book/en/Getting-Started-Installing-Git">Installing Git section of <em>Pro Git</em></a>.</p>
<div class="label" id="sec-install_ruby"></div>
<h4><a id="sec-1_2_2_3" href="beginning.html#sec-install_ruby" class="heading">Install Ruby</a></h4>
<p>The next step is to install Ruby. It’s possible that your system already has it; try running</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> ruby -v
<span class="go">ruby 1.9.3</span>
</pre></div>
</div>
<p>to see the version number. Rails 3 requires Ruby 1.8.7 or later and works best with Ruby 1.9.x. This tutorial assumes that most readers are using Ruby 1.9.2 or 1.9.3, but Ruby 1.8.7 should work as well (although there is one syntax difference, covered in <a class="ref" href="rails-flavored-ruby.html#top">Chapter 4</a>, and assorted minor differences in output).</p>
<p>As part of installing Ruby, if you are using OS X or Linux I strongly recommend using <a href="http://rvm.io/">Ruby Version Manager (RVM)</a>, which allows you to install and manage multiple versions of Ruby on the same machine. (The <a href="http://github.com/vertiginous/pik">Pik</a> project accomplishes a similar feat on Windows.) This is particularly important if you want to run different versions of Ruby or Rails on the same machine. If you run into any problems with RVM, you can often find its creator, Wayne E. Seguin, on the RVM IRC channel (<a href="http://webchat.freenode.net/?channels=rvm">#rvm on freenode.net</a>).<sup class="footnote" id="fnref-1_11"><a href="#fn-1_11">11</a></sup> If you are running Linux, I particularly recommend <a href="http://blog.sudobits.com/2012/05/02/how-to-install-ruby-on-rails-in-ubuntu-12-04-lts/">How to install Ruby on Rails in Ubuntu on the Sudobits Blog</a>.</p>
<p>After <a href="http://rvm.io/rvm/install/">installing RVM</a>, you can install Ruby as follows:<sup class="footnote" id="fnref-1_12"><a href="#fn-1_12">12</a></sup></p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm get head <span class="o">&&</span> rvm reload
<span class="gp">$</span> rvm install 1.9.3
<span class="go"><wait a while></span>
</pre></div>
</div>
<p>Here the first command updates and reloads RVM itself, which is a good practice since RVM gets updated frequently. The second installs the 1.9.3 version of Ruby; depending on your system, they might take a while to download and compile, so don’t worry if it seems to be taking forever.</p>
<p>Some OS X users have trouble with the lack of an <code>autoconf</code> executable, which you can fix by installing <a href="http://mxcl.github.com/homebrew/">Homebrew</a><sup class="footnote" id="fnref-1_13"><a href="#fn-1_13">13</a></sup> (a package management system for OS X) and then running</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> brew install automake
<span class="gp">$</span> rvm install 1.9.3
</pre></div>
</div>
<p>Some Linux users report having to include the path to a library called OpenSSL:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm install 1.9.3 --with-openssl-dir<span class="o">=</span><span class="nv">$HOME</span>/.rvm/
</pre></div>
</div>
<p>On some older OS X systems, you might have to include the path to the readline library:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm install 1.9.3 --with-readline-dir<span class="o">=</span>/opt/local
</pre></div>
</div>
<p>(Like I said, lots of things can go wrong. The only solution is web searches and determination.)</p>
<p>After installing Ruby, you should configure your system for the other software needed to run Rails applications. This typically involves installing <em>gems</em>, which are self-contained packages of Ruby code. Since gems with different version numbers sometimes conflict, it is often convenient to create separate <em>gemsets</em>, which are self-contained bundles of gems. For the purposes of this tutorial, I suggest creating a gemset called <code>rails3tutorial2ndEd</code>:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm use 1.9.3@rails3tutorial2ndEd --create --default
<span class="go">Using /Users/mhartl/.rvm/gems/ruby-1.9.3 with gemset rails3tutorial2ndEd</span>
</pre></div>
</div>
<p>This command creates (<tt class="verb">--create</tt>) the gemset <code>rails3tutorial2ndEd</code> associated with Ruby 1.9.3 while arranging to start using it immediately (<tt class="verb">use</tt>) and setting it as the default (<tt class="verb">--default</tt>) gemset, so that any time we open a new terminal window the <code>1.9.3@rails3tutorial2ndEd</code> Ruby/gemset combination is automatically selected. RVM supports a large variety of commands for manipulating gemsets; see the documentation at <a href="http://rvm.io/gemsets/">http://rvm.beginrescueend.com/gemsets/</a>. If you ever get stuck with RVM, running commands like these should help you get your bearings:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm <span class="nb">help</span>
<span class="gp">$</span><span class="nb"> </span>rvm gemset <span class="nb">help</span>
</pre></div>
</div>
<div class="label" id="sec-install_rubygems"></div>
<h4><a id="sec-1_2_2_4" href="beginning.html#sec-install_rubygems" class="heading">Install RubyGems</a></h4>
<p>RubyGems is a package manager for Ruby projects, and there are many useful libraries (including Rails) available as Ruby packages, or <em>gems</em>. Installing RubyGems should be easy once you install Ruby. In fact, if you have <a href="http://rvm.io/rvm/install/">installed RVM</a>, you already have RubyGems, since RVM includes it automatically:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> which gem
<span class="go">/Users/mhartl/.rvm/rubies/ruby-1.9.3-p0/bin/gem</span>
</pre></div>
</div>
<p>If you don’t already have it, you should <a href="http://rubyforge.org/frs/?group_id=126">download RubyGems</a>, extract it, and then go to the <code>rubygems</code> directory and run the setup program:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> ruby setup.rb
</pre></div>
</div>
<p>(If you get a permissions error here, recall from <a class="ref" href="beginning.html#sec-conventions">Section 1.1.3</a> that you may have to use <code>sudo</code>.)</p>
<p>If you already have RubyGems installed, you should make sure your system uses the version used in this tutorial:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> gem update --system 1.8.24
</pre></div>
</div>
<p>Freezing your system to this particular version will help prevent conflicts as RubyGems changes in the future.</p>
<p>When installing gems, by default RubyGems generates two different kinds of documentation (called ri and rdoc), but many Ruby and Rails developers find that the time to build them isn’t worth the benefit. (Many programmers rely on online documentation instead of the native ri and rdoc documents.) To prevent the automatic generation of the documentation, I recommend making a gem configuration file called <code>.gemrc</code> in your home directory as in <a class="ref" href="beginning.html#code-create_gemrc">Listing 1.1</a> with the line in <a class="ref" href="beginning.html#code-gemrc">Listing 1.2</a>. (The tilde “<tt class="verb">~</tt>” means “home directory”, while the dot <tt class="verb">.</tt> in <code>.gemrc</code> makes the file hidden, which is a common convention for configuration files. )</p>
<div class="label" id="code-create_gemrc"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.1.</span> <span class="description">Creating a gem configuration file.</span> </div>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> subl ~/.gemrc
</pre></div>
</div></div>
<p>Here <code>subl</code> is the command-line command to launch Sublime Text on OS X, which you can set up using the <a href="http://www.sublimetext.com/docs/2/osx_command_line.html">Sublime Text 2 documentation for the OS X command line</a>. If you’re on a different platform, or if you’re using a different editor, you should replace this command as necessary (i.e., by double-clicking the application icon or by using an alternate command such as <code>mate</code>, <code>vim</code>, <code>gvim</code>, or <code>mvim</code>). For brevity, throughout the rest of this tutorial I’ll use <code>subl</code> as a shorthand for “open with your favorite text editor.”</p>
<div class="label" id="code-gemrc"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.2.</span> <span class="description">Suppressing the ri and rdoc documentation in <code>.gemrc</code>.</span> </div>
<div class="code"><div class="highlight"><pre><span class="ss">install:</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">rdoc</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">ri</span>
<span class="ss">update:</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">rdoc</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">ri</span>
</pre></div>
</div></div>
<div class="label" id="sec-install_rails"></div>
<h4><a id="sec-1_2_2_5" href="beginning.html#sec-install_rails" class="heading">Install Rails</a></h4>
<p>Once you’ve installed RubyGems, installing Rails should be easy. This tutorial standardizes on Rails 3.2, which we can install as follows:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> gem install rails -v 3.2.16
</pre></div>
</div>
<p>To check your Rails installation, run the following command to print out the version number:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rails -v
<span class="go">Rails 3.2.16</span>
</pre></div>
</div>
<p><em>Note:</em> If you installed Rails using the Rails Installer in <a class="ref" href="beginning.html#sec-rails_installer_windows">Section 1.2.2.1</a>, there might be slight version differences. As of this writing, those differences are not relevant, but in the future, as the current Rails version diverges from the one used in this tutorial, these differences may become significant. I am currently working with Engine Yard to create links to specific versions of the Rails Installer.</p>
<p>If you’re running Linux, you might have to install a couple of other packages at this point:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> sudo apt-get install libxslt-dev libxml2-dev libsqlite3-dev <span class="c"># Linux only</span>
</pre></div>
</div>
<div class="label" id="sec-the_first_application"></div>
<h3><a id="sec-1_2_3" href="beginning.html#sec-the_first_application" class="heading"><span class="number">1.2.3</span> The first application</a></h3>
<p>Virtually all Rails applications start the same way, by running <code>rails new</code> command. This handy command creates a skeleton Rails application in a directory of your choice. To get started, make a directory for your Rails projects and then run <code>rails new</code> to make the first application (<a class="ref" href="beginning.html#code-rails_command">Listing 1.3</a>):</p>
<div class="label" id="code-rails_command"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.3.</span> <span class="description">Running <code>rails new</code> to generate a new application.</span> </div>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> mkdir rails_projects
<span class="gp">$</span> <span class="nb">cd </span>rails_projects
<span class="gp">$</span> rails new first_app
<span class="go"> create</span>
<span class="go"> create README.rdoc</span>
<span class="go"> create Rakefile</span>
<span class="go"> create config.ru</span>
<span class="go"> create .gitignore</span>
<span class="go"> create Gemfile</span>
<span class="go"> create app</span>
<span class="go"> create app/assets/images/rails.png</span>
<span class="go"> create app/assets/javascripts/application.js</span>
<span class="go"> create app/assets/stylesheets/application.css</span>
<span class="go"> create app/controllers/application_controller.rb</span>
<span class="go"> create app/helpers/application_helper.rb</span>
<span class="go"> create app/mailers</span>
<span class="go"> create app/models</span>
<span class="go"> create app/views/layouts/application.html.erb</span>
<span class="go"> create app/mailers/.gitkeep</span>
<span class="go"> create app/models/.gitkeep</span>
<span class="go"> create config</span>
<span class="go"> create config/routes.rb</span>
<span class="go"> create config/application.rb</span>
<span class="go"> create config/environment.rb</span>
<span class="go"> .</span>
<span class="go"> .</span>
<span class="go"> .</span>
<span class="go"> create vendor/plugins</span>
<span class="go"> create vendor/plugins/.gitkeep</span>
<span class="go"> run bundle install</span>
<span class="go">Fetching source index for https://rubygems.org/</span>
<span class="go">.</span>
<span class="go">.</span>
<span class="go">.</span>
<span class="go">Your bundle is complete! Use `bundle show [gemname]` to see where a bundled</span>
<span class="go">gem is installed.</span>
</pre></div>
</div></div>
<p>As seen at the end of <a class="ref" href="beginning.html#code-rails_command">Listing 1.3</a>, running <code>rails new</code> automatically runs the <code>bundle install</code> command after the file creation is done. If that step doesn’t work right now, don’t worry; follow the steps in <a class="ref" href="beginning.html#sec-bundler">Section 1.2.4</a> and you should be able to get it to work.</p>
<p>Notice how many files and directories the <code>rails</code> command creates. This standard directory and file structure (<a class="ref" href="beginning.html#fig-directory_structure_rails_3_2">Figure 1.2</a>) is one of the many advantages of Rails; it immediately gets you from zero to a functional (if minimal) application. Moreover, since the structure is common to all Rails apps, you can immediately get your bearings when looking at someone else’s code. A summary of the default Rails files appears in <a class="ref" href="beginning.html#table-rails_directory_structure">Table 1.1</a>; we’ll learn about most of these files and directories throughout the rest of this book. In particular, starting in <a class="ref" href="filling-in-the-layout.html#sec-the_asset_pipeline">Section 5.2.1</a> we’ll discuss the <code>app/assets</code> directory, part of the <em>asset pipeline</em> (new as of Rails 3.1) that makes it easier than ever to organize and deploy assets such as cascading style sheets and JavaScript files.</p>
<div class="label" id="fig-directory_structure_rails_3_2"></div>
<div class="figure"><div class="center"><span class="graphic"><img src="images/figures/directory_structure_rails_31.png" alt="directory_structure_rails_31" /></span></div><div class="caption"><span class="header">Figure 1.2: </span><span class="description">The directory structure for a newly hatched Rails app. <a href="http://railstutorial.org/images/figures/directory_structure_rails_31-full.png">(full size)</a></span></div></div>
<div class="label" id="table-rails_directory_structure"></div>
<div class="table"><div class="center">
<table class="tabular"><tr><th class="align_left"><strong>File/Directory</strong></th><th class="align_left"><strong>Purpose</strong></th></tr><tr class="top_bar"><td class="align_left"><code>app/</code></td><td class="align_left">Core application (app) code, including models, views, controllers, and helpers</td></tr><tr><td class="align_left"><code>app/assets</code></td><td class="align_left">Applications assets such as cascading style sheets (CSS), JavaScript files, and images</td></tr><tr><td class="align_left"><code>config/</code></td><td class="align_left">Application configuration</td></tr><tr><td class="align_left"><code>db/</code></td><td class="align_left">Database files</td></tr><tr><td class="align_left"><code>doc/</code></td><td class="align_left">Documentation for the application</td></tr><tr><td class="align_left"><code>lib/</code></td><td class="align_left">Library modules</td></tr><tr><td class="align_left"><code>lib/assets</code></td><td class="align_left">Library assets such as cascading style sheets (CSS), JavaScript files, and images</td></tr><tr><td class="align_left"><code>log/</code></td><td class="align_left">Application log files</td></tr><tr><td class="align_left"><code>public/</code></td><td class="align_left">Data accessible to the public (e.g., web browsers), such as error pages</td></tr><tr><td class="align_left"><code>script/rails</code></td><td class="align_left">A script for generating code, opening console sessions, or starting a local server</td></tr><tr><td class="align_left"><code>test/</code></td><td class="align_left">Application tests (made obsolete by the <code>spec/</code> directory in <a class="ref" href="static-pages.html#sec-static_pages_with_rails">Section 3.1.2</a>)</td></tr><tr><td class="align_left"><code>tmp/</code></td><td class="align_left">Temporary files</td></tr><tr><td class="align_left"><code>vendor/</code></td><td class="align_left">Third-party code such as plugins and gems</td></tr><tr><td class="align_left"><code>vendor/assets</code></td><td class="align_left">Third-party assets such as cascading style sheets (CSS), JavaScript files, and images</td></tr><tr><td class="align_left"><code>README.rdoc</code></td><td class="align_left">A brief description of the application</td></tr><tr><td class="align_left"><code>Rakefile</code></td><td class="align_left">Utility tasks available via the <code>rake</code> command</td></tr><tr><td class="align_left"><code>Gemfile</code></td><td class="align_left">Gem requirements for this app</td></tr><tr><td class="align_left"><code>Gemfile.lock</code></td><td class="align_left">A list of gems used to ensure that all copies of the app use the same gem versions</td></tr><tr><td class="align_left"><code>config.ru</code></td><td class="align_left">A configuration file for <a href="http://rack.rubyforge.org/doc/">Rack middleware</a></td></tr><tr><td class="align_left"><code>.gitignore</code></td><td class="align_left">Patterns for files that should be ignored by Git</td></tr></table></div><div class="caption"><span class="header">Table 1.1: </span><span class="description">A summary of the default Rails directory structure.</span></div></div>
<div class="label" id="sec-bundler"></div>
<h3><a id="sec-1_2_4" href="beginning.html#sec-bundler" class="heading"><span class="number">1.2.4</span> Bundler</a></h3>
<p>After creating a new Rails application, the next step is to use <em>Bundler</em> to install and include the gems needed by the app. As noted briefly in <a class="ref" href="beginning.html#sec-the_first_application">Section 1.2.3</a>, Bundler is run automatically (via <code>bundle install</code>) by the <code>rails</code> command, but in this section we’ll make some changes to the default application gems and run Bundler again. This involves opening the <code>Gemfile</code> with your favorite text editor:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">cd </span>first_app/
<span class="gp">$</span> subl Gemfile
</pre></div>
</div>
<p>The result should look something like <a class="ref" href="beginning.html#code-default_gemfile">Listing 1.4</a>. The code in this file is Ruby, but don’t worry at this point about the syntax; <a class="ref" href="rails-flavored-ruby.html#top">Chapter 4</a> will cover Ruby in more depth.</p>
<div class="label" id="code-default_gemfile"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.4.</span> <span class="description">The default <code>Gemfile</code> in the <code>first_app</code> directory.</span> </div>
<div class="code"><div class="highlight"><pre><span class="n">source</span> <span class="s1">'https://rubygems.org'</span>
<span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="s1">'3.2.16'</span>
<span class="c1"># Bundle edge Rails instead:</span>
<span class="c1"># gem 'rails', :git => 'git://github.com/rails/rails.git'</span>
<span class="n">gem</span> <span class="s1">'sqlite3'</span>
<span class="c1"># Gems used only for assets and not required</span>
<span class="c1"># in production environments by default.</span>
<span class="n">group</span> <span class="ss">:assets</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sass-rails'</span><span class="p">,</span> <span class="s1">'~> 3.2.3'</span>
<span class="n">gem</span> <span class="s1">'coffee-rails'</span><span class="p">,</span> <span class="s1">'~> 3.2.2'</span>
<span class="n">gem</span> <span class="s1">'uglifier'</span><span class="p">,</span> <span class="s1">'>= 1.2.3'</span>
<span class="k">end</span>
<span class="n">gem</span> <span class="s1">'jquery-rails'</span>
<span class="c1"># To use ActiveModel has_secure_password</span>
<span class="c1"># gem 'bcrypt-ruby', '~> 3.0.0'</span>
<span class="c1"># To use Jbuilder templates for JSON</span>
<span class="c1"># gem 'jbuilder'</span>
<span class="c1"># Use unicorn as the web server</span>
<span class="c1"># gem 'unicorn'</span>
<span class="c1"># Deploy with Capistrano</span>
<span class="c1"># gem 'capistrano'</span>
<span class="c1"># To use debugger</span>
<span class="c1"># gem 'ruby-debug19', :require => 'ruby-debug'</span>
</pre></div>
</div></div>
<p>Many of these lines are commented out with the hash symbol <code>#</code>; they are there to show you some commonly needed gems and to give examples of the Bundler syntax. For now, we won’t need any gems other than the defaults: Rails itself, some gems related to the asset pipeline (<a class="ref" href="filling-in-the-layout.html#sec-the_asset_pipeline">Section 5.2.1</a>), the gem for the jQuery JavaScript library, and the gem for the Ruby interface to the <a href="http://www.sqlite.org/">SQLite database</a>.</p>
<p>Unless you specify a version number to the <code>gem</code> command, Bundler will automatically install the latest version of the gem. Unfortunately, gem updates often cause minor but potentially confusing breakage, so in this tutorial we’ll include explicit version numbers known to work, as seen in <a class="ref" href="beginning.html#code-gemfile_sqlite_version">Listing 1.5</a> (which also omits the commented-out lines from <a class="ref" href="beginning.html#code-default_gemfile">Listing 1.4</a>).</p>
<div class="label" id="code-gemfile_sqlite_version"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.5.</span> <span class="description">A <code>Gemfile</code> with an explicit version of each Ruby gem.</span> </div>
<div class="code"><div class="highlight"><pre><span class="n">source</span> <span class="s1">'https://rubygems.org'</span>
<span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="s1">'3.2.16'</span>
<span class="n">group</span> <span class="ss">:development</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sqlite3'</span><span class="p">,</span> <span class="s1">'1.3.5'</span>
<span class="k">end</span>
<span class="c1"># Gems used only for assets and not required</span>
<span class="c1"># in production environments by default.</span>
<span class="n">group</span> <span class="ss">:assets</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sass-rails'</span><span class="p">,</span> <span class="s1">'3.2.5'</span>
<span class="n">gem</span> <span class="s1">'coffee-rails'</span><span class="p">,</span> <span class="s1">'3.2.2'</span>
<span class="n">gem</span> <span class="s1">'uglifier'</span><span class="p">,</span> <span class="s1">'1.2.3'</span>
<span class="k">end</span>
<span class="n">gem</span> <span class="s1">'jquery-rails'</span><span class="p">,</span> <span class="s1">'2.0.2'</span>
</pre></div>
</div></div>
<p><a class="ref" href="beginning.html#code-gemfile_sqlite_version">Listing 1.5</a> changes the line for jQuery, the default JavaScript library used by Rails, from</p>
<div class="code"><div class="highlight"><pre><span class="n">gem</span> <span class="s1">'jquery-rails'</span>
</pre></div>
</div>
<p>to</p>
<div class="code"><div class="highlight"><pre><span class="n">gem</span> <span class="s1">'jquery-rails'</span><span class="p">,</span> <span class="s1">'2.0.2'</span>
</pre></div>
</div>
<p>We’ve also changed</p>
<div class="code"><div class="highlight"><pre><span class="n">gem</span> <span class="s1">'sqlite3'</span>
</pre></div>
</div>
<p>to</p>
<div class="code"><div class="highlight"><pre><span class="n">group</span> <span class="ss">:development</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sqlite3'</span><span class="p">,</span> <span class="s1">'1.3.5'</span>
<span class="k">end</span>
</pre></div>
</div>
<p>which forces Bundler to install version <code>1.3.5</code> of the <code>sqlite3</code> gem. Note that we’ve also taken this opportunity to arrange for SQLite to be included only in a development environment (<a class="ref" href="sign-up.html#sec-rails_environments">Section 7.1.1</a>), which prevents potential conflicts with the database used by Heroku (<a class="ref" href="beginning.html#sec-deploying">Section 1.4</a>).</p>
<p><a class="ref" href="beginning.html#code-gemfile_sqlite_version">Listing 1.5</a> also changes a few other lines, converting</p>
<div class="code"><div class="highlight"><pre><span class="n">group</span> <span class="ss">:assets</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sass-rails'</span><span class="p">,</span> <span class="s1">'~> 3.2.3'</span>
<span class="n">gem</span> <span class="s1">'coffee-rails'</span><span class="p">,</span> <span class="s1">'~> 3.2.2'</span>
<span class="n">gem</span> <span class="s1">'uglifier'</span><span class="p">,</span> <span class="s1">'>= 1.2.3'</span>
<span class="k">end</span>
</pre></div>
</div>
<p>to</p>
<div class="code"><div class="highlight"><pre><span class="n">group</span> <span class="ss">:assets</span> <span class="k">do</span>
<span class="n">gem</span> <span class="s1">'sass-rails'</span><span class="p">,</span> <span class="s1">'3.2.5'</span>
<span class="n">gem</span> <span class="s1">'coffee-rails'</span><span class="p">,</span> <span class="s1">'3.2.2'</span>
<span class="n">gem</span> <span class="s1">'uglifier'</span><span class="p">,</span> <span class="s1">'1.2.3'</span>
<span class="k">end</span>
</pre></div>
</div>
<p>The syntax</p>
<div class="code"><div class="highlight"><pre><span class="n">gem</span> <span class="s1">'uglifier'</span><span class="p">,</span> <span class="s1">'>= 1.2.3'</span>
</pre></div>
</div>
<p>installs the latest version of the <code>uglifier</code> gem (which handles file compression for the asset pipeline) as long as it’s greater than version <code>1.2.3</code>—even if it’s, say, version <code>7.2</code>. Meanwhile, the code</p>
<div class="code"><div class="highlight"><pre><span class="n">gem</span> <span class="s1">'coffee-rails'</span><span class="p">,</span> <span class="s1">'~> 3.2.2'</span>
</pre></div>
</div>
<p>installs the gem <code>coffee-rails</code> (also needed by the asset pipeline) as long as it’s lower than version <code>3.3</code>. In other words, the <tt class="verb">>=</tt> notation always performs upgrades, whereas the <tt class="verb">~> 3.2.2</tt> notation only performs upgrades to minor point releases (e.g., from <code>3.2.1</code> to <code>3.2.2</code>), but not to major point releases (e.g., from <code>3.2</code> to <code>3.3</code>). Unfortunately, experience shows that even minor point releases can break things, so for the <em>Rails Tutorial</em> we’ll err on the side of caution by including exact version numbers for virtually all gems. (The only exception is gems that are in release candidate or beta stage as of this writing; for those gems, we’ll use <tt class="verb">~></tt> so that the final versions will be loaded once they’re done.) You are welcome to use the most up-to-date version of any gem, including using to the <tt class="verb">~></tt> construction in the <code>Gemfile</code> (which I generally recommend for more advanced users), but be warned that this may cause the tutorial to act unpredictably.</p>
<p>Once you’ve assembled the proper <code>Gemfile</code>, install the gems using
<code>bundle update</code><sup class="footnote" id="fnref-1_14"><a href="#fn-1_14">14</a></sup> and <code>bundle install</code>:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> bundle update
<span class="gp">$</span> bundle install
<span class="go">Fetching source index for https://rubygems.org/</span>
<span class="go">.</span>
<span class="go">.</span>
<span class="go">.</span>
</pre></div>
</div>
<p>If you’re running OS X and you get an error about missing Ruby header files (e.g., <code>ruby.h</code>) at this point, you may need to install Xcode. These are developer tools that came with your OS X installation disk, but to avoid the full installation I recommend the much smaller <a href="https://developer.apple.com/downloads/">Command Line Tools for Xcode</a>.<sup class="footnote" id="fnref-1_15"><a href="#fn-1_15">15</a></sup> If you get a libxslt error when installing the Nokogiri gem, try reinstalling Ruby:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rvm reinstall 1.9.3
<span class="gp">$</span> bundle install
</pre></div>
</div>
<p>The <code>bundle install</code> command might take a few moments, but when it’s done our application will be ready to run. <em>Note:</em> This setup is fine for the first app, but it isn’t ideal. <a class="ref" href="static-pages.html#top">Chapter 3</a> covers a more powerful (and slightly more advanced) method for installing Ruby gems with Bundler.</p>
<div class="label" id="sec-rails_server"></div>
<h3><a id="sec-1_2_5" href="beginning.html#sec-rails_server" class="heading"><span class="number">1.2.5</span> <tt>rails server</tt></a></h3>
<p>Thanks to running <code>rails new</code> in <a class="ref" href="beginning.html#sec-the_first_application">Section 1.2.3</a> and <code>bundle install</code> in <a class="ref" href="beginning.html#sec-bundler">Section 1.2.4</a>, we already have an application we can run—but how? Happily, Rails comes with a command-line program, or <em>script</em>, that runs a <em>local</em> web server, visible only from your development machine:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> rails server
<span class="go">=> Booting WEBrick</span>
<span class="go">=> Rails application starting on http://0.0.0.0:3000</span>
<span class="go">=> Call with -d to detach</span>
<span class="go">=> Ctrl-C to shutdown server</span>
</pre></div>
</div>
<p>(If your system complains about the lack of a JavaScript runtime, visit the <a href="https://github.com/sstephenson/execjs">execjs page at GitHub</a> for a list of possibilities. I particularly recommend installing <a href="http://nodejs.org/">Node.js</a>.) This tells us that the application is running on <a href="http://en.wikipedia.org/wiki/TCP_and_UDP_port">port number</a> 3000<sup class="footnote" id="fnref-1_16"><a href="#fn-1_16">16</a></sup> at the address <code>0.0.0.0</code>. This address tells the computer to listen on every available IP address configured on that specific machine; in particular, we can view the application using the special address <code>127.0.0.1</code>, which is also known as <code>localhost</code>. We can see the result of visiting <a href="http://localhost:3000/">http://localhost:3000/</a> in <a class="ref" href="beginning.html#fig-riding_rails_31">Figure 1.3</a>.</p>
<div class="label" id="fig-riding_rails_31"></div>
<div class="figure"><div class="center"><span class="graphic"><img src="images/figures/riding_rails_31.png" alt="riding_rails_31" /></span></div><div class="caption"><span class="header">Figure 1.3: </span><span class="description">The default Rails page. <a href="http://railstutorial.org/images/figures/riding_rails_31-full.png">(full size)</a></span></div></div>
<p>To see information about our first application, click on the link “About your application’s environment”. The result is shown in <a class="ref" href="beginning.html#fig-riding_rails_32_environment">Figure 1.4</a>. (<a class="ref" href="beginning.html#fig-riding_rails_32_environment">Figure 1.4</a> represents the environment on my machine when I made the screenshot; your results may differ.)</p>
<div class="label" id="fig-riding_rails_32_environment"></div>
<div class="figure"><div class="center"><span class="graphic"><img src="images/figures/riding_rails_32_environment.png" alt="riding_rails_32_environment" /></span></div><div class="caption"><span class="header">Figure 1.4: </span><span class="description">The default page with the app environment. <a href="http://railstutorial.org/images/figures/riding_rails_32_environment-full.png">(full size)</a></span></div></div>
<p>Of course, we don’t need the default Rails page in the long run, but it’s nice to see it working for now. We’ll remove the default page (and replace it with a custom home page) in <a class="ref" href="filling-in-the-layout.html#sec-rails_routes">Section 5.3.2</a>.</p>
<div class="label" id="sec-mvc"></div>
<h3><a id="sec-1_2_6" href="beginning.html#sec-mvc" class="heading"><span class="number">1.2.6</span> Model-view-controller (MVC)</a></h3>
<p>Even at this early stage, it’s helpful to get a high-level overview of how Rails applications work (<a class="ref" href="beginning.html#fig-MVC">Figure 1.5</a>). You might have noticed that the standard Rails application structure (<a class="ref" href="beginning.html#fig-directory_structure_rails_3_2">Figure 1.2</a>) has an application directory called <code>app/</code> with three subdirectories: <code>models</code>, <code>views</code>, and <code>controllers</code>. This is a hint that Rails follows the <a href="http://en.wikipedia.org/wiki/Model-view-controller">model-view-controller</a> (MVC) architectural pattern, which enforces a separation between “domain logic” (also called “business logic”) from the input and presentation logic associated with a graphical user interface (GUI). In the case of web applications, the “domain logic” typically consists of data models for things like users, articles, and products, and the GUI is just a web page in a web browser.</p>
<p>When interacting with a Rails application, a browser sends a <em>request</em>, which is received by a web server and passed on to a Rails <em>controller</em>, which is in charge of what to do next. In some cases, the controller will immediately render a <em>view</em>, which is a template that gets converted to HTML and sent back to the browser. More commonly for dynamic sites, the controller interacts with a <em>model</em>, which is a Ruby object that represents an element of the site (such as a user) and is in charge of communicating with the database. After invoking the model, the controller then renders the view and returns the complete web page to the browser as HTML.</p>
<div class="label" id="fig-MVC"></div>
<div class="figure"><div class="center"><span class="graphic"><img src="images/figures/mvc_schematic.png" alt="mvc_schematic" /></span></div><div class="caption"><span class="header">Figure 1.5: </span><span class="description">A schematic representation of the model-view-controller (MVC) architecture.</span></div></div>
<p>If this discussion seems a bit abstract right now, worry not; we’ll refer back to this section frequently. In addition, <a class="ref" href="a-demo-app.html#sec-mvc_in_action">Section 2.2.2</a> has a more detailed discussion of MVC in the context of the demo app. Finally, the sample app will use all aspects of MVC; we’ll cover controllers and views starting in <a class="ref" href="static-pages.html#sec-static_pages_with_rails">Section 3.1.2</a>, models starting in <a class="ref" href="modeling-users.html#sec-user_model">Section 6.1</a>, and we’ll see all three working together in <a class="ref" href="sign-up.html#sec-a_users_resource">Section 7.1.2</a>.</p>
<div class="label" id="sec-version_control"></div>
<h2><a id="sec-1_3" href="beginning.html#sec-version_control" class="heading"><span class="number">1.3</span> Version control with Git</a></h2>
<p>Now that we have a fresh and working Rails application, we’ll take a moment for a step that, while technically optional, would be viewed by many Rails developers as practically essential, namely, placing our application source code under <em>version control</em>. Version control systems allow us to track changes to our project’s code, collaborate more easily, and roll back any inadvertent errors (such as accidentally deleting files). Knowing how to use a version control system is a required skill for every software developer.</p>
<p>There are many options for version control, but the Rails community has largely standardized on <a href="http://git-scm.com/">Git</a>, a distributed version control system originally developed by Linus Torvalds to host the Linux kernel. Git is a large subject, and we’ll only be scratching the surface in this book, but there are many good free resources online; I especially recommend <a href="http://git-scm.com/book"><em>Pro Git</em></a> by Scott Chacon (Apress, 2009). Putting your source code under version control with Git is <em>strongly</em> recommended, not only because it’s nearly a universal practice in the Rails world, but also because it will allow you to share your code more easily (<a class="ref" href="beginning.html#sec-github">Section 1.3.4</a>) and deploy your application right here in the first chapter (<a class="ref" href="beginning.html#sec-deploying">Section 1.4</a>).</p>
<div class="label" id="sec-git_setup"></div>
<h3><a id="sec-1_3_1" href="beginning.html#sec-git_setup" class="heading"><span class="number">1.3.1</span> Installation and setup</a></h3>
<p>The first step is to install Git if you haven’t yet followed the steps in <a class="ref" href="beginning.html#sec-install_git">Section 1.2.2.2</a>. (As noted in that section, this involves following the instructions in the <a href="http://git-scm.com/book/en/getting-started-installing-git">Installing Git section of <em>Pro Git</em></a>.)</p>
<h4><a id="sec-1_3_1_1" href="beginning.html#sec-1_3_1_1" class="heading">First-time system setup</a></h4>
<p>After installing Git, you should perform a set of one-time setup steps. These are <em>system</em> setups, meaning you only have to do them once per computer:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> git config --global user.name <span class="s2">"Your Name"</span>
<span class="gp">$</span> git config --global user.email [email protected]
</pre></div>
</div>
<p>I also like to use <code>co</code> in place of the more verbose <code>checkout</code> command, which we can arrange as follows:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> git config --global alias.co checkout
</pre></div>
</div>
<p>This tutorial will usually use the full <code>checkout</code> command, which works for systems that don’t have <code>co</code> configured, but in real life I nearly always use <code>git co</code>.</p>
<p>As a final setup step, you can optionally set the editor Git will use for commit messages. If you use a graphical editor such as Sublime Text, TextMate, gVim, or MacVim, you need to use a flag to make sure that the editor stays attached to the shell instead of detaching immediately:<sup class="footnote" id="fnref-1_17"><a href="#fn-1_17">17</a></sup></p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> git config --global core.editor <span class="s2">"subl -w"</span>
</pre></div>
</div>
<p>Replace <code>"subl -w"</code> with <code>"mate -w"</code> for TextMate, <code>"gvim -f"</code> for gVim, or <code>"mvim -f"</code> for MacVim.</p>
<h4><a id="sec-1_3_1_2" href="beginning.html#sec-1_3_1_2" class="heading">First-time repository setup</a></h4>
<p>Now we come to some steps that are necessary each time you create a new <em>repository</em>. First navigate to the root directory of the first app and initialize a new repository:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> git init
<span class="go">Initialized empty Git repository in /Users/mhartl/rails_projects/first_app/.git/</span>
</pre></div>
</div>
<p>The next step is to add the project files to the repository. There’s a minor complication, though: by default Git tracks the changes of <em>all</em> the files, but there are some files we don’t want to track. For example, Rails creates log files to record the behavior of the application; these files change frequently, and we don’t want our version control system to have to update them constantly. Git has a simple mechanism to ignore such files: simply include a file called <code>.gitignore</code> in the application root directory with some rules telling Git which files to ignore.<sup class="footnote" id="fnref-1_18"><a href="#fn-1_18">18</a></sup></p>
<p>Looking again at <a class="ref" href="beginning.html#table-rails_directory_structure">Table 1.1</a>, we see that the <code>rails</code> command creates a default <code>.gitignore</code> file in the application root directory, as shown in <a class="ref" href="beginning.html#code-default_gitignore">Listing 1.6</a>.</p>
<div class="label" id="code-default_gitignore"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.6.</span> <span class="description">The default <code>.gitignore</code> created by the <code>rails</code> command.</span> </div>
<div class="code"><div class="highlight"><pre># See http://help.github.com/ignore-files/ for more about ignoring files.
#
# If you find yourself ignoring temporary files generated by your text editor
# or operating system, you probably want to add a global ignore instead:
# git config --global core.excludesfile ~/.gitignore_global
# Ignore bundler config
/.bundle
# Ignore the default SQLite database.
/db/*.sqlite3
# Ignore all logfiles and tempfiles.
/log/*.log
/tmp
</pre></div>
</div></div>
<p><a class="ref" href="beginning.html#code-default_gitignore">Listing 1.6</a> causes Git to ignore files such as log files, Rails temporary (<code>tmp</code>) files, and SQLite databases. (For example, to ignore log files, which live in the <code>log/</code> directory, we use <code>log/*.log</code> to ignore all files that end in <code>.log</code>.) Most of these ignored files change frequently and automatically, so including them under version control is inconvenient; moreover, when collaborating with others they can cause frustrating and irrelevant conflicts.</p>
<p>The <code>.gitignore</code> file in <a class="ref" href="beginning.html#code-default_gitignore">Listing 1.6</a> is probably sufficient for this tutorial, but depending on your system you may find <a class="ref" href="beginning.html#code-gitignore">Listing 1.7</a> more convenient. This augmented <code>.gitignore</code> arranges to ignore Rails documentation files, Vim and Emacs swap files, and (for OS X users) the weird <code>.DS_Store</code> directories created by the Mac Finder application. If you want to use this broader set of ignored files, open up <code>.gitignore</code> in your favorite text editor and fill it with the contents of <a class="ref" href="beginning.html#code-gitignore">Listing 1.7</a>.</p>
<div class="label" id="code-gitignore"></div>
<div class="codelisting">
<div class="listing"><span class="header">Listing 1.7.</span> <span class="description">An augmented <code>.gitignore</code> file.</span> </div>
<div class="code"><div class="highlight"><pre># Ignore bundler config
/.bundle
# Ignore the default SQLite database.
/db/*.sqlite3
# Ignore all logfiles and tempfiles.
/log/*.log
/tmp
# Ignore other unneeded files.
database.yml
doc/
*.swp
*~
.project
.DS_Store
.idea
</pre></div>
</div></div>
<div class="label" id="sec-adding_and_committing"></div>
<h3><a id="sec-1_3_2" href="beginning.html#sec-adding_and_committing" class="heading"><span class="number">1.3.2</span> Adding and committing</a></h3>
<p>Finally, we’ll add the files in your new Rails project to Git and then commit the results. You can add all the files (apart from those that match the ignore patterns in <code>.gitignore</code>) as follows:</p>
<div class="code"><div class="highlight"><pre><span class="gp">$</span> git add .
</pre></div>
</div>
<p>Here the dot ‘<code>.</code>’ represents the current directory, and Git is smart enough to add the files <em>recursively</em>, so it automatically includes all the subdirectories. This command adds the project files to a <em>staging area</em>, which contains pending changes to your project; you can see which files are in the staging area using the <code>status</code> command:<sup class="footnote" id="fnref-1_19"><a href="#fn-1_19">19</a></sup></p>