# Navigating Ruby Files with Vim - The Cheat Sheet

## Precision motions for Ruby

Look up Ruby motions by running `:help ruby-motion`.

<table>
  <tr>
    <th>command</th>
    <th>effect</th>
  </tr>
  <tr>
    <td>]m</td>
    <td>go to start of next method definition</td>
  </tr>
  <tr>
    <td>]M</td>
    <td>go to end of next (or current) method definition</td>
  </tr>
  <tr>
    <td>[m</td>
    <td>go to start of previous method definition</td>
  </tr>
  <tr>
    <td>[M</td>
    <td>go to end of previous method definition</td>
  </tr>
  <tr>
    <td>]]</td>
    <td>go to start of next module or class definition.</td>
  </tr>
  <tr>
    <td>[[</td>
    <td>go to start of previous module or class definition.</td>
  </tr>
  <tr>
    <td>%</td>
    <td>jump between matchin keyword pairs</td>
  </tr>
</table>

The `%` command is provided by the [matchit][] plugin. All of the other motions are implemented by [vim-ruby][].

## Text objects for working with Ruby

Look up Ruby motions by running `:help ruby-text-objects`.

<table>
  <tr>
    <th>command</th>
    <th>effect</th>
  </tr>
  <tr>
    <td>ir</td>
    <td>inside the current rubyblock</td>
  </tr>
  <tr>
    <td>ar</td>
    <td>around the current rubyblock</td>
  </tr>
  <tr>
    <td>im</td>
    <td>inside the current method definition</td>
  </tr>
  <tr>
    <td>am</td>
    <td>around the current method definition</td>
  </tr>
  <tr>
    <td>iM</td>
    <td>inside the current class or module</td>
  </tr>
  <tr>
    <td>aM</td>
    <td>around the current class or module</td>
  </tr>
</table>

The `ir` and `ar` text objects are supplied by the [textobj-rubyblock][] plugin. All of the other text objects are implemented by [vim-ruby][].

## Jump to filenames

When your `path` option is properly configured, you can use these commands to navigate your project:

<table>
  <tr>
    <th>command</th>
    <th>effect</th>
  </tr>
  <tr>
    <td>gf</td>
    <td>jump to the filename under the cursor</td>
  </tr>
  <tr>
    <td>:find&nbsp;{file}</td>
    <td>jump to the specified {file} in path</td>
  </tr>
</table>

## Jump to definitions

When your codebase has been indexed with ctags, you can use these commands to navigate your project:

<table>
  <tr>
    <th>command</th>
    <th>effect</th>
  </tr>
  <tr>
    <td>&lt;C-]&gt;</td>
    <td>jump to the first tag that matches the word under the cursor</td>
  </tr>
  <tr>
    <td>:tag&nbsp;{keyword}</td>
    <td>jump to the first tag that matches {keyword}</td>
  </tr>
  <tr>
    <td>g&lt;C-]&gt;</td>
    <td>prompt user to select from multiple matches for the word under the cursor. If only one match exists, jump to it without prompting.</td>
  </tr>
  <tr>
    <td>:tselect&nbsp;{keyword}</td>
    <td>prompt user to select from multiple matches for {keyword}. If only one match exists, jump to it without prompting.</td>
  </tr>
</table>

## Tab completion at Vim's command-line

At Vim's command line, you can use tab completion:

<table>
  <tr>
    <th>command</th>
    <th>effect</th>
  </tr>
  <tr>
    <td>&lt;Tab&gt;</td>
    <td>expand commandline to use next match</td>
  </tr>
  <tr>
    <td>&lt;S-Tab&gt;</td>
    <td>expand commandline to use previous match</td>
  </tr>
  <tr>
    <td>&lt;C-d&gt;</td>
    <td>show a list of all possible matches</td>
  </tr>
</table>

For example, if you type:

    :tag assert

Then press `<C-d>`, Vim will reveal a list of all `assert_*` methods. Press `<Tab>` to expand the command line to use the next match from that list.


[vim-ruby]: https://github.com/vim-ruby/vim-ruby
[textobj-rubyblock]: https://github.com/nelstrom/vim-textobj-rubyblock
[matchit]: http://www.vim.org/scripts/script.php?script_id=39