Setting up Sublime Text 3 for Rails Development

I’ve been a satisfied Sublime user for the past three years, using it primarily for Rails development. Here are the packages, preferences, and tips I recommend for getting the most out of this excellent editor.

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:


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 ⌥ opt⌘ cmdn 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.

Protip: if you prefix your path with the : character, AdvancedNewFile will create the file in the same directory as your current Sublime editor tab. (Note: I’m using the Primer theme in these screen recordings.)

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⌘ cmdw (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 ⌃ ctrlh in a Sublime editor and DashDoc immediately opens Dash to show the appropriate documentation based on the cursor position.

Don’t remember all the options for has_and_belongs_to_many? Just press ⌃ ctrlh.

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.

Emmet expands CSS-ish expressions into full-blown HTML markup. Just press ⇥ tab.

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.

Uncommitted changes show up in the gutter of the editor. No need to run git diff!

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.

Rubocop style violations in yellow. (If there were Ruby syntax errors, they would appear in red.)


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,
  "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
Goto Reference
Place the cursor on a method call and use Goto Definition… to jump to the source. In my key mappings I’ve set this to ⌥ opt⌘ cmdr.

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 ⌃ ctrlh 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.)


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:

class << ${1:self}

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 ⌘ cmdv 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.

A stylish alternative to the default Sublime icon.

To install the icon, first locate the Sublime Text application in the Finder and press ⌘ cmdi. 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!