I recently started a love affair with the Sublime Text 2 text editor. Looking around the web, I’m certainly not alone, and there are many great tips and tricks posts. I probably can’t write anything better than what’s already out there, so this post is really just an attempt to document for my future self my own customization decisions and the logic behind my choices.

I Need Another Text Editor Like I Need a Hole In The Head

An important piece of context for this post: I went looking for a new editor specifically because I was annoyed at switching between BBEdit on Mac and Notepad++ on Windows (I also use vi/vim/gvim on all platforms, but am not annoyed in the least with it). If either BBEdit of Notepad++ were on both platforms, I would be using it and not considering ST2. But they aren’t, and I am, and so much of this post is “how do I replicate this feature in Notepad++” or “I wish this cool BBEdit thing would work”. There’s even the short term effect of turning off interesting features in ST2 because I found them distracting. Long term I will revisit these choices, but in the short term my goal was to make ST2 as usable as BBEdit or Notepad++ as quickly as possible, even if that mean losing possible ST2 functionality.

Pay The Man

Sublime Text 2 is commercial software. It’s free to use right now (it is in beta) but the author reserves the right to charge in the future. After I used it for a while I didn’t need to wait. This software is definitely worth the $59 I paid for it, and I hope it motivates the author to keep working on it.

Settings

I might as well start this by jumping straight into the user settings. ST2 uses very readable JSON files to control things like preferences and keybindings. Setting “preferences” is really just opening a JSON file in the editor itself and typing away. All of the defaults are in a well-commented file, available from the “Settings – Default” menu option. Here’s a snippet of the file contents:

    // Set to true to insert spaces when tab is pressed
    "translate_tabs_to_spaces": false,

    // If translate_tabs_to_spaces is true, use_tab_stops will make tab and
    // backspace insert/delete up to the next tabstop
    "use_tab_stops": true,

    // Set to false to disable detection of tabs vs. spaces on load
    "detect_indentation": true,

    // Calculates indentation automatically when pressing enter
    "auto_indent": true,

Two great side effect of using a commented text file for configuration: Finding an option is as easy as searching for a keyword, and the configuration is versionable. The awesomeness of neither of these should be underestimated.

Once you find a setting you want to tweak, open the user-specific settings file (“Settings – User”) and add them there. Here is my current user-specific settings file, followed by some brief discussion of why I set the option:

{
    "auto_match_enabled": false,
    "auto_complete": false,
    "color_scheme": "Packages/Color Scheme - Default/Mac Classic.tmTheme",
    "draw_white_space": "all",
    "font_face": "Courier New",
    "trim_automatic_white_space": false,
}

• auto_match_enabled – This is a great example of what is probably a powerful feature that my own habits made me turn off. This option controls whether or not ST2 auto-closes braces and brackets for you. I really liked the idea of this option, but in practice it was more trouble than it was worth. It would auto-add the closing brace, and then I would either have to arrow/mouse past the auto-added closing brace, or forget that it had been added already and re-add it, which would cause me to go back and remove the extra closing brace. If I were to reimplement this feature, I would make ST2 try to detect whether I had just added an extra closing brace. If I had, ST2 should remove the auto-added brace. In the short term, it’s just easier to turn this feature off entirely.
• auto_complete – While I had it turned on, auto_complete was pretty interesting. The auto-complete of functions, language keywords, etc, was great. The problem is that the little box that popped up for auto-completion options while you typed, even if you didn’t want to auto-complete, that I had to turn it off. I think there are more tunables around this (for instance, increasing delay before completion options are presented, or requiring a manual keystroke to get completion options) but in the short term this option was actually making me less productive so I just turned it off.
• color_scheme – I wanted to like all the dark color schemes that ST2 had to choose from, but in the end I had to have a white background. The “Mac Classic” theme was the best “white background” theme I could find (which probably means it’s the closest to what Notepad++ uses by default).
• draw_white_space – Visual white space was one of the first features on Notepad++ that I became completely addicted to and could not live without. This option actually has three settings – “none”, “selection”, and “all”, with “selection” being the default. “Selection” (in which whitespace is only made visual in selected text) is actually a really nice idea, but I had gotten addicted to having it turned on all the time.
• font_face – When I first began using ST2 I had a hard time engaging with it. One of the factors were the dark-by-default themes, which I changed fairly quickly, but there was a lingering discomfort too that took me a while to identify. I eventually realized that I wasn’t comfortable with the default font. ST2 ships with “Consolas” as the default font on Windows, and “Menlo Regular” as the default on Mac OS X. Changing these both to “Courier New” made a huge difference in my comfort in making ST2 my default editor.
• trim_automatic_white_space – Another feature I turned off. ST2 has a fantastic auto-indenter (better than Notepad++’s in my opinion) but this feature worked against me. Apparently I move the I-beam around a lot when I am working, and this feature caused the auto-added whitespace to be removed when I (very temporarily) moved the I-beam off the line, which was pretty awful. I think one reason this was left on was that, technically, it results in “trailing white space” when you don’t type anything on a line. I happen to see this as a feature when also using visual white space

Sane Tab-Switching

Another tweak I made was changing the default tab-switching behavior. The default, stack-like, MRU-ish behavior was unnatural to me. I changed it to the more standard “cycle in tab order” style. This is done in the “Preferences -> Key Bindings – User” file, by adding these two lines:

    { "keys": ["ctrl+tab"], "command": "next_view" },
    { "keys": ["ctrl+shift+tab"], "command": "prev_view" }

Indenting

I’m of mixed opinion on ST2’s indenting vs. Notepad++’s (they are both better than BBEdit). Out of the box, I think Notepad++’s is better, but with some tweaking I’m starting to think that ST2 has pulled ahead.

Understanding Alternate Indenting Styles

ST2 is definitely better at following the indent of the previous line, rather than sticking slavishly to the indents set for the file. Specifically, consider the case of a single “line” of code split across multiple lines. In that case I “tab” to the natural indent, and then indent with spaces after that. In Notepad++, on the second space-indented line, it will indent with tabs, because it “knows” that tabs are the indent character for that doc. Sublime Text 2, on the other hand, will recognize that I’ve altered my indenting and will use the same indenting for following lines:

Reindenting

One area I’m really torn over is “re-indenting”. I suspect that Sublime Text 2 is technically better at it, but that it’s more effort to make it work. I maintain a lot of legacy code has often been maintained by copying tabbed code out of a teminal and then pasted into a new file, resulting in 8-space indents, instead of the 4-space-tab indents we’ve agreed to use. In Notepad++, reindenting that code is very easy – Change a tab to 8-spaces in the preferences, select the entire block you want to re-indent, then hit tab (which indents the entire block one additional level, but also changes the 8-spaces into tabs), then hit shift-tab (which removes the extra indent level you just added, but leaves you with tabs instead of spaces). Then change you tabs back to 4-spaces, and you’re done. (It sounds complex as I read that back to myself, but it’s a fairly fluid action.)

Sublime Text 2, on the other hand, doesn’t quite do this (by default). It will block-indent/unindent of course, but it won’t automatically convert spaces to tabs. I finally realized that there’s an actual menu option to do what I want (Edit -> Line -> Reindent), and it works reasonably well. I haven’t figured out all of the nuances yet, but it is not 100% rock-solid as Notepad++’s functionality. It is good enough to use though. It lacks a default key binding, and I use it enough that I added one (Preferences -> Key Bindings – User) to bind ctrl+shift+r to Reindent:

    { "keys": ["ctrl+shift+r"], "command": "reindent" }

Awesome stuff

While I first focused on getting ST2 modified to be as similar as possible to Notepad++ or BBEdit, there are (at least) a few things that have stood out as being awesome and unique to Sublime Text 2 (as far as I know).

Scrolling Past “End Of File”

The first one is really simple but amazingly useful. When you scroll a file in ST2, you can scroll “past” the end of the file. In other words, you can scroll all the way until the last line of the file is the only visible line in the document (contrasting with the standard practice of allowing you to scroll until the last line in the file is on the last (bottom) visbile line in the editor window). This is shockingly useful, and not even abstractly – I’ve spent the last 15 years adding 20 lines of whitespace to the bottom of files as a poor-man’s version of this. Having it as a native feature in the editor is wonderful, and a great example of something I never would have thought to ask for, because “that’s not how editors work”.

Update 2013-02-20: I recently switched to Mac OS X as my primary work environment and realized that this behavior is not the default on Mac OS X for some reason. Set “scroll_past_end” to true in your user preferences to enable this. I haven’t discovered why this option’s default value isn’t the same for all platforms

“minimap”

The minimap is another area that is phenomenal. It’s like a visual scroll-bar, with sensitity set halfway between just scrolling the I-beam with the arrow keys and dragging the actual scrollbar. It’s so good that I only just realized that the standard scrollbar doesn’t have arrows on the top and bottom – I’ve never needed to use them!

Update 2012-07-25: Mike points out in the comment that Notepad++ does have the same functionality as ST2’s minimap, available from View -> Document Map. I had never used this feature in NPP before, but I tried it out for the sake of fairness and in my opinion it’s not as good as ST2’s implementation. In brief:

• NPP’s Document Map doesn’t include the current document’s language syntax coloring. ST2’s inclusion of this definitely helps when scanning docs.
• NPP’s “scroll thumb” doesn’t properly map to the top and bottom of a long document. Specifically, I opened a 2700 line file, then drug the thumb to the bottom of the document map. In ST2 I’m now viewing lines ~2660-2700. In NPP I’m now viewing lines ~540-600. If you fiddle with the mouse you can make the thumb scroll you through the document, but it’s an annoying experience and doesn’t provide any visual feedback on the overall length of the document (a sense of where you are in the document) while scrolling.
• This is clearly a bug and not an implementation choice, but the doc I opened happened to be a perl script with no suffix, so NPP didn’t apply any language syntax highlighting to it (ST2 correctly detects perl, but that’s a different issue). To test whether NPP’s map would use the language highlighting, I manually changed the doc to perl, and the document map turned black and stayed black until I closed the map and re-opened it. Not the best first impression.

All in all the NPP would probably serve the purpose if I had other reasons to stay with NPP, but it’s implementation definitely feels like something tacked on. ST2’s map feels like a first-class feature, with performance similar to the rest of the product.

Easy and Powerful Layout Switching

Another feature I didn’t know I needed was the fast layout switching. The ability to quickly change from one-up to two-up, vertical or horizontal layouts is really powerful. Since there’s no cognitive overhead to changing the layout (View -> Layout -> (option)) or moving documents to different frames, I’m much more likely to use it to compare docs, or use another doc as a ref, which I’ve found has a noticeable performance benefit.

Project and Folders

One feature I didn’t really think I would use was projects, or adding folders to an editor window. It turns out that I tried it an instantly benefitted from it. I haven’t developed an ecosystem of “projects”, but I have found that I add and remove folders from my editor fairly regularly as I work. Being able to have all my files quickly reachable from within the editor itself, even if I don’t have them open for editing, is another time saver.

Open Issues

I don’t have a ton of open issues, but there are a couple of areas I’m still trying to figure out.

Unfocused Clicks on Minimap

The first is an issue with clicking in the minimap. When Sublime Text 2 is in focus, clicking in the minimap, but outside of the “this is what you’re currently looking at” grey box, will jump you to where you clicked. This makes sense. However, it does the exact same thing if the ST2 window does NOT have focus. I’ve lost the link now but this was raised on the ST2 forums and the author flatly stated that it wass working as designed and he would not change it. In my opinion this is a really poor design choice. I often switch back and forth between an editor, a terminal, and an scp client, and I can do it quickly my keeping parts of the windows visible and clicking into them. This works great until I click into ST2 and suddenly I’m in a completely different part of the file because the part that was visible to click was the minimap. More than anything, it surprised me that the author was so completely against it, to the point of being unwilling to offer a switch for the behavior. I’ve learned to live with it but I’m still puzzled at the choice.

“Find All” Results

In general I’ve found searching in ST2 to be as good as searching in Notepad++, possibly a little better. However, one of the few areas I’ve found in which Notepad++ is inarguably better (to the point where I suspect maybe I just haven’t found the right interface in ST2) is in the “Find all in document”, “Find all in open files”, and “Find in files” interfaces. It’s not that ST2 doesn’t have these options, it’s that the results are unusable. In Notepad++, there is a tray that opens from the bottom of the window that show all the matches and (if applicable), which file they are from. These results can be copied, they can be collapsed by file name, and double clicking the line takes you that that line in the appropriate file.

When searching in files, you can almost recreate the Notepad++ experience. The results are presenting as in a new document. Using a 2-up, row-based layout, you can have the results and the documents visible at the same time, and it appears that you can collapse files and double-click lines to go to the files. However, this might be a case where flexibility actually hampers instead of helps. I still much prefer the Notepad++ interface for this vs. the ST2 interface. Additionally, that only really seems to be for “find in files”. When doing “Find All” in just the active document, you end up with each match selected, but I haven’t found a good view of each of those matches. I’m not sure if this it a shortcoming of ST2 or my ability to use it, but the area of finding multiple matches is one of the few areas I think Notepad++ is genuinely a better use experience than ST2.

Split Screen Editing Of A Single Document

One last item I would like to have is, surprisingly, a feature in BBEdit that I haven’t found in either Notepad++ or Sublime Text 2, and that’s split-editing a single document. It’s can be wonderful to use one part of document as reference while editing a a different location in the same document. I bet you could kludge something up for this in both NPP and ST2, but the ease of just grabbing the “splitter” on the scrollbar to make it happen is pretty wonderful, and something I would love to have in ST2.

Update 2012-07-16: I had not pursued this complaint more, but Antonio fills in the missing details in the comments below. File -> New File Into View does indeed open up a second “live” view of the doc (meaning I can type into one and the new typing is echoed in the other view in real time). The second live tab can then be manipulated using the standard View -> Layout options. This was much less discoverable than the scrollbar slider solution in BBEdit but much more powerful since you get access to the full set of Layout options.

Update 2012-10-14: And from Ilja in the comments regarding split-view editing in Notepad++: “It actually has been available in NPP for quite a while now. You access it by right clicking on a document tab and choosing “Clone to Other View” menu item.” Ayup. Interesting that ST2 and NPP have very similar ways to access this feature, and I was looking for the BBEdit style (which I also like to think of as the “MS Word 5 for Mac” style).

And For My Next Trick

This post has existed as a draft for the last several weeks. I knew it was time to finish it when I stopped noting “how to make ST2 as good as Notepad++” and started jotting down features I’d found that were entirely new. So, I’ll let this post stand for now, a summary of changes I made to bring the features of Sublime Text 2 quickly up to par with those of Notepad++ and BBEdit that I was used to using daily.