3. Settings
Creating custom Settings (Preferences) is one of the ways you can customize Sublime Text’s behavior.
The global default Settings are accessed (read-only) by:
(left side since Sublime Text 4)
This opens a window with a pair of .sublime-settings files shown side by side.
The right side of the window that appears is your own settings file that overrides the settings on the left-hand side. Note that the entire file is one large JSON object (dictionary when translated to a Python object). JSON objects contain key/value pairs. Each “key” is a setting name, and each “value” is the setting value.
You customize settings by copying key/value pairs from the left side to your
own .sublime-settings file on the right side, and changing its value by
editing and saving the file on the right side (your settings override file). The
documentation for each setting is conveniently right there in the left-side file
with each setting.
Note
If you have the PackageDev Package installed, this copy/pasting can be done
by a single mouse click on the setting’s pencil icon, among many other things.
Settings are stored in JSONC format (JSON with comments), which means you can
include end-of-line comments after // to document why you did certain things so
you can remember the reasons later, as well as leave commas after the last item in a
list.
Obviously it helps to be familiar with JSON data format. If you need to brush up on it, or need to learn it from scratch, here are a couple of good references:
Introducing JSON (authoritative reference for JSON beginners)
JSON on Wikipedia (article including JSON history)
The major sections of the default settings file are:
Editor settings (the top 2/3 of the file),
UI settings,
Application settings.
The last 2 “sections” of the settings file are headed by a “header comment” with the latter 2 titles.
Syntax-Specific Settings:
This is a subset of the main settings that override global defaults when editing a file that uses that Syntax.
Package Settings:
Package settings, which apply to specific Package behavior, and are are accessed by:
These settings are applied in layers like CSS, where lower (more specific) preferences override higher-level preferences of the same name.
The “path” of the “layer cascade” is guided by the Syntax of the current View as follows:
Layer |
Access |
Notes |
|---|---|---|
global defaults |
(left side) |
shipped: Packages/Default/Preferences.sublime-settings |
platform defaults |
> Default/Preferences (<platform>) |
override folder: Packages/Default/Preferences (Windows).sublime-settings |
user overrides |
(right side) |
Packages/User/Preferences.sublime-settings |
project overrides |
> “settings”: { ... } entry |
Pjt File; editor preferences only, not UI or APP preferences. |
syntax defaults |
(left) |
shipped: Packages/<syntax>/<syntax>.sublime-settings |
syntax file overrides |
(left if present) |
override folder: Packages/<syntax>/<syntax>.sublime-settings |
syntax overrides |
(right) |
Packages/User/C.sublime-settings |
buffer-specific |
Programmatic/by command (see below) |
no file involved |
In a Plugin, you can get settings from a View or Window. The
object returned is like a dictionary, and you can read and write live settings using
it using its get() and set() methods respectively. Changes to settings made
are in the buffer-specific category shown in table, and are only temporary
until that View or Window is closed. You can also create a dictionary from it by:
my_settings_dict = settings.to_dict()
but be advised: the dictionary acquired is only a copy and changes to it have no impact on the actual settings.
Additionally, there are 2 Commands you can use anywhere Commands can be used:
Command |
Args |
Example |
|---|---|---|
toggle_setting |
{“setting”: “<setting_name>”} |
{“setting”: “word_wrap”} |
set_setting |
{“setting”: “<setting_name>”, “value”: Value} |
{
“setting”: “color_scheme”,
“value”: “Packages/Color Scheme - Default/Cobalt.tmTheme”
}
|