Setting up Sublime Text 3 for Rails Development

These recommendations are for Sublime Text 3, which is currently in beta, but stable. I’ll keep this article updated as my Sublime preferences change over time. You can also peek at my latest Sublime Text settings files and snippets by browsing my dotfiles repository on GitHub. Enjoy!

Jump to:

• Packages
• Settings
• Snippets
• Key mappings
• Custom theme and icon

Packages

Did you know that there is a fantastic online repository and discovery tool for Sublime Text packages? The plugin community for Sublime is huge, and there are more packages being added all the time. Here are the handful of packages that I consider must-haves for Rails development.

Of course, make sure you have Package Control installed first!

AdvancedNewFile

I use AdvancedNewFile to quickly create files at any level of a project folder hierarchy without needing to take my hands off the keyboard. This is really useful for Rails, where even a brand new project contains dozens of directories.

Just press CMD-OPT-N and type the path (relative to the root of your project) of the file you want to create and press RETURN. AdvancedNewFile supports tab-completion, so you can quickly expand existing directory names.

All Autocomplete

Sublime ships with autocomplete behavior, but it is limited to completing strings that exist in the current editor. With All Autocomplete installed, all open files are searched for autocompletion candidates.

Clipboard Manager

Programming involves lots of copy and paste, so I consider clipboard history to be essential. There are system-wide solutions, but Clipboard Manager gets the job done for Sublime Text. It keeps a history of all copied text, and allows me to use keyboard shortcuts to browse that history or to cycle through previously copied text.

CloseOtherWindows

It’s easy for tabs to get out of control, so I like to activate a “focus mode” where I close all tabs except the one I’m working on. CloseOtherWindows provides exactly such a command, which you can activate with a right-click, or assign a keyboard shortcut. I use to SHIFT-CMD-W (see my key mappings below).

DashDoc

I’m a big fan of Dash, which is a programming documentation browser for the Mac. Assuming Dash is installed, I can simply press CTRL-H in a Sublime editor and DashDoc immediately opens Dash to show the appropriate documentation based on the cursor position.

DocBlockr

This is an install-and-forget-it enhancement to Sublime that saves me keystrokes when writing multi-line code comments. When I hit RETURN while writing a Ruby comment, DocBlockr will helpfully indent and add the leading # on the next line. Works for other languages, too.

Emmet

I write my Rails views with ERB-flavored HTML, so Emmet is an incredible time-saver. The headline feature is that it makes writing complex nested markup super easy, but it has expansions and auto-completion for writing CSS/SCSS as well. There’s too much to explain in detail here, so be sure to check out the Emmet docs.

GitGutter

Shows what lines I’ve changed, added, or removed in comparison to the local git repository. GitGutter is a no-brainer if you use git.

SublimeLinter

This one is actually three separate packages: SublimeLinter, SublimeLinter-Ruby, and SublimeLinter-rubocop. With these installed, Sublime lints my Ruby code as I type! If I’m not satisfied with the default rules, I can tweak style enforcement using ~.rubocop.yml. Check out the Rubocop documentation for details.

Settings

Packages aside, there are a bunch of built-in settings that I like to tweak to make Sublime work great as a Rails editor. Here are the important ones:

{
  "auto_complete": true,
  "auto_complete_commit_on_tab": true,
  "copy_with_empty_selection": true,
  "ensure_newline_at_eof_on_save": true,
  "index_files": true,
  "rulers":
  [
    79
  ],
  "tab_size": 2,
  "translate_tabs_to_spaces": true,
  "trim_trailing_white_space_on_save": true,
}

Indexing

This is one setting that deserves a special note. I always thought that source code indexing required a fancy IDE or a separate plugin, like ctags. But no! Sublime Text 3 does indexing, and it works great with Ruby. Just make sure it is turned on:

{
  "index_files": true
}

Ruby-specific word selection behavior

When you double-click a word, or use any other word-related text selection commands, Sublime tries to be smart about where words begin and end. By default, it assumes punctuation is not part of the word. But in Ruby, punctuation can be part of method names: e.g. empty? and chomp!, among many others.

To tell Sublime to include those trailing ? and ! characters in word selections, add the following property to the Ruby syntax-specific settings. This has a side-effect of improving the Dash CTRL-H behavior as well!

{
  "word_separators": "./\\()\"'-:,.;<>~@#$%^&*|+=[]{}`~"
}

(To get to the Ruby settings, open a Ruby file in the editor and then navigate the menus to Sublime Text → Preferences → Settings – More → Syntax Specific – User.)

Snippets

Unlike TextMate, where I was always creating snippets and coding up customizations, Sublime Text and its powerful assortment of community-supplied packages do almost everything I need with minimal fuss. The built-in Ruby and Rails syntaxes and snippets are great.

There’s really just one notable case where I’ve needed to open the hood and add my own stuff.

Singleton class snippet

I’m always forgetting how to open the singleton class (eigenclass) in Ruby. The syntax just doesn’t come naturally to me: class << self ... end. Here’s my snippet, activated by meta TAB:

<snippet>
  <content><![CDATA[
class << ${1:self}
  $0
end
]]></content>
  <tabTrigger>meta</tabTrigger>
  <scope>source.ruby</scope>
</snippet>

Key mappings

For the most part, I am happy with Sublime’s default key mappings. There are just a few instances where I’ve tweaked the mappings to make them more consistent with other Mac editors like TextMate and Sublime.

I also like changing the behavior of CMD-V so that it does paste-and-indent, which is what I want 99% of the time.

[
  { "keys": ["super+\\"], "command": "toggle_side_bar" },
  { "keys": ["super+shift+\\"], "command": "reveal_in_side_bar"},
  { "keys": ["super+shift+w"], "command": "close_other_tabs" },

  { "keys": ["super+backspace"], "command": "run_macro_file", "args": {"file": "res://Packages/Default/Delete Line.sublime-macro"} },

  { "keys": ["super+shift+r"], "command": "goto_symbol_in_project" },
  { "keys": ["super+alt+r"], "command": "goto_definition" },

  { "keys": ["super+shift+t"], "command": "reopen_last_file" },

  { "keys": ["super+x"], "command": "clipboard_manager_cut" },
  { "keys": ["super+c"], "command": "clipboard_manager_copy" },
  { "keys": ["super+v"], "command": "clipboard_manager_paste", "args": { "indent": true } },
  { "keys": ["super+ctrl+v"], "command": "clipboard_manager_paste", "args": { "indent": false } },
  { "keys": ["super+shift+v"], "command": "clipboard_manager_previous_and_paste" },
  { "keys": ["super+alt+ctrl+v"], "command": "clipboard_manager_choose_and_paste" },
]

Custom theme and icon

The “Primer” theme

I prefer a light theme for my editor, and Primer is by far the most polished (it’s the one you see in all the screenshots above). It also fits nicely with the OS X Yosemite look and feel. To use it, just install Primer using Package Control and follow the instructions that appear. I’ve also customized the theme a bit further with these settings:

{
  "color_scheme": "Packages/User/SublimeLinter/primer.light (SL).tmTheme",
  "theme": "Primer.sublime-theme",
  "theme_primer_sidebar_font_large": true,
  "theme_primer_sidebar_tree_small": true,
  "theme_primer_tabs_font_large": true
}

Custom icon

Finally, I’ve replaced the default Sublime Text icon with something a bit more contemporary, designed by the talented Rafael Conde. You can download his icon from Dribbble.

To install the icon, first locate the Sublime Text application in the Finder and press CMD-I. Then drag and drop Rafael’s Sublime Text.icns file onto icon section of the Get Info window. If Sublime is in your Dock, you may need to restart the Dock process for the new icon to appear.

And that’s it! You made it to the end of my Sublime Text 3 setup guide. Thanks for reading!