Sublime Text 3’s user configuration

adminIDE, sublime0 Comment
10 min. reading

As you probably know, there are no configuration dialogs, windows or generally any UI to click-through configure your Sublime Text 3. Actually, nearly everything is customized by editing ST3 configuration files.

Default configuration file is very well documented, but it is quite long and may be overwhelming. To help some of you with that problem, I wrote this article, where I show the list of configuration settings that I changed in my own development environment, that you may find interesting or at list worth considering.

If you play with Sublime Text 3 configuration files for the first time, first open both files (default and user) in two separate tabs, by clicking Preferences > Settings — Default and Preferences > Settings — User. Remember to edit only second file (its values overrides everything in default file) and to use default configuration file only as reference and source of information.

The list

Before we continue, I must explain, that I’ve been using Netbeans for about five years and when I decided to drop it, I was also considering phpStorm (both IDEs dropped off my list, because they’re Java-based, hellishly slow). So, some of entries on my personal list (below) are inspired by either of these two IDEs.

Here are flags that I changed in my ST3; list with a little bit comment:

  • "translate_tabs_to_spaces": true — because I’m the one of those, who thinks that tabs are pure evil,
  • "match_brackets_content": false:
    • I don’t like the idea of underlining brackets when cursor is anywhere inside them;
    • I much more prefer, when brackets are underlined / marked only when cursor stands next or before any of it,
  • "highlight_line": true — to have entire line with cursor highlighted; purely personal decision
  • scroll_past_end": false:
    • I don’t like the idea of empty editor field, with just the last line of code standing in the top;
    • last line places is always in the bottom, according to my personal zen,
  • "draw_white_space": "all":
    • to have tabs and spaces marked with special characters;
    • this setting is especially important, as it seems, that translate_tabs_to_spaces not always works
    • I still see a lot of tabs in opened files (maybe I don’t understand how ST3 treats that flag?),
  • "save_on_focus_lost": true — read more about it in the next chapter
  • "auto_find_in_selection": true:
    • this is so obvious setting for me that I was surprised, that it is not default in Sublime Text 3
    • it causes search / replace to be automatically performed in selected text only
  • "preview_on_click": false:
    • disabled this, because that ST3 feature was something beyond me;
    • I don’t much like the idea that I get new tab opened each time I click on any filename is sidebar,
  • "rulers": [80] — to have standard, 80-character margin line in every pane.

I excluded all font and theme related flags from above list, as I find them very personal and understand, you’ll want to set them your way.

Automatically saving changes on focus lost

A bit more explanation on save_on_focus_lost flag. This is one of these things, which you miss really much, but you don’t realize that fact, until you are able to taste the difference. I’ve been using Netbeans so long, that I managed to learn myself a tick of pressing Ctrl+S before pressing Alt+Tab to switch to another program (mostly: browser, to test newest changes). When I first time used phpStorm and learnt of this feature, I finally understood, that I was blind for so long.

Auto-save on focus lost works slightly different in Sublime Text 3 than in phpStorm. In phpStorm it was triggered only on entire window focus lost (only when actually switching to another application) and in that case, it was saving all unsaved files (on all tabs). In ST3 it is triggered on focus lost of every tab — so changes to your file are automatically saved even if you just browse through tabs and don’t leave the program.

Keep in mind, that when save_on_focus_lost flag is set to true, it will not trigger auto-save upon closing entire ST3. When you restart it, all previously open files will be open back again, but changes to your unsaved files will be kept in internal cache and restored from there. So, you’ll see them in unsaved state and you will not see latest changes in browser. This was a little bit odd for me, but that’s how things are working in ST3.

During its start Sublime Text 3 opens your files only that were previously opened. If you open up any configuration file, close ST3 and reopen it, you won’t see that configuration file reopened.

I don’t know, if this is a bug or a feature.

UTF-8 only, please…

I’m one of those, who think, that using anything else than UTF-8 is wrong. So, in addition to above list, I also set three more flags:

  • "fallback_encoding": "UTF-8"
  • "show_encoding": true and
  • "show_line_endings": true

This (along with some other, default settings, that I did not changed) ensures, that every file will be opened in UTF-8. In addition, I have very quick access (bottom-right corner) to verification and possible change of file encoding and line endings.

Ignored files

One last thing. There’s file_exclude_patterns flag, which controls, which file extensions are ignored. If you modify this flag, make sure that you extend it, not overwrite it (first copy all its values from default configuration and only then, and your own at the end). This is essential, because values for this flag, from user settings file are not merged with default flag values only overrides them.

I find default definition of file_exclude_patterns quite vast and OK. So, the only reason, for which I decided to extend it, was installation of CTags plugins. Read more about this here: CTags and Goto source definition functionality in Sublime Text 3

Disabling auto-completion inside brackets

Sublime Text 3 uses many sources of data for auto-completion feature. And, by default, auto-completion dialog is also fired inside brackets, which can be quite annoying for many. As MattDMo points out, to disable this, you need to is to change auto_complete_selector value:

"auto_complete_selector": "source - comment - string, meta.tag - punctuation.definition.tag.begin"

Read more here.

Other important (at least for me) flags

At some point I have highlight_modified_tabs enabled (set to true), but I turned it back to default value (disabled), because I found out, that this is ignored by some themes, mine including.

Most IDEs (especially for PHP development) marks entire words, including $ symbol, when such word is double clicked with mouse. By default, Sublime Text 3 is not doing this. It considers $ as one of many word separators and selects only text.

This might by annoying for people who are used to entire variable selection upon double click. Fixing this is a finger snap (as everything) in Sublime Text 3. All is needed, is a word_separators flag modification, so it doesn’t include $ character any more. In other words, put this:

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

to your user configuration file, save it and… you’re done.

Keep your eye on trim_trailing_white_space_on_save flag and use it carefully:

  • This is one of the fabulous features of phpStorm that I missed so much in Netbeans.
  • It removes whitespace on the end of each line.
  • But, beware. If your line is empty, but only contains some white spaces i.e.:
    • spaces or tabs equal to surrounding lines,
    • as many editors does, when intending entire blocks of code,
  • then in such line Sublime Text 3 also remove white spaces, when this flag is enabled.
  • And it will do this automatically on each save
  • So you may quickly find, that half or more of your files reports to be modified when first time opened and saved in ST3.

In other words, I had this option enabled, but soon disabled it (reverted back to default settings of false).

Final words

To summarize entire article, I place here my entire user configuration file:

{
    "auto_find_in_selection": true,
    "color_scheme": "Packages/User/Tubnil Bright (SL).tmTheme",
    "draw_white_space": "all",
    "fallback_encoding": "UTF-8",
    "file_exclude_patterns":
    [
        ".pyc",
        ".pyo",
        ".exe",
        ".dll",
        ".obj",
        ".o",
        ".a",
        ".lib",
        ".so",
        ".dylib",
        ".ncb",
        ".sdf",
        ".suo",
        ".pdb",
        ".idb",
        ".DS_Store",
        ".class",
        ".psd",
        ".db",
        ".sublime-workspace",
        ".tags",
        ".tags_sorted_by_file"
    ],
    "font_face": "Courier",
    "font_size": 15,
    "highlight_line": true,
    "highlight_modified_tabs": true,
    "ignored_packages":
    [
        "Vintage"
    ],
    "match_brackets_content": false,
    "preview_on_click": false,
    "rulers": [80],
    "save_on_focus_lost": true,
    "scroll_past_end": false,
    "shift_tab_unindent": true,
    "show_encoding": true,
    "show_line_endings": true,
    "theme": "Ayin.sublime-theme",
    "translate_tabs_to_spaces": true,
    "word_separators": "./()"'-:,.;<>~!@#%^&|+=[]{}`~?"
}

If you wish to use then open Preferences > Settings — User and paste, whatever you wish.

Leave a Reply