*rails.txt* Plugin for working with Ruby on Rails applications
Author: Tim Pope
|rails-introduction| Introduction and Feature Summary
|rails-navigation| Navigation
|rails-gf| File Under Cursor - gf
|rails-alternate-related| Alternate and Related Files
|rails-type-navigation| File Type Commands
|rails-exec| Executable Wrappers
|rails-refactoring| Refactoring Helpers
|rails-partials| Partial Extraction
|rails-migrations| Migration Inversion
|rails-misc| Miscellaneous Commands
|rails-integration| Integration
|rails-vim-integration| Integration with the Vim Universe
|rails-rails-integration| Integration with the Rails Universe
|rails-syntax| Syntax Highlighting
|rails-projections| Projections
|rails-configuration| Configuration
|rails-global-settings| Global Settings
|rails-about| About rails.vim
|rails-license| License
INTRODUCTION *rails-introduction* *rails*
Whenever you edit a file in a Rails application, this plugin will be
automatically activated. This sets various options and defines a few
buffer-specific commands.
If you are in a hurry to get started, with a minimal amount of reading, you
are encouraged to at least skim through the headings and command names in this
file, to get a better idea of what is offered. If you only read one thing,
make sure it is the navigation section.
NAVIGATION *rails-navigation*
Navigating the twisted file hierarchy of Rails projects is what initially
inspired the creation of this plugin.
The standard Rails load path is prepended to 'path', enabling |:find| to work:
>
:find application_controller
<
In asset files, 'path' is instead set to the asset load path, and
'suffixesadd' is set to a long list of possible JavaScript or CSS suffixes.
File Under Cursor - gf ~
*rails-gf*
The |gf| command, which normally edits the current file under the cursor, has
been remapped to take context into account. |CTRL-W_f| (open in new window),
|CTRL-W_gf| (open in new tab), and |c_CTRL-R_CTRL-F| (insert filename on
command line) are also remapped.
Example uses of |gf|, and where they might lead.
(* indicates cursor position)
>
Pos*t.first
< app/models/post.rb ~
>
has_many :c*omments
< app/models/comment.rb ~
>
link_to 'Home', :controller => 'bl*og'
< app/controllers/blog_controller.rb ~
>
<%= render 'sh*ared/sidebar' %>
< app/views/shared/_sidebar.html.erb ~
>
<%= stylesheet_link_tag 'appl*ication' %>
< app/assets/stylesheets/application.css ~
>
class BlogController < Applica*tionController
< app/controllers/application_controller.rb ~
>
class ApplicationController < ActionCont*roller::Base
< .../action_controller/base.rb ~
>
fixtures :pos*ts
< test/fixtures/posts.yml ~
>
layout :pri*nt
< app/views/layouts/print.html.erb ~
>
<%= link_to "New", new_comme*nt_path %>
< app/controllers/comments_controller.rb (jumps to def new) ~
In the last example, the controller and action for the named route are
determined by evaluating routes.rb as Ruby and doing some introspection. This
means code from the application is executed. Keep this in mind when
navigating unfamiliar applications.
Alternate and Related Files ~
*rails-alternate-related*
Two commands, :A and :R, are used to quickly jump to an "alternate" and a
"related" file, defined below.
*rails-:A* *rails-:AE* *rails-:AS* *rails-:AV* *rails-:AT* *rails-:AD*
:A These commands were picked to mimic Michael Sharpe's
:AE a.vim. Briefly, they edit the "alternate" file, in
:AS either the same window (:A and :AE), a new split
:AV window (:AS), a new vertically split window (:AV), a
:AT new tab (:AT), or read it into the current buffer
:AD (:AD). With a range (:.A), they find the "related"
file for the specified line. With a filename
argument, they edit a file relative to the application
root (:A Rakefile), and with both a count and a
filename (:1A post.rb), they find a file in 'path',
similar to |:find| but with smarter tab completion.
*rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT* *rails-:RD*
:R These are similar |rails-:A| and friends above, only
:RE they default to the "related" file rather than the
:RS "alternate." :R is equivalent to :.A and :0R is
:RV equivalent to :.A. The filename and count version
:RT (:1R post.rb) is hard coded to use the application
:RD load path rather than 'path', so that one can access
Ruby files regardless of 'filetype'.
*rails-alternate* *rails-related*
The alternate file is most frequently the test file, though there are
exceptions. The related file varies, and is sometimes dependent on current
location in the file. For example, when editing a controller, the related
file is template for the method currently being edited.
The easiest way to learn these commands is to experiment. A few examples of
alternate and related files for a Test::Unit application follow:
Current file Alternate file Related file ~
model unit test schema definition
controller (in method) functional test template (view)
template (view) functional test controller (jump to method)
migration previous migration next migration
database.yml database.example.yml environments/*.rb
Alternates can be tweaked with |rails-projections|.
File Type Navigation Commands ~
*rails-type-navigation*
For the less common cases, a more deliberate set of commands are provided.
Each of the upcoming commands takes an optional argument (with tab completion)
but defaults to a reasonable guess. Commands that default to the current
model or controller generally behave like you'd expect in other file types.
For example, in app/helpers/posts_helper.rb, the current controller is
"posts", and in test/fixtures/comments.yml, the current model is "comment".
In model related files, the current controller is the pluralized model name,
and in controller related files, the current model is the singularized
controller name.
Each of the following commands has variants for splitting, vertical splitting,
opening in a new tab, and reading the file into the current buffer. For
:Emodel, those variants would be :Smodel, :Vmodel, :Tmodel, and :Dmodel.
They also allow for jumping to methods or line numbers using the same syntax
as |:rails-R|, and file creation (with a bit of boilerplate) can be forced by
adding a ! after the filename (not after the command itself!).
Additionally, for each unrecognized directory of the form app/{type}s/
containing at least one file matching *_{type}.rb, a command of the form
:E{type} is automatically defined.
:Econtroller |rails-:Econtroller|
:Eenvironment |rails-:Eenvironment|
:Efixtures |rails-:Efixtures|
:Efunctionaltest |rails-:Efunctionaltest|
:Ehelper |rails-:Ehelper|
:Einitializer |rails-:Einitializer|
:Eintegrationtest |rails-:Eintegrationtest|
:Ejavascript |rails-:Ejavascript|
:Elayout |rails-:Elayout|
:Elib |rails-:Elib|
:Elocale |rails-:Elocale|
:Emailer |rails-:Emailer|
:Emigration |rails-:Emigration|
:Emodel |rails-:Emodel|
:Eschema |rails-:Eschema|
:Espec |rails-:Espec|
:Estylesheet |rails-:Estylesheet|
:Etask |rails-:Etask|
:Eunittest |rails-:Eunittest|
:Eview |rails-:Eview|
*rails-:Econtroller* *rails-:Rcontroller*
:Econtroller [{name}] Edit the specified or current controller.
*rails-:Eenvironment* *rails-:Renvironment*
:Eenvironment [{name}] Edit the config/environments file specified. With no
argument, defaults to editing config/application.rb
or config/environment.rb.
*rails-:Efixtures* *rails-:Rfixtures*
:Efixtures [{name}] Edit the fixtures for the given or current model. If
an argument is given, it must be pluralized, like the
final filename (this may change in the future). If
omitted, the current model is pluralized. An optional
extension can be given, to distinguish between YAML
and CSV fixtures.
*rails-:Efunctionaltest* *rails-:Rfunctionaltest*
:Efunctionaltest [{name}]
Edit the functional test or controller spec for the
specified or current controller.
*rails-:Ehelper* *rails-:Rhelper*
:Ehelper [{name}] Edit the helper for the specified name or current
controller.
*rails-:Einitializer* *rails-:Rinitializer*
:Einitializer [{name}] Edit the config/initializers file specified. With no
argument, defaults to editing config/routes.rb.
*rails-:Eintegrationtest* *rails-:Rintegrationtest*
:Eintegrationtest [{name}]
Edit the integration test, integration spec, or
cucumber feature specified. With no argument,
defaults to editing test/test_helper.rb.
*rails-:Ejavascript* *rails-:Rjavascript*
:Ejavascript [{name}] Edit the JavaScript for the specified name or current
controller. Also supports CoffeeScript in
app/scripts/.
*rails-:Elayout* *rails-:Rlayout*
:Elayout [{name}] Edit the specified layout. Defaults to the layout for
the current controller, or the application layout if
that cannot be found. A new layout will be created if
an extension is given.
*rails-:Elib* *rails-:Rlib*
:Elib [{name}] Edit the library from the lib directory for the
specified name. With no argument, defaults to editing
the application Gemfile (a task formally handled by
the defunct :Rplugin).
*rails-:Elocale* *rails-:Rlocale*
:Elocale [{name}] Edit the config/locale file specified, optionally
adding a yml or rb extension if none is given. With
no argument, checks config/environment.rb for the
default locale.
*rails-:Emailer* *rails-:Rmailer*
:Emailer [{name}] Edit the specified mailer.
*rails-:Emigration* *rails-:Rmigration*
:Emigration [{pattern}] If {pattern} is a number, find the migration for that
particular set of digits, zero-padding if necessary.
Otherwise, find the newest migration containing the
given pattern. Omitting the pattern selects the
latest migration. Give a numeric argument of 0 to edit
db/seeds.rb.
*rails-:Emodel* *rails-:Rmodel*
:Emodel [{name}] Edit the specified or current model.
*rails-:Espec* *rails-:Rspec*
:Espec [{name}] Edit the given spec. With no argument, defaults to
editing spec/spec_helper.rb (If you want to jump to
the spec for the given file, use |rails-:A| instead).
This command is only defined if there is a spec folder
in the root of the application.
*rails-:Eschema* *rails-:Rschema*
:Eschema [{table}] Edit the schema and optionally jump to the specified
table.
*rails-:Estylesheet* *rails-:Rstylesheet*
:Estylesheet [{name}] Edit the stylesheet for the specified name or current
controller. Also supports Sass and SCSS.
*rails-:Etask* *rails-:Rtask*
:Etask [{name}] Edit the .rake file from lib/tasks for the specified
name. If no argument is given, the application
Rakefile is edited.
*rails-:Eunittest* *rails-:Runittest*
:Eunittest [{name}] Edit the unit test or model spec for the specified
name or current model.
*rails-:Eview* *rails-:Rview*
:Eview [[{controller}/]{view}]
Edit the specified view. The controller will default
sensibly, and the view name can be omitted when
editing a method of a controller. If a view name is
given with an extension, a new file will be created.
This is a quick way to create a new view.
Finally, one Vim feature that proves helpful in conjunction with all of the
above is |CTRL-^|. This keystroke edits the previous file, and is helpful to
back out of any of the above commands.
EXECUTABLE WRAPPERS *rails-exec*
Several commands are provided that wrap the `rails` and `rake` executables.
Additionally, `rails` (or `rake` on Rails versions older than 5) can be
invoked directly with |:make| or dispatch.vim's :Make.
*rails-:Rails*
:Rails {command} [options]
Invoke "rails {command}". On older versions of Rails,
it will conditionally invoke "rake {command}" and
"script/{command}" when appropriate. Uses |:!| or
dispatch.vim's :Start if the command is "console",
"dbconsole", or "server". Otherwise, the "rails"
|:compiler| plugin included with the plugin is
temporarily enabled, and |:make| or dispatch.vim's
:Make is used to load the output into the quickfix
list.
Unlike other commands, :Rails is available globally,
for use with the "new" subcommand.
:Rails With no command, runs a default task based on the
current file. See |rails-default-task|.
*rails-:Rscript*
:Rscript {command} [options]
Deprecated alias for |:Rails| {command}.
*rails-:Console*
:Console {options} Launch rails console {options}. If dispatch.vim's
:Start is available, that is used. Otherwise,
executes directly in the foreground.
*rails-:Generate* *rails-:Rgenerate*
:Generate {options} Invoke rails generate {options} and loads the
generated files into the quickfix list. Use ! to
suppress jumping to the first file.
*rails-:Destroy* *rails-:Rdestroy*
:Destroy {options} Invoke rails destroy {options} and loads the destroyed
files into the quickfix list.
*rails-:Server* *rails-:Rserver*
:Server {options} Launch rails server {options} in the background. If
dispatch.vim's :Start is available, that is used.
Otherwise, the --daemon option is passed in.
*rails-:Server!* *rails-:Rserver!*
:Server! {options} Kill the pid found in tmp/pids/server.pid and then
invoke :Server.
*rails-:Runner* *rails-:Rrunner*
:[range]Runner [file] Run the given file or code with rails runner and load
:Runner {code} the results in to the quickfix list, using the error
parser from the "ruby" |:compiler|. If the file looks
like a test, spec, or cucumber feature, the
"rubyunit", "rspec", or "cucumber" |:compiler| will be
used instead. If provided, [range] is passed to the
test runner to restrict execution to a particular
line. With no argument, defaults to running the test
for the current file.
*rails-:Rp*
:[range]Rp {code} Use rails runner to execute "p begin {code} end" and
echo the result.
*rails-:Rpp*
:[range]Rpp {code} Like :Rp, but with pp (pretty print).
*rails-:Rake*
:[range]Rake {task} Invoke `rake`. Generally, you are encouraged to use
|:Rails| or directly invoke |:make| instead.
*rails-default-task*
Invoking |:Rails| with no arguments runs a default task. This is typically
the associated test task, but can also be a closely related utility task.
File Task ~
test/*_test.rb test TEST=test/*_test.rb
spec/*_spec.rb spec SPEC=spec/*_spec.rb
features/*.feature cucumber FEATURE=features/*.feature
app/*.rb test TEST=... | spec SPEC=...
test/fixtures/*.yml db:fixtures:load FIXTURES=*
config.ru middleware
config/routes.rb routes
db/migrate/*_*.rb db:migrate:redo VERSION=*
db/schema.rb db:migrate:status
db/seeds.rb db:seed
README about
For some files, giving the command a range (e.g., :.Rails) triggers a variant
of the task to be performed.
File Task when given range ~
test/*_test.rb test TEST=test/*_test.rb TESTOPTS=-n
spec/*_spec.rb spec SPEC=spec/*_spec.rb:
features/*.feature cucumber FEATURE=features/*.feature:
test/fixtures/*.yml db:fixtures:identify LABEL=