How Sublime Text’s Preferences Work
Sublime Text uses a powerful text-based settings system that can be a little intimidating when you encounter it for the first time. This article gives an overview of the system and points out some common mistakes to avoid.
Sublime Text allows you to customize its behavior in detail with various settings. These settings are changed by modifying text files that follow a JSON syntax.
Some settings can be changed through clickable options in the Sublime Text menu bar but many interesting ones are only available in the text-based settings files.
This system can seem a little overwhelming and tricky at first but it has two great advantages:
- It makes it easy to share settings and configuration tips with others.
- It makes it easy to back up your own settings so that you can restore them quickly or move them to another system. (I like to use a Git repository for that.)
Where Settings Files Are Stored
You can access the most commonly used settings files through the Preferences ▸ Settings menu item. This opens up a new editor window that’s split into two panes. The left-hand pane contains the default settings. The right-hand pane is where you can apply custom overrides for the settings on the left.
Sublime Text stores its settings as JSON-formatted text files with a .sublime-settings extension on disk. Depending on your operating system you’ll find the settings files in one of the following folders:
- macOS:
~/Library/Application Support/Sublime Text 3/Packages/User - Windows:
%APPDATA%\Sublime Text 3/Packages/User - Linux:
~/.config/sublime-text-3/Packages/User
Default, User Specific, and Syntax Specific Preferences
Sublime Text processes several settings files in sequence to determine which value applies for a specific configuration option.
The specific order of files is listed in the Sublime Text documentation, but from a high-level perspective it looks like this:
This process always starts with the default preferences which determine the default values for all configuration options. Then user specific and syntax specific settings are layered on top. This means they can override values in the default preferences. Syntax specific settings take precedence over user specific settings.
This gives you the power and flexibility, for example, to use a different font for .txt files and .py files. Another example would be setting different tab widths for Python code files and HTML files.
The default preferences can help you discover which settings are available for you to modify.
It’s a good idea to browse through Sublime’s default preferences or the defaults for a specific plugin in order to learn what settings you may want to change or optimize. Some of these settings are undocumented and not discussed in the official Sublime Text docs—you might even stumble on some “hidden gems”.
Things to Watch Out For
Here are a couple of key points that will help you working with Sublime Text’s preferences:
-
Never modify the default preferences. The default settings for SublimeText itself or any of its plugins are built-in and are not represented by actual files on disk. Any change you make to the defaults will be reverted when you restart Sublime Text. Always add your personal settings to Sublime’s user settings instead.
-
Sublime Text stores it settings as JSON text files. This great because it is a common and standardized format. On the other hand it doesn’t support comments and it’s easy to introduce syntax errors. A common pitfall is getting commas wrong. Remember that the last value in a JSON object must not have a comma after it, but all other values need to end with a comma. In its latest versions Sublime became a little more flexible with its JSON parsing when it comes to handling commas. But in general you want to make sure your preferences are not malformed.
-
User, syntax, and plugin specific settings are empty by default. On a fresh Sublime Text install your user, syntax, and plugin specific settings will be empty. This means that the default values apply for all settings. You can then build from there and selectively override the defaults. For example, when a tutorial asks you to modify a setting that doesn’t exist yet in your own user, syntax, or plugin specific settings you simply need to add that new setting to the appropriate file.
How to Migrate Your Sublime Text Settings to Another Machine
To transfer your customized version of Sublime Text from one machine to another do the following:
-
Install the same set of plugins on all machines via Package Control. Note that copying over the plugins manually won’t work due to platform differences. They must be reinstalled through Package Control.
-
Copy over the
.sublime-settings(JSON) files and place them in the platform-specific settings folders listed earlier in this article.
Additional Resources
You can learn more about Sublime Text’s configuration system in the official Sublime Text 3 documentation.
