Settings – Reference — Sublime Text Unofficial Documentation (original) (raw)

Global Settings¶

Global settings can only be modified in Preferences.sublime-settings and Preferences (<platform>).sublime-settings(where <platform> can be any of Linux, OSX or Windows) and, where indicated, also in .sublime-project files.

theme

Type	str
Default	"Default.sublime-theme"

Theme to be used. Accepts a base name for a .sublime-theme file.

scroll_speed

Type	float
Default	1.0

Controls the smooth scrolling feature.

• A value of 0 disables smooth scrolling.
• A value between 0 and 1 makes scrolling slower.
• A value of 1 is the default scrolling speed.
• A value larger than 1 makes scrolling faster.

hot_exit

Type	bool
Default	true

If trueand you exit the application or active window, Sublime Text will close the application or window without prompting, even if there are unsaved files. Unsaved files and the state of the active project will be restored the next time Sublime Text starts.

remember_open_files

Type	bool
Default	false

If true, every time you start Sublime Text it will reopen the files that were open when the application was closed the last time.

open_files_in_new_window

Type	bool
Default	true

**OS X only.**If true, a new window is created when files are opened from Finder or by dragging them onto the dock icon.

close_windows_when_empty

Type	bool
Default (All)	false
Default (OS X)	true

If trueand no folder is open in the active window, the window will be closed when the last file is closed.

show_full_path

Type	bool
Default (All)	true
Default (OS X)	false

If true, show the active file’s full path in the title bar.

preview_on_click

Type	bool
Default	true

If true, preview file contents when clicking on a file in the side bar. Files in preview will be closed automatically as soon as they lose focus (for example, if you press Esc). Double-clicking or editing a file in preview will open the file in a tab.

folder_exclude_patterns

Type	[str,]
Default	[".svn", ".git", ".hg", "CVS"]

Accepts wildcards. Excludes the matching folders in the project from the side bar, Goto Anything and any project-wide action.

This setting must be used in a global Preferences.sublime-settings file, or in folder items in a .sublime-project file.

file_exclude_patterns

Type	[str,]
Default	["*.pyc", "*.pyo", "*.exe", "*.dll", "*.obj", "*.o", "*.a", "*.lib", "*.so", "*.dylib", "*.ncb", "*.sdf", "*.suo", "*.pdb", "*.idb", ".DS_Store", "*.class", "*.psd", "*.db", "*.sublime-workspace"]

Accepts wildcards. Excludes the matching files in the project from the side bar, Goto Anything and any project-wide action.

This setting must be used in a global Preferences.sublime-settings file, or in folder items in a .sublime-project file.

binary_file_patterns

Type	[str,]
Default	["*.jpg", "*.jpeg", "*.png", "*.gif", "*.ttf", "*.tga", "*.dds", "*.ico", "*.eot", "*.pdf", "*.swf", "*.jar", "*.zip"]

Accepts wildcards. Excludes the matching files in the project from Goto Anything and any project-wide action, but not the side bar.

This setting must be used in a global Preferences.sublime-settings file, or in folder items in a .sublime-project file.

show_tab_close_buttons

Type	bool
Default	true

If false, hides close buttons in the tab bar until you hover the mouse over the tab bar.

mouse_wheel_switches_tabs

Type	bool
Default	false

If trueand the cursor is in the tab bar, scrolling the mouse wheel will switch tabs.

ignored_packages

Type	[str,]
Default	["Vintage"]

A list of packages that Sublime Text will ignore. Packages in this list will be disabled until you remove them from the list.

Some packages may not respond gracefully to being disabled/enabled via this setting. Therefore, after editing this setting, you should restart Sublime Text.

File Settings¶

Whitespace and Indentation¶

auto_indent

Type	bool
Default	true

Toggles automatic indentation. Automatic indentation will try to calculate the correct indentation when you press :kbd:´Enter´.

smart_indent

Type	bool
Default	true
Depends on	auto_indent

Toggles smart indentation. Smart indentation tries additional heuristics to calculate the correct indentation. when you press :kbd:´Enter´.

indent_to_bracket

Type	bool
Default	false
Depends on	auto_indent

If true, adds whitespace up to the first open bracket when indenting.

tab_size

Type	int
Default	4

Size of a tab in spaces.

translate_tabs_to_spaces

Type	bool
Default	false

Determines whether to replace a tab character with tab_size number of spaces when Tab is pressed.

use_tab_stops

Type	bool
Default	true

If translate_tabs_to_spaces is true, this setting will make Tab and Backspaceinsert/delete tab_size number of spaces per key press.

trim_automatic_white_space

Type	bool
Default	true

Toggles deletion of whitespace added by auto_indent.

detect_indentation

Type	bool
Default	true

If false, disables detection of tabs vs. spaces whenever a buffer is loaded. If true, it will automatically modifytranslate_tabs_to_spaces and tab_size.

draw_white_space

Type	enum : str
Default	"selection"

Valid values: none, selection, all.

trim_trailing_white_space_on_save

Type	bool
Default	false

If true, Sublime Text will remove whitespace from the active file before saving.

tab_completion

Type	bool
Default	true

If true, pressing Tabwill insert the best matching completion.

If false,Tab will only trigger snippets or insert a tab.

Tab can still be used to insert an explicit tab when tab_completion is true.

auto_complete

Type	bool
Default	true

If true, completions will be shown automatically while typing.

auto_complete_size_limit

Type	int
Default	4194304

In files whose size is larger than this value, auto complete will stop being automatically triggered.

auto_complete_delay

Type	int
Default	50

Delay in milliseconds before the auto complete window is shown after typing.

auto_complete_selector

Type	str
Default	"meta.tag - punctuation.definition.tag.begin, source - comment - string.quoted.double.block - string.quoted.single.block - string.unquoted.heredoc"

Selector denoting scopes where auto complete will be active.

auto_complete_triggers

Type	[{ (enum : str) : str }, ]
Default	[{"characters": "<", "selector": "text.html"}]

Additional situations to trigger auto complete.

auto_complete_commit_on_tab

Type	bool
Default	false

By default, auto complete will commit the current completion on Enter.

If true, this setting will allow you to complete on Tab instead.

Completing on Tabis generally a superior option, as it removes the ambiguity between committing the completion and inserting a newline.

auto_complete_with_fields

Type	bool
Default	false
Depends on	auto_complete_commit_on_tab

If true, auto complete will be also shown when snippet fields are active.

auto_complete_cycle

Type	bool
Default	false

If true, pressing Upon the first item in the auto complete window will select the last item.

If false, the auto complete window will be closed in the same situation.

Likewise for the Down key when the last item is selected.

auto_close_tags

Type	bool
Default	true

If true, entering </will automatically close HTML and XML tags.

shift_tab_unindent

Type	bool
Default	false

By default,Shift+Tab will only unindent if the selection spans multiple lines. When pressing Shift+Tab at other times, it will insert a tab character. This way, tabs can be inserted when tab_completion is enabled.

If true,Shift+Tab will always unindent instead of inserting tabs.

copy_with_empty_selection

Type	bool
Default	true

If true, the copy and cut commands will operate on the current line when the selection is empty instead of doing nothing.

find_selected_text

Type	bool
Default (All)	true
Default (OS X)	false

If true, the selected text will be copied into the find panel when it’s shown.

auto_find_in_selection

Type	bool
Default	false

If true, the Find in Selection flag will be enabled automatically when multiple lines are selected.

drag_text

Type	bool
Default	true

If true, clicking on selected text will begin a drag-drop operation.

Not currently implemented under Linux.

Visual Settings¶

always_show_minimap_viewport

Type	bool
Default	false

If true, shows a rectangle on the minimap highlighting the file’s visible area. If false, only shows the rectangle when you hover the cursor over the minimap.

color_scheme

Type	str
Default	"Packages/Color Scheme - Default/Monokai.tmTheme"

Sets the colors used for text highlighting. Accepts a path relative to the Data directory (for example: Packages/Color Scheme - Default/Monokai Bright.tmTheme).

font_face

Type	str
Default (Linux)	"Monospace"
Default (OS X)	"Menlo-Regular"
Default (Windows)	"Consolas"

Font face to be used for editable text.

font_size

Type	int
Default (All)	10
Default (OS X)	12

Size of the font for editable text.

font_options

Type	enum : str
Default	[]

Valid values: bold, italic, no_antialias, gray_antialias,subpixel_antialias, directwrite (Windows).

gutter

Type	bool
Default	true

Toggles display of gutter.

line_numbers

Type	bool
Default	true

If true, displays line numbers in the gutter.

margin

Type	int
Default	4

Spacing between the gutter and the text.

fold_buttons

Type	bool
Default	true

If true, you will see triangles next to lines that can be folded.

fade_fold_buttons

Type	bool
Default	true

If true, the fold buttons will be hidden until you hover the mouse over the gutter.

rulers

Type	float | [float,]
Default	[]

Columns at which to display vertical lines. Rulers help to visually indicate the length of a line. Accepts a list of numeric values (such as [79, 89, 99]) or a single numeric value (for example, 79).

draw_minimap_border

Type	bool
Default	false

If true, draws a border around the minimap’s region corresponding to the the view’s currently visible text. The minimapBorder key of the active color scheme controls the border’s color.

highlight_line

Type	bool
Default	false

If true, highlights lines where a caret is present.

line_padding_top

Type	int
Default	0

Additional spacing at the top of each line, in pixels.

line_padding_bottom

Type	int
Default	0

Additional spacing at the bottom of each line, in pixels.

caret_style

Type	enum : str
Default	"smooth"

Determines the style of the caret (text insertion point).

Valid values: smooth, phase, blink, solid.

caret_extra_top

Type	int
Default	0

Increases the size of the caret.

caret_extra_bottom

Type	int
Default	0

Increases the size of the caret.

caret_extra_width

Type	int
Default	0

Increases the width of the caret.

scroll_past_end

Type	bool
Default (All)	true
Default (OS X)	false

If true, Sublime Text will leave a wide, empty margin between the last line and the bottom of the window.

word_wrap

Type	bool | auto
Default	"auto"

If true, disables horizontal scrolling. If set to auto, will be disabled for source code and enabled otherwise.

wrap_width

Type	int
Default	0
Depends on	word_wrap

If greater than 0, wraps long lines at the specified column as opposed to the window width.

indent_subsequent_lines

Type	bool
Default	true
Depends on	word_wrap

If false, wrapped lines will not be indented. Only has effect if word_wrap is set to true.

draw_centered

Type	bool
Default	false

If true, text will be drawn centered rather than left-aligned.

match_brackets

Type	bool
Default	true

If false, disables bracket highlighting for brackets enclosing the caret.

match_brackets_content

Type	bool
Default	true

If true, the nearest bracket pair surrounding the caret will be highlighted. Otherwise, the caret has to be next to a bracket for highlighting to occur.

match_brackets_square

Type	bool
Default	true
Depends on	match_brackets

If false, stops highlighting square brackets. Only has effect if match_brackets is true.

match_brackets_braces

Type	bool
Default	true
Depends on	match_brackets

If false, stops highlighting curly brackets. Only has effect if match_brackets is true.

match_brackets_angle

Type	bool
Default	false
Depends on	match_brackets

If false, stops highlighting angle brackets. Only has effect if match_brackets is true.

match_tags

Type	bool
Default	true

If true, enables visualization of the matching tag in HTML and XML content.

match_selection

Type	bool
Default	true

If true, highlights other occurrences of the selected text.

draw_indent_guides

Type	bool
Default	true

If true, draws lines at every indentation level.

The color of the indentation guides is controlled via the .tmTheme settings:guide, activeGuide and stackGuide.

indent_guide_options

Type	enum : str
Default	["draw_normal"]
Depends on	draw_indent_guides

Valid options: draw_normal, draw_active.

The draw_active option will cause the indent guide containing the caret to be shown in a different color.

show_definitions

Type	bool
Depends on	index_files

If true, hovering over a word will show a popup listing all possible locations for the symbol.

tree_animation_enabled

Type	bool
Default	true

If true, animations will be shown in the sidebar when expanding or collapsing folders.

animation_enabled

Type	bool
Default	true

If true, animations will be shown throughout the application.

hightlight_modified_tabs

Type	bool

If true, makes tabs with unsaved changes more visible.

bold_folder_labels

Type	bool
Default	false

If true, folder names in the side bar will be bold.

use_simple_full_screen

Type	bool
Default	false

OS X only.

If true, disables Lion-style full-screen support.

Sublime Text must be restarted after changing this setting for it to take effect.

gpu_window_buffer

Type	enum : (bool | str)
Default	"auto"

OS X only.

Valid values: true, false, auto.

If auto, it will enable the setting when running on a screen 2560 pixels or wider (for example, a Retina display).

If true, OpenGL is used to accelerate drawing.

Sublime Text must be restarted after changing this setting for it take effect.

overlay_scroll_bars

Type	enum : str
Default	"system"

Valid values: system, enabled, disabled.

enable_tab_scrolling

Type	bool
Default	true

If true, tabs will scroll left and right instead of simply shrinking when there are too many to show on the tab bar.

show_encoding

Type	bool
Default	false

If true, shows the active file’s encoding in the status bar.

show_line_endings

Type	bool
Default	false

If true, shows the active file’s type of line endings in the status bar.

remember_full_screen

Type	bool
Default	false

If true, allows Sublime Text to start in full-screen mode if it was exited in full-screen mode.

If false, Sublime Text will never start in full-screen mode.

always_prompt_for_file_reload

Type	bool
Default	false

If true, always prompt before reloading a file.

By default, prompting will only occur if a file has unsaved changes.

create_window_at_startup

Type	bool
Default	true

OS X only.

If true, an empty window will be created at startup.

show_panel_on_build

Type	bool
Default	true

If true, shows the Build Results panel when building.

If false, the Build Results panel can be shown via theTools --> Build Results menu item.

index_files

Type	bool
Default	true

If true, file indexing parses all files in the side bar and builds an index of their symbols.

Required for Goto Definition to work.

Symbols are only available for syntaxes that define them via .tmPreferences files.

index_workers

Type	int
Default	0
Depends on	index_files

Sets the number of threads used for indexing.

If 0, Sublime Text will use all available cores.

To disable indexing completely, use index_files.

index_exclude_patterns

Type	[str,]
Default	["*.log"]
Depends on	index_files

Indicates which files will not be indexed.

Patterns in this list accept wildcards.

Automatic Behavior¶

auto_match_enabled

Type	bool
Default	true

Toggles automatic pairing of quotes, brackets, etc.

save_on_focus_lost

Type	bool
Default	false

If true, saves files automatically when switching to a different file or application.

find_selected_text

Type	bool
Default (All)	true
Default (OS X)	false

If true, the selected text will be copied into the find panel when the panel is opened.

word_separators

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

Characters considered to divide words for actions like advancing the cursor, etc. Not used for every context where a notion of a word separator is useful (for example, word wrapping). In some contexts, the text might be tokenized based on other criteria (for example, the syntax definition rules).

ensure_newline_at_eof_on_save

Type	bool
Default	false

If true, adds a new line at the end of the active file before saving if no new line is present.

System and Miscellaneous Settings¶

is_widget

Type	bool
Default	null

Is set to true by Sublime Text if the buffer is an input field in a dialog, as opposed to a regular buffer.

spell_check

Type	bool
Default	false

Toggles the spell checker.

dictionary

Type	bool
Default	"Packages/Language - English/en_US.dic"

Word list to be used by the spell checker. Accepts a path relative to the Data directory (such as Packages/Language - English/en_US.dic). You can add more dictionaries.

spelling_selector

Type	str
Default	"markup.raw, source string.quoted - punctuation - meta.preprocessor.c.include, source comment - source comment.block.preprocessor, -(source, constant, keyword, storage, support, variable, markup.underline.link, meta.tag)"
Depends on	spell_check

Scope selector to determine which scopes will be spell checked.

fallback_encoding

Type	bool
Default	"Western (Windows 1252)"

The encoding to use when the encoding can’t be determined automatically. ASCII, UTF-8 and UTF-16 encodings will be detected automatically .

default_encoding

Type	str
Default	"UTF-8"

Encoding used when saving new files, and files opened with an undefined encoding (for example, plain ascii files).

If a file is opened with a specific encoding (either detected or given explicitly), this setting will be ignored and the file’s encoding will be used to save the file.

enable_hexadecimal_encoding

Type	bool
Default	true

If true, files containing null bytes will be opened as hexadecimal by default.

default_line_ending

Type	bool
Default	"system"

Determines what characters to use to designate new lines. Valid values:system (OS-dependant), windows (CRLF) and unix (LF).

tab_completion

Type	bool
Default	true

Determines whether pressing Tabwill insert completions.

Build and Error Navigation Settings¶

result_file_regex

Type	str
Default	null

Regular expression used to extract file names from build system output printed to a view or output panel. Follows the rules for error capturing in build systems.

result_line_regex

Type	str
Default	null

Regular expression used to extract line information from build system output printed to a view or output panel. Follows the rules for error capturing in build systems.

result_base_dir

Type	str
Default	null

Folder to start looking for offending files based on information extracted with result_file_regex and result_line_regex.

build_env

Type	bool | {str : str}
Default	false

List of paths to add to build systems by default.

File and Directory Settings¶

default_dir

Type	str
Default	null

Sets the default save folder for the view. If the value of this setting points to an existing folder, you will be prompted to save the file to that folder when you try to save the file.

atomic_save

Type	bool
Default	false

If true, Sublime Text will save by writing to an alternate file and then renaming it over the original file.

Atomic save attempts to reduce data loss by only removing the orginal file when the new file has been successfully written. Because the a file is first created and then renamed instead of being updated in place, many file listeners and virtual file systems will get confused. For this reason, it’s disabled by default.

Input Settings¶

command_mode

Type	bool
Default	false

If true, the buffer will ignore key strokes. Useful when emulating Vim’s modal behavior.

move_to_limit_on_up_down

Type	bool
Default (All)	false
Default (OS X)	true

If trueand the caret is on the first line, pressing the up arrow will move the caret to the beginning of the line. If the caret is on the last line, the down arrow will move the caret to the end of the last line.