Sublime Text Unofficial Documentation

Release 2.0

guillermooo

January 11, 2013

CONTENTS

ii

CHAPTER

ONE

ABOUT THIS DOCUMENTATION

This is the unofficial documentation for the Sublime Text editor, maintained by volunteers. We hope its useful!
The sublime what? What are you talking about!?
Sublime Text is a text editor for code and prose. It does away with many repetitive tasks so you can focus on your
work. And its fun to use!
Before you continue, we encourage you to read through the Basic Concepts section.
Happy learning!

Sublime Text Unofficial Documentation, Release 2.0

Chapter 1. About This Documentation

CHAPTER

TWO

INSTALLATION
The process of installing Sublime Text is different for each platform.
Make sure to read the conditions for use on the official site. Sublime Text is not free.

2.1 32 bits or 64 bits?

Choose the 64-bit version if youre running a 64-bit operating system, otherwise the 32-bit version.
On Windows, if in doubt, choose the 32-bit version. Modern 64-bit versions of Windows can run 32-bit software.
On Linux run this command in your terminal to check your operating systems type:
uname -m

For OS X, you can ignore this section: there is only one version of Sublime Text for OS X.

2.2 Windows
2.2.1 Portable or Not Portable?
Sublime Text comes in two flavors for Windows: normal, and portable. If you need the portable installation, you
probably know already. Otherwise, go with the normal one.
Normal installations separate data between two folders: the installation folder proper, and the data directory. These
concepts are explained later in this guide. Normal installations also integrate Sublime Text with the Windows context
menu.
Portable installations will keep all files Sublime Text needs to run in one single folder. You can then move this folder
around and the editor will still work.

2.2.2 How to Install the Normal Version of Sublime Text

Download the installer, doubleclick on it and follow the onscreen instructions.

2.2.3 How to Install the Portable Version of Sublime Text

Download the package and uncompress it to a folder of your choice. You will find the sublime_text.exe executable
inside that folder.

Sublime Text Unofficial Documentation, Release 2.0

2.3 OS X
Download and open the .dmg file, and then drag the Sublime Text 2 bundle into the Applications folder.

2.4 Linux
You can download the package and uncompress it manually. Alternatively, you can use the command line:
cd /path/to/your/apps
wget http://url/to/sublime.tar.bz2
tar vxjf sublime.tar.bz2

If you want, you can also create a symbolic link to the executable for convenience:
sudo ln -s /path/to/sublime_text /usr/bin/subl

2.5 Living Dangerously... or Not

Sublime Text has three release channels:
Stable (default)
Dev
Nightly
If you are working on a NASA project or are on a tight deadline, keep using the stable releases and stop reading here.
Stable releases are better tested and more reliable for everyday use than the others. They come out roughly once a
month. The majority of users will want to use stable releases only.
The dev and nightly channels are unstable, which means that builds published through them are likely to contain bugs
and to not work reliably. They are updated more often than stable releases.
Dev builds are available for everyone. On average, theyre released twice a month. While not quite ready for everyday
use yet, they showcase new features in a mostly unbroken fashion.
Lastly, nightly builds are the bleeding edge, with frequent updates and also frequent problems of various degrees of
severity. They are fun to try out, but do so at your own risk. Nighlty builds are only available for registered users.

Chapter 2. Installation

CHAPTER

THREE

BASIC CONCEPTS
Here well explain concepts that the reader needs to be familiar with in order to fully understand the contents of this
guide.

3.1 Conventions in This Guide

This guide is written from the perspective of a Windows user, but most instructions should only require trivial changes
to work on other platforms.
Relative paths (e. g. Packages/User) start at the data directory unless otherwise noted. The data directory is explained
further below.
We assume default key bindings when indicating keyboard shortcuts. Due to the way Sublime Text maps keys to
commands, some key bindings wont match your locales keyboard layout.

3.2 With Great Power Comes Lots of Questions

Sublime Text is a very extensible and customizable editor. It does many things out of the box, but if you spend some
time tailoring it to your exact needs, it will give you superpowers. This guide will teach you all you need to know to
configure Sublime Text.
In the following paragraphs, well outline some aspects that wont click in your mind until youve spent some time
using Sublime Text. Keep exploring the editor and looking around in this guide, and everything will fall into place at
some point.
Sublime Text is undeniably a versatile tool for programmers, but you dont need to be one to use it, or even to configure
it to make it the perfect tool for your writing. If youre a hacker, however, you are about to spend the remainder of
your day playing around with this editor.

3.3 The Data Directory

Sublime Text 2 stores nearly all of the interesting files for users under the data directory. This is a platform-dependent
location:
Windows: %APPDATA%\Sublime Text 2
OS X: ~/Library/Application Support/Sublime Text 2
Linux: ~/.config/sublime-text-2

Sublime Text Unofficial Documentation, Release 2.0

For portable installations, look inside Sublime Text 2/Data. Here, the Sublime Text 2 part refers to the directory to
which youve extracted the contens of the compressed file containing Sublime Text 2.
Note that only for portable installations does a directory named Data exist. For the other types of installation, the data
directory is the location indicated above.

3.4 The Packages Directory

This is a key directory: all resources for supported programming and markup languages are stored here. A package
is a directory containing related files having a special meaning to Sublime Text.
You can access the packages directory from the Sublime Text 2 menu (Preferences | Browse Packages...), or by
means of an api call: sublime.packages_path(). In this guide, we refer to this location as Packages, packages
path, packages folder or packages directory.

3.4.1 The User Package

Packages/User is a catch-all directory for custom plugins, snippets, macros, etc. Consider it your personal area in the
packages folder. Sublime Text 2 will never overwrite the contents of Packages/User during upgrades.

3.5 The Python Console and the Python API

This information is especially interesting for programmers. For the rest of Sublime Text 2 users, you just need to know
that Sublime Text enables users with programming skills to add their own features to the editor. (So go learn how to
program; its great fun!)
Sublime Text 2 comes with an embedded Python interpreter. Its an useful tool to inspect Sublime Text 2 settings and
to quickly test API calls while youre writing plugins.
To open the Python console, press Ctrl+ or select View | Show Console in the menu.
Confused? Lets try again more slowly:
Python is a programming language known to be easy for beginners and very powerful at the same time. API is
short for Application Programming Interface, which is a fancy way of saying that Sublime Text 2 is prepared to be
programmed by the user. Put differently, Subime Text gives the user access to its internals through Python. Lastly, a
console is a little window inside Sublime Text which lets you type in short snippets of Python code and run them. The
console also shows text output by Sublime Text or its plugins.

3.5.1 Your Systems Python vs the Sublime Text 2 Embedded Python

On Windows and Linux, Sublime Text 2 comes with its own Python interpreter and its separate from your systems
Python installation.
On OS X, the system Python is used instead. Modifying your system version of Python, such as replacing it with the
MacPorts version, can cause problems for Sublime Text.
The embedded interpreter is intended only to interact with the plugin API, not for general development.

Chapter 3. Basic Concepts

Sublime Text Unofficial Documentation, Release 2.0

3.6 Packages, Plugins, Resources and Other Things That May Not
Make Sense to You Now
For now, just keep in mind that almost everything in Sublime Text can be adapted to your needs. This vast flexibility is
the reason why you will learn about so many settings files: there simply must be a place to specify all your preferences.
Configuration files in Sublime Text let you change the editors behavior, add macros, snippets or create new features
where feature means anything you can think of. Ok, maybe not anything, but Sublime Text definitely hands you
over a good deal of control.
These settings files are simply text files following a special structure or format: JSON predominates, but youll find
XML files too.
In this guide, we refer collectively to all these disparate configuration files as resources. Sublime Text will look for
resources inside the packages directory. To keep things tidy, the editor has a notion of a package, which is a directory
containing resources that belong together (maybe they all help write emails faster or code in a certain programming
language).

3.7 Textmate Compatibility

This information is mainly useful for Textmate users who are now using Sublime Text. Textmate was an editor for the
Mac.
Sublime Text 2 is fairly compatible with Textmate bundles with the notable exception of commands. Additionally,
Sublime Text requires all syntax definitions to have the .tmLanguage extension, and all preferences files to have the
.tmPreferences extension. This means that .plist files will be ignored, even if they are located under a Syntaxes or
Preferences subdirectory.

3.8 Vi Emulation
This information is mainly useful for dinosaurs and people who like to drop the term RSI in conversations. Vi is an
ancient modal editor that lets the user perform all operations from the keyboard. Vim, a modern version of vi, is still
in widespread use.
Sublime Text provides vi emulation through the Vintage package. The Vintage package is ignored by default. Read
more about Vintage in the official documentation.

3.9 Emacs
This information is hardly useful for anyone. Emacs is... Well, nobody really knows what emacs is, although some
people edit text with it.
If you are an emacs user, youre probably not reading this.

3.10 Be Sublime, My Friend

Borrowing from Bruce Lees wisdom, Sublime Text can become almost anything you need it to be. In skilled hands,
it can defeat an army of ninjas without your breaking a sweat.
Empty your mind; be sublime, my friend.
3.6. Packages, Plugins, Resources and Other Things That May Not Make Sense to You Now

Sublime Text Unofficial Documentation, Release 2.0

Chapter 3. Basic Concepts

CHAPTER

FOUR

EDITING
4.1 Overview
Sublime Text is full to the brim with editing features. This topic just scratches the surface of whats possible.

4.2 Multiple Selections

Multiple selections let you make sweeping changes to your text efficiently. Any praise about multiple selections is an
understatement. This is why:
Select some text and press Ctrl + D to add more instances. If you want to skip the current instance, press Ctrl
+ K, Ctrl + D.
If you go too far, press Ctrl + U to deselect the current instance.

4.3 Transforming Multiple Selections into Lines

Ctrl + L expands the selections to the end of the line. Ctrl + Shift + L splits the selections into lines.
You can copy multiple selected lines to a separate buffer, edit them there, select the content again as multiple lines and
then paste them back into place in the first buffer.

4.4 Other Ways of Selecting Text

The list is long; all available options can be found under Selection. To name a few:
Select subwords (Alt + Shift + <arrow>)
Expand selection to brackets (Ctrl + Shift + M)
Expand selection to indentation (Ctrl + Shift + J)
Expand selection to scope (Ctrl + Shift + Space)

4.5 Transposing Things

Need to swap two letters or, better yet, two words? Experiment with Ctrl + T.
9

Sublime Text Unofficial Documentation, Release 2.0

4.6 And much, much more...

The Edit, Selection, Find and Goto menus are good places to look for handy editing tools. You might end up using
just a few of them, but the rest will still be there when you need them.

10

Chapter 4. Editing

CHAPTER

FIVE

SEARCH AND REPLACE

Sublime Text features two main types of search:

5.1 Search and Replace - Single File

5.1.1 Searching
To open the search panel for buffers, press Ctrl + F. Some options in the search panel and search actions can be
controlled with the keyboard:
Toggle Regular Expressions
Toggle Case Sensitivity
Toggle Exact Match
Find Next
Find Previous
Find All

Alt +
Alt +
Alt +
Enter
Shift
Alt +

R
C
W
+ Enter
Enter

5.1.2 Incremental Search

The incremental search panel can be brought up with Ctrl + I. The only difference with the regular search panel
lies in the behavior of the Enter key: in incremental searches, it will select the next match in the buffer and dismiss
the search panel for you. Choosing between this panel or the regular search panel is mainly a matter of preference.

5.1.3 Replacing Text

You can open the replace planel with Ctrl + H.
Replace All:

Ctrl + Alt + Enter

5.1.4 Tips
Other Ways of Searching in Buffers
Goto Anything provides the operator # to search in the current buffer. The search term will be the part following the
# operator.

11

Sublime Text Unofficial Documentation, Release 2.0

Other Key Bindings to Search in Buffers

These keybindings work when the search panel is hidden.
Search Forward Using Most Recent Pattern
Search Backwards Using Most Recent Pattern
Select All Matches Using Most Recent Pattern

F3
Shift + F3
Alt + F3

Multiline Search
You can type a multiline search pattern. To enter a newline character, press Ctrl + Enter in the search panel.
Note that the search panel is resizable too.

5.2 Search and Replace - Multiple Files

5.2.1 Searching
To open the search panel for files, press Ctrl + Shift + F. You can use the keyboard to control the search panel
and some search actions:
Toggle Regular Expressions
Toggle Case Sensitivity
Toggle Exact matches
Find Next

Alt + R
Alt + C
Alt + W
Enter

5.2.2 Search Scope

The Where field in the search panel determines where to search. You can define the scope of the search in several
ways:
Adding individual directories (Unix-style paths, even on Windows)
Adding/excluding files based on a pattern
Adding symbolic locations (<open folders>, <open files>)
You can combine these filters separing them with commas, for example:
/C/Users/Joe/Top Secret,-*.html,<open files>
Press the ... button in the search panel to display a menu containing these options.

5.2.3 Results Format

In the search panel, you can find the following options to customize the results format:
Show in Separate Buffer/Output Panel
Show Context

12

Chapter 5. Search and Replace

Sublime Text Unofficial Documentation, Release 2.0

5.2.4 Navigating Results

If the search yields matches, you can move through the sequence using the following key bindings:
Next match
Previous match

F4
Shift + F4

Well examine them in turn, but lets talk about a powerful tool for searching text first: regular expressions.

5.3 Regular Expressions

Regular Expressions find complex patterns in text. To take full advantage of the search and replace facilities in Sublime
Text, you should learn at least the basics of regular expressions. In this guide we will not explain how to use regular
expressions.
Typing out regular expression gets boring fast, and actually saying it is even more annoying, so nerds usually shorten
that to regexp or regex instead.
This is how a regex might look like:
(?:Sw|P)i(?:tch|s{2})\s(?:it\s)?of{2}!

Regexes are known to hurt peoples feelings.

To use regular expressions, you need to activate them first in the various search panels. Othwerwise, the search term
will be interpreted literally.
Sublime Text uses the Boost syntax for regular expressions.

5.3. Regular Expressions

13

Sublime Text Unofficial Documentation, Release 2.0

14

Chapter 5. Search and Replace

CHAPTER

SIX

BUILD SYSTEMS (BATCH

PROCESSING)
Build systems let you run your files through external programs like make, tidy, interpreters, etc.
Executables called from build systems must be in your PATH. For more information about making sure the PATH seen
by Sublime Text is set correctly, see Troubleshooting Build Systems.

6.1 File Format

Build systems are JSON files and have the extension .sublime-build.

6.1.1 Example
Heres an example of a build system:
{
"cmd": ["python", "-u", "$file"],
"file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
"selector": "source.python"
}

cmd Required. This option contains the actual command line to be executed:
python -u /path/to/current/file.ext

file_regex A Perl-style regular expression to capture error information out of the external programs output. This
information is then used to help you navigate through error instances with F4.
selector If the Tools | Build System | Automatic option is set, Sublime Text will automatically find the corresponding build system for the active file by matching selector to the files scope.
In addition to options, you can also use some variables in build systems, like we have done above with $file, which
expands to the the active buffers file name.

6.2 Where to Store Build Systems

Build systems must be located somewhere under the Packages folder (e. g. Packages/User). Many packages include
their own build systems.

15

Sublime Text Unofficial Documentation, Release 2.0

6.3 Running Build Systems

Build systems can be run by pressing F7 or from Tools | Build.
See Also:
Reference for build systems Complete documentation on all available options, variables, etc.

16

Chapter 6. Build Systems (Batch Processing)

CHAPTER

SEVEN

FILE NAVIGATION AND FILE

MANAGEMENT
7.1 Goto Anything
Goto Anything lets you navigate files swiftly. Open it with Ctrl+P. As you type into the input area, names of open
files and files in open directories will be searched, and a preview of the best match will be shown. This preview is
transient, that is, it wont become the actual active buffer until you perform some operation on it. Transient views go
away when you press Esc. You will find transient views in other situations. They are like ghosts or something.
Goto Anything lives up to its name theres more to it than locating files:
To perform a fuzzy search, append # and then keep typing, like this:
island#treasure

This instructs Sublime Text to perform a fuzzy search for treasure in the file whose name matches island. Pressing
Ctrl+; will open Goto Anything and type # for you.
And theres more:
To search symbols in the active buffer, press Ctrl+R. The operator @ can be used as explained above too.
To go to a line number, press Ctrl+G. The operator : can be used as explained above too.
Searching for symbols will only work for file types that have symbols defined for them.

7.2 Sidebar
The sidebar gives you an overview of your project. Files and folders added to the sidebar will be available in Goto
Anything and project-wide actions. Projects and the sidebar are closely related. Theres always an open project,
whether its implicit or explicit.
To open or close the sidebar, press Ctrl+K, Ctrl+B.
The sidebar can be navigated with the arrow keys, but first you need to give it the input focus by pressing Ctrl+0.
To return input focus to the buffer, press Esc. Alternatively, you can use the mouse to the same effect, but why would
you?
The sidebar also provides basic file management operations through the context menu.

17

Sublime Text Unofficial Documentation, Release 2.0

7.3 Projects
Projects group sets of files and directories you need to work on as a unit. Once youve set up your project the way that
suits you by adding folders, save it and give it a name.
To save a project, go to Project | Save Project As....
To quickly switch between projects, press Ctrl+Alt+P.
Project data are stored in JSON files with a .sublime-project extension. Wherever theres a .sublime-project file, you
will find an ancillary .sublime-workspace file too. The second one is used by Sublime Text and you shouldnt edit it
yourself.
Project files can define settings specific to that project only. More on that in the official documentation.
You can open a project from the command line by passing the .sublime- project file as an argument.

18

Chapter 7. File Navigation and File Management

CHAPTER

EIGHT

CUSTOMIZING SUBLIME TEXT

Sublime Text is highly customizable. In the topics below, well explain you how you can adapt it to your needs and
preferences.

8.1 Settings
Sublime Text stores configuration data in .sublime-settings files. Flexibility comes at the price of a slightly complex
system for applying settings. However, heres a rule of thumb:
Always place your personal settings files under Packages/User to guarantee that they will take precedence over any
other conflicting settings files.
With that out of the way, lets unveil the mysteries of how settings work to please masochistic readers.

8.1.1 Format
Settings files use JSON and have the .sublime-settings extension.

8.1.2 Types of Settings

The purpose of each .sublime-settings file is determined by its name. These names can be descriptive (like Preferences
(Windows).sublime-settings or Minimap.sublime-settings), or they can be related to what the settings file is controlling.
For example, file type settings need to carry the name of the .tmLanguage syntax definition for the file type. Thus, for
the .py file type, whose syntax definition is contained in Python.tmLanguage, the corresponding settings files would
be called Python.sublime-settings.
Also, some settings files only apply for specific platforms. This can be inferred from the file names: Preferences
(Windows).sublime-settings, Preferences (Linux).sublime-settings, etc.
This is important: Platform-specific settings files in the Packages/User folder are ignored. This way, you can be sure
a single settings file overrides all the others.

8.1.3 How to Access and Edit Common Settings Files

Unless you need very fine-grained control over settings, you can access the main configuration files through the
Preferences | Settings - User and Preferences | Settings - More menu items. Editing Preferences - Settings Default
isnt a smart thing to do, because changes will be reverted with every update to the software. However, you can use
that file for reference: it contains comments explaining the purpose of all available global and file type settings.

19

Sublime Text Unofficial Documentation, Release 2.0

8.1.4 Order of Precedence of .sublime-settings Files

The same settings file (such as Python.sublime-settings) can appear in multiple places. All settings defined in identically named files will be merged together and overwritten according to predefined rules. See Merging and Order of
Precedence for more information.
Let us remember again that any given settings file in Packages/User ultimately overrides every other settings file of
the same name.
In addition to settings files, Sublime Text maintains session data settings for the particular set of files being currently
edited. Session data is updated as you work on files, so if you adjust settings for a particular file in any way (mainly
through API calls), they will be recorded in the session and will take precedence over any applicable .sublime-settings
files.
To check the value of a setting in effect for a particular file, use view.settings().get(<setting_name>) from the console.
Lastly, its also worth noting that some settings may be adjusted automatically for you. Keep this is mind if youre
puzzled about some settings value. For instance, this is the case for certain whitespace-related settings and the
syntax setting.
Below, you can see the order in which Sublime Text would process a hypothetical hierarchy of settings for Python files
on Windows:
Packages/Default/Preferences.sublime-settings
Packages/Default/Preferences (Windows).sublime-settings
Packages/User/Preferences.sublime-settings
Packages/Python/Python.sublime-settings
Packages/User/Python.sublime-settings
Session data for the current file
Auto adjusted settings

8.1.5 Global Editor Settings and Global File Settings

These settings are stored in Preferences.sublime-settings and Preferences (<platform>).sublime-settings files. The
defaults can be found in Packages/Default.
Valid names for <platform> are Windows, Linux, OSX.

8.1.6 File Type Settings

If you want to target a specific file type, name the .sublime-settings file after the file types syntax definition. For
example, if our syntax definition was called Python.tmLanguage, wed need to call our settings file Python.sublimesettings.
Settings files for specific file types usually live in packages, like Packages/Python, but there can be multiple settings
files for the same file type in separate locations.
Similarly to global settings, one can establish platform-specific settings for file types.
(Linux).sublime-settings would only be consulted under Linux.

For example, Python

Also, let us emphasize that under Pakages/User only Python.sublime-settings would be read, but not any Python
(<platform>).sublime-settings variant.
Regardless of its location, any file-type-specific settings file has precedence over every global settings file affecting
file types.
20

Chapter 8. Customizing Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

8.1.7 Where to Store User Settings (Once Again)

Whenever you want to save settings, especially if they should be preserved between software updates, place the
corresponding .sublime-settings file in Packages/User.

8.2 Indentation
See Also:
Indentation Official Sublime Text Documentation.

8.3 Key Bindings

See Also:
Reference for key bindings Complete documentation on key bindings.
Key bindings let you map sequences of key presses to actions.

8.3.1 File Format

Key bindings are defined in JSON and stored in .sublime-keymap files. In order to integrate better with each
platform, there are separate key map files for Linux, OSX and Windows. Only key maps for the corresponding
platform will be loaded.
Example
Heres an excerpt from the default key map for Windows:
[
{ "keys": ["ctrl+shift+n"], "command": "new_window" },
{ "keys": ["ctrl+o"], "command": "prompt_open_file" }
]

8.3.2 Defining and Overriding Key Bindings

Sublime Text ships with a default key map (e.
g.
Packages/Default/Default
(Windows).sublime-keymap). In order to override key bindings defined there or add new ones, you
can store them in aseparate key map with a higher precedence, for example Packages/User/Default
(Windows).sublime-keymap.
See Merging and Order of Precedence for more information about how Sublime Text sorts files for merging.

8.3.3 Advanced Key Bindings

Simple key bindings consist of a key combination and a command to be executed. However, there are more complex
syntaxes to pass arguments and provide contextual awareness.

8.2. Indentation

21

Sublime Text Unofficial Documentation, Release 2.0

Passing Arguments
Arguments are specified in the args key:
{ "keys": ["shift+enter"], "command": "insert", "args": {"characters": "\n"} }

Here, \n is passed to the insert command when you press Shift+Enter.

Contexts
Contexts determine when a given key binding will be enabled based on the carets position or some other state.
{ "keys": ["escape"], "command": "clear_fields", "context":
[
{ "key": "has_next_field", "operator": "equal", "operand": true }
]
}

This key binding translates to clear snippet fields and resume normal editing if there is a next field available. Thus,
pressing ESC when you are not cycling through snippet fields will not trigger this key binding (however, something
else might occur instead if ESC happens to be bound to a different context too and thats likely to be the case for
ESC).

8.4 Menus
No documenation available about this topic.
But heres Bruce Lee screaming.

22

Chapter 8. Customizing Sublime Text

CHAPTER

NINE

EXTENDING SUBLIME TEXT

As it can be seen from the long list of topics below, Sublime Text is a very extensible editor.

9.1 Commands
Commands are ubiquitous in Sublime Text: key bindings, menu items and macros all work through the command
system. They are found in other places too.
Some commands are implemented in the editors core, but many of them are provided as python plugins. Every
command can be called from a python plugin.

9.1.1 Command Dispatching

Normally, commands are bound to the application object, a window object or a view object. Window objects, however,
will dispatch commands based on input focus, so you can issue a view command from a window object and the correct
view instance will be found for you.

9.1.2 Anatomy of a Command

Commands have a name separated by underscores, like hot_exit and can take a dictionary of arguments whose
keys must be strings and whose values must be JSON types. Heres a few examples of commands run from the Python
console:
view.run_command("goto_line", {"line": 10})
view.run_command(insert_snippet, {"contents": "<$SELECTION>"})
view.window().run_command("prompt_select_project")

See Also:
Reference for commands Command reference.

9.2 Macros
Macros are a basic automation facility consisting in sequences of commands. Use them whenever you need to repeat
the exact same steps to perform an operation.
Macro files are JSON files with the extension .sublime-macro. Sublime Text ships with a few macros providing
core functionality, such as line and word deletion. You can find these under Tools | Macros.

23

Sublime Text Unofficial Documentation, Release 2.0

9.2.1 How to Record Macros

To start recording a macro, press Ctrl+q and subsequently execute the desired steps one by one. When youre done,
press Ctrl+q again to stop the macro recorder. Your new macro wont be saved to a file, but kept in the macro buffer
instead. You will now be able to run the recorded macro by pressing Ctrl+Shift+q or save it to a file by selecting
Tools | Save macro. . . .
Note that the macro buffer will only remember the macro recorded latest. Also, recorded macros only capture commands sent to the buffer: window level commands, such as creating a new file, will be ignored.

9.2.2 How to Edit Macros

Alternatively to recording a macro, you can edit it by hand. Save a new file with the extension .sublime-macro
under PackagesUser and add commands to it. This is how a macro file looks like:
[
{"command": "move_to", "args": {"to": "hardeol"}},
{"command": "insert", "args": {"characters": "\n"}}
]

See the ../core/commands section for more information on commands.

If youre editing a macro by hand, you need to escape quotation marks, blank spaces and backslashes by preceding
them with \.

9.2.3 Where to Store Macros

Macro files can be stored in any package folder, and they will show up under Tools | Macros | <PackageName>.

9.3 Snippets
Whether you are coding or writing the next vampire best-seller, youre likely to need certain short fragments of text
again and again. Use snippets to save yourself tedious typing. Snippets are smart templates that will insert text for you
and adapt it to their context.
To create a new snippet, select Tools | New Snippet. . . . Sublime Text will present you with an skeleton for a new
snippet.
Snippets can be stored under any packages folder, but to keep it simple while youre learning, you can save them to
your Packages/User folder.

9.3.1 Snippets File Format

Snippets typically live in a Sublime Text package.
They are simplified XML files with the extension
sublime-snippet. For instance, you could have a greeting.sublime-snippet inside an Email package.
The structure of a typical snippet is as follows (including the default hints Sublime Text inserts for your convenience):
<snippet>
<content><![CDATA[Type your snippet here]]></content>
<!-- Optional: Tab trigger to activate the snippet -->
<tabTrigger>xyzzy</tabTrigger>
<!-- Optional: Scope the tab trigger will be active in -->

24

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

<scope>source.python</scope>
<!-- Optional: Description to show in the menu -->
<description>My Fancy Snippet</description>
</snippet>

The snippet element contains all the information Sublime Text needs in order to know what to insert, whether to
insert it and when. Lets see all of these parts in turn.
content The actual snippet. Snippets can range from simple to fairly complex templates. Well look at examples
of both later.
Keep the following in mind when writing your own snippets:
If you want the get a literal $, you have to escape it like this: \$.
When writing a snippet that contains indentation, always use tabs. The tabs will be transformed
into spaces when the snippet is inserted if the option translateTabsToSpaces is set to
true.
The content must be included in a <![CDATA[...]]> section. Snippets wont work if you
dont do this!
tabTrigger Defines the sequence of keys you will press to insert this snippet. The snippet will kick in as soon as
you hit the Tab key after typing this sequence.
A tab trigger is an implicit key binding.
scope Scope selector determining the context where the snippet will be active. See Scopes for more information.
description Used when showing the snippet in the Snippets menu. If not present, Sublime Text defaults to the
name of the snippet.
With this information, you can start writing your own snippets as described in the next sections.
Note: In the interest of brevity, were only including the content elements text in examples unless otherwise
noted.

9.3.2 Snippet Features

Environment Variables
Snippets have access to contextual information in the form of environment variables. Sublime Text sets the values of
the variables listed below automatically.
You can also add your own variables to provide extra information.
.sublime-options files.

9.3. Snippets

These custom variables are defined in

25

Sublime Text Unofficial Documentation, Release 2.0

$PARAM1, $PARAM2. . .
$SELECTION
$TM_CURRENT_LINE
$TM_CURRENT_WORD
$TM_FILENAME
$TM_FILEPATH
$TM_FULLNAME
$TM_LINE_INDEX
$TM_LINE_NUMBER
$TM_SELECTED_TEXT
$TM_SOFT_TABS
$TM_TAB_SIZE

Arguments passed to the insert_snippet command. (Not covered here.)

The text that was selected when the snippet was triggered.
Content of the line the cursor was in when the snippet was triggered.
Current word under the cursor when the snippet was triggered.
File name of the file being edited including extension.
File path to the file being edited.
Users user name.
Column the snippet is being inserted at, 0 based.
Row the snippet is being inserted at, 1 based.
An alias for $SELECTION.
YES if translate_tabs_to_spaces is true, otherwise NO.
Spaces per-tab (controlled by the tab_size option).

Lets see a simple example of a snippet using variables:

====================================
USER NAME:
$TM_FULLNAME
FILE NAME:
$TM_FILENAME
TAB SIZE:
$TM_TAB_SIZE
SOFT TABS:
$TM_SOFT_TABS
====================================
# Output:
====================================
USER NAME:
guillermo
FILE NAME:
test.txt
TAB SIZE:
4
SOFT TABS:
YES
====================================

Fields
With the help of field markers, you can cycle through positions within the snippet by pressing the Tab key. Fields are
used to walk you through the customization of a snippet once its been inserted.
First Name: $1
Second Name: $2
Address: $3

In the example above, the cursor will jump to $1 if you press Tab once. If you press Tab a second time, it will
advance to $2, etc. You can also move backwards in the series with Shift+Tab. If you press Tab after the highest
tab stop, Sublime Text will place the cursor at the end of the snippets content so that you can resume normal editing.
If you want to control where the exit point should be, use the $0 mark.
You can break out of the field cycle any time by pressing Esc.
Mirrored Fields
Identical field markers mirror each other: when you edit the first one, the rest will be populated with the same value in
real time.
First Name: $1
Second Name: $2
Address: $3
User name: $1

26

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

In this example, User name will be filled out with the same value as First Name.
Place Holders
By expanding the field syntax a little bit, you can define default values for a field. Place holders are useful when theres
a general case for your snippet but you still want to keep its customization convenient.
First Name: ${1:Guillermo}
Second Name: ${2:Lpez}
Address: ${3:Main Street 1234}
User name: $1

Variables can be used as place holders:

First Name: ${1:Guillermo}
Second Name: ${2:Lpez}
Address: ${3:Main Street 1234}
User name: ${4:$TM_FULLNAME}

And you can nest place holders within other place holders too:
Test: ${1:Nested ${2:Placeholder}}

Substitutions
Warning: This section is a draft and may contain inaccurate information.
In addition to the place holder syntax, tab stops can specify more complex operations with substitutions. Use substitutions to dynamically generate text based on a mirrored tab stop.
The substitution syntax has the following syntaxes:
${var_name/regex/format_string/}
${var_name/regex/format_string/options}
var_name The variable name: 1, 2, 3. . .
regex Perl-style regular expression: See the Boost library reference for regular expressions.
format_string See the Boost library reference for format strings.
options
Optional. May be any of the following:
i Case-insensitive regex.
g Replace all occurrences of regex.
m Dont ignore newlines in the string.
With substitutions you can, for instance, underline text effortlessly:
Original: ${1:Hey, Joe!}
Transformation: ${1/./=/g}
# Output:

9.3. Snippets

27

Sublime Text Unofficial Documentation, Release 2.0

Original: Hey, Joe!

Transformation: =========

9.4 Completions
See Also:
Reference for completions Complete documentation on all available options.
Sublime Text Documentation Official documentation on this topic.
Completions provide functionality in the spirit of IDEs to suggest terms and insert snippets. Completions work through
the completions list or, optionally, by pressing Tab.
Note that completions in the broader sense of words that Sublime Text will look up and insert for you are not limited
to completions files, because other sources contribute to the list of words to be completed, namely:
Snippets
API-injected completions
Buffer contents
However, .sublime-completions files are the most explicit way Sublime Text provides you to feed it completions. This topic deals with the creation of .sublime-completions files as well as with the interaction between
all sources for completions.

9.4.1 File Format

Completions are JSON files with the .sublime-completions extension. Entries in completions files can contain
either snippets or plain strings.
Example
Heres an excerpt from the HTML completions:
{
"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",
"completions":
[
{ "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
{ "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
]
}

scope Determines when the completions list will be populated with this list of completions. See Scopes for more
information.
In the example above, weve used trigger-based completions only, but completions files support simple completions
too. Simple completions are just plain strings. Expanding our example with a few simple completions, wed end up
with a list like so:

28

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

{
"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",
"completions":
[
{ "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
{ "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" },
"ninja",
"robot",
"pizza"
]
}

9.4.2 Sources for Completions

Completions not only originate in .sublime-completions files. This is the exhaustive list of sources for completions:
Snippets
API-injected completions
.sublime-completions files
Words in buffer
Priority of Sources for Completions
This is the order in which completions are prioritized:
Snippets
API-injected completions
.sublime-completions files
Words in buffer
Snippets will always win if the current prefix matches their tab trigger exactly. For the rest of the completions sources,
a fuzzy match is performed. Also, snippets will always lose against a fuzzy match. Note that this is only relevant if
the completion is going to be inserted automatically. When the completions list is shown, snippets will be listed along
the other items, even if the prefix only partially matches the snippets tab triggers.

9.4.3 How to Use Completions

There are two methods to use completions, and although the priority given to completions when screening them is
always the same, there is a difference in the result that will be explained below.
Completions can be inserted in two ways:
through the completions list (Ctrl+spacebar);
by pressing Tab.

9.4. Completions

29

Sublime Text Unofficial Documentation, Release 2.0

The Completions List

The completions list (Ctrl+spacebar) may work in two ways: by bringing up a list of suggested words to be
completed, or by inserting the best match directly.
If the choice of best completion is ambiguous, an interactive list will be presented to the user, who will have to select an
item himself. Unlike other items, snippets in this list are displayed in this format: <tab_trigger> : <name>,
where <tab_trigger> and <name> are variable.
The completion with Ctrl+spacebar will only be automatic if the list of completion candidates can be narrowed
down to one unambiguous choice given the current prefix.
Tab-completed Completions
If you want to be able to tab-complete completions, the setting tab_completion must be set to true. By default, tab_completion is set to true. Snippet tab-completion is unaffected by this setting: they will always be
completed according to their tab trigger.
With tab_completion enabled, completion of items is always automatic, which means that, unlike in the case of
the completions list, Sublime Text will always make a decision for you. The rules to select the best completion are the
same as above, but in case of ambiguity, Sublime Text will still insert the item deemed most suitable.
Inserting a Literal Tab Character

When tab_completion is enabled, you can press Shift+Tab to insert a literal tab character.

9.5 Command Palette

See Also:
Reference for Command Palette Complete documentation on the command palette options.

9.5.1 Overview
The command palette is an interactive list bound to Ctrl+Shift+P whose purpose is to execute commands. The
command palette is fed entries with commands files. Usually, commands that dont warrant creating a key binding of
their own are good candidates for inclusion in a .sublime-commands file.

9.5.2 File Format (Commands Files)

Commands files use JSON and have the .sublime-commands extension.
Heres an excerpt from Packages/Default/Default.sublime-commands:
[
{ "caption": "Project: Save As", "command": "save_project_as" },
{ "caption": "Project: Close", "command": "close_project" },
{ "caption": "Project: Add Folder", "command": "prompt_add_folder" },

{ "caption": "Preferences: Default File Settings", "command": "open_file", "args": {"file": "${pa
{ "caption": "Preferences: User File Settings", "command": "open_file", "args": {"file": "${packa
{ "caption": "Preferences: Default Global Settings", "command": "open_file", "args": {"file": "${

30

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

{ "caption": "Preferences: User Global Settings", "command": "open_file", "args": {"file": "${pac
{ "caption": "Preferences: Browse Packages", "command": "open_dir", "args": {"dir": "$packages"}
]

caption Text for display in the command palette.

command Command to be executed.
args Arguments to pass to command.

9.5.3 How to Use the Command Palette

1. Press Ctrl+Shift+P
2. Select command
The command palette filters entries by context, so whenever you open it, you wont always see all the commands
defined in every .sublime-commands file.

9.6 Syntax Definitions

Syntax definitions make Sublime Text aware of programming and markup languages. Most noticeably, they work
together with colors to provide syntax highlighting. Syntax definitions define scopes in a buffer that divide the text in
named regions. Several editing features in Sublime Text make extensive use of this fine-grained contextual information.
Essentially, syntax definitions consist of regular expressions used to find text, and more or less arbitrary, dot-separated
strings called scopes or scope names. For every occurrence of a given regular expression, Sublime Text gives the
matching text its corresponding scope name.

9.6.1 Prerequisites
In order to follow this tutorial, you will need to install AAAPackageDev, a package intended to ease the creation of
new syntax definitions for Sublime Text. AAAPackageDev lives on a public Mercurial repository at Bitbucket.
Download the latest .sublime-package file and install it as described in Installation of .sublime-package Files.
Mercurial and Bitbucket
Mercurial is a distributed version control system (DVCS). Bitbucket is an online service that provides hosting for
Mercurial repositories. If you want to install Mercurial, there are freely available command-line and graphical
clients.

9.6.2 File format

Sublime uses property list files (Plist) to store syntax definitions. Because editing XML files is a cumbersome task,
though, well be using JSON instead and converting it to Plist afterwards. This is where the AAAPackageDev package
mentioned above comes in.
Note: If you experience unexpected errors during this tutorial, chances are AAAPackageDev is to blame. Dont
immediately think your problem is due to a bug in Sublime Text.

9.6. Syntax Definitions

31

Sublime Text Unofficial Documentation, Release 2.0

By all means, do edit the Plist files by hand if you prefer to work in XML, but keep always in mind the differing needs
with regards to escape sequences, etc.

9.6.3 Scopes
Scopes are a key concept in Sublime Text. Essentially, they are named text regions in a buffer. They dont do anything
by themselves, but Sublime Text peeks at them when it needs contextual information.
For instance, when you trigger a snippet, Sublime Text checks the scope the snippets bound to and looks at the carets
position in the file. If the carets current scope matches the snippets scope selector, Sublime Text fires the snippet off.
Otherwise, nothing happens.
Scopes vs Scope Selectors
Theres a slight difference between scopes and scope selectors: scopes are the names defined in a syntax definition, whilst scope selectors are used in items like snippets and key bindings to target scopes. When creating a
new syntax definition, you care about scopes; when you want to constrain a snippet to a certain scope, you use a
scope selector.
Scopes can be nested to allow for a high degree of granularity. You can drill down the hierarchy very much like with
CSS selectors. For instance, thanks to scope selectors, you could have a key binding activated only within single
quoted strings in python source code, but not inside single quoted strings in any other language.
Sublime Text implements the idea of scopes from Texmate, a text editor for Mac. Textmates online manual contains
further information about scope selectors thats useful for Sublime Text users too.

9.6.4 How Syntax Definitions Work

At their core, syntax definitions are arrays of regular expressions paired with scope names. Sublime Text will try to
match these patterns against a buffers text and attach the corresponding scope name to all occurrences. These pairs of
regular expressions and scope names are known as rules.
Rules are applied in order, one line at a time. Each rule consumes the matched text region, which will therefore
be excluded from the next rules matching attempt (save for a few exceptions). In practical terms, this means that
you should take care to go from more specific rules to more general ones when you create a new syntax definition.
Otherwise, a greedy regular expression might swallow parts youd like to have styled differently.
Syntax definitions from separate files can be combined, and they can be recursively applied too.

9.6.5 Your First Syntax Definition

By way of example, lets create a syntax definition for Sublime Text snippets. Well be styling the actual snippet
content, not the .sublime-snippet file.
Note: Since syntax definitions are primarily used to enable syntax highlighting, well use to style as in to break down
a source code file into scopes. Keep in mind, however, that colors are a different thing to syntax definitions and that
scopes have many more uses besides syntax highlighting.
These are the elements we want to style in a snippet:
Variables ($PARAM1, $USER_NAME. . . )

32

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

Simple fields ($0, $1. . . )

Complex fields with place holders (${1:Hello})
Nested fields (${1:Hello ${2:World}!})
Escape sequences (\\$, \\<. . . )
Illegal sequences ($, <. . . )
Note: Before continuing, make sure youve installed the AAAPackageDev package as explained further above.

Creating A New Syntax Definition

To create a new syntax definition, follow these steps:
Go to Tools | Packages | Package Development | New Syntax Definition
Save the new file to your Packages/User folder as Sublime Snippets (Raw).JSON-tmLanguage.
You should now see a file like this:
{ "name": "Syntax Name",
"scopeName": "source.syntax_name",
"fileTypes": [""],
"patterns": [
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

Lets examine now the key elements.

uuid Located at the end, this is a unique identifier for this syntax definition. Each new syntax definition gets its own
uuid. Dont modify them.
name The name that Sublime Text will display in the syntax definition drop-down list Use a short, descriptive name.
Typically, you will be using the programming languages name you are creating the syntax definition for.
scopeName The top level scope for this syntax definition. It takes the form source.<lang_name> or
text.<lang_name>. For programming languages, use source. For markup and everything else, text.
fileTypes This is a list of file extensions. When opening files of these types, Sublime Text will automatically
activate this syntax definition for them.
patterns Container for your patterns.
For our example, fill in the template with the following information:
{

"name": "Sublime Snippet (Raw)",

"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"

Note: JSON is a very strict format, so make sure to get all the commas and quotes right. If the conversion to Plist
fails, take a look at the output panel for more information on the error. Well explain later how to convert a syntax
definition in JSON to Plist.

9.6. Syntax Definitions

33

Sublime Text Unofficial Documentation, Release 2.0

9.6.6 Analyzing Patterns

The patterns array can contain several types of elements. Well look at some of them in the following sections. If
you want to learn more about patterns, refer to Textmates online manual.
Regular Expressions Syntax In Syntax Definitions
Sublime Text uses Onigurumas syntax for regular expressions in syntax definitions. Several existing syntax
definitions make use of features supported by this regular expression engine that arent part of perl-style regular
expressions, hence the requirement for Oniguruma.

Matches
They take this form:
{ "match": "[Mm]y \s+[Rr]egex",
"name": "string.ssraw",
"comment": "This comment is optional."
}

match A regular expression Sublime Text will use to try and find matches.
name Name of the scope that should be applied to the occurrences of match.
comment An optional comment about this pattern.
Lets go back to our example. Make it look like this:
{ "name": "Sublime Snippet (Raw)",
"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

That is, make sure the patterns array is empty.

Now we can begin to add our rules for Sublime snippets. Lets start with simple fields. These could be matched with
a regex like so:
\$[0-9]+
# or...
\$\d+

However, because were writing our regex in JSON, we need to factor in JSONs own escaping rules. Thus, our
previous example becomes:
\\$\\d+

With escaping out of the way, we can build our pattern like this:
{ "match": "\\$\\d+",
"name": "keyword.source.ssraw",
"comment": "Tab stops like $1, $2..."
}

34

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

Choosing the Right Scope Name

Naming scopes isnt obvious sometimes. Check the Textmate online manual for guidance on scope names. It
is important to re-use the basic categories outlined there if you want to achieve the highest compatibility with
existing colors.
Colors have hardcoded scope names in them. They could not possibly include every scope name you can think
of, so they target the standard ones plus some rarer ones on occasion. This means that two colors using the same
syntax definition may render the text differently!
Bear in mind too that you should use the scope name that best suits your needs or preferences. Itd be perfectly
fine to assign a scope like constant.numeric to anything other than a number if you have a good reason to
do so.
And we can add it to our syntax definition too:
{

"name": "Sublime Snippet (Raw)",

"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
{ "match": "\\$\\d+",
"name": "keyword.source.ssraw",
"comment": "Tab stops like $1, $2..."
}
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"

Were now ready to convert our file to .tmLanguage. Syntax definitions use Textmates .tmLanguage extension
for compatibility reasons. As explained further above, they are simply XML files in the Plist format.
Follow these steps to perform the conversion:
Select Json to tmLanguage in Tools | Build System
Press F7
A .tmLanguage file will be generated for you in the same folder as your .JSON-tmLanguage file
Sublime Text will reload the changes to the syntax definition
You have now created your first syntax definition. Next, open a new file and save it with the extension .ssraw. The
buffers syntax name should switch to Sublime Snippet (Raw) automatically, and you should get syntax highlighting
if you type $1 or any other simple snippet field.
Lets proceed to creating another rule for environment variables.
{ "match": "\\$[A-Za-z][A-Za-z0-9_]+",
"name": "keyword.source.ssraw",
"comment": "Variables like $PARAM1, $TM_SELECTION..."
}

Repeat the steps above to update the .tmLanguage file and restart Sublime Text.
Fine Tuning Matches
You might have noticed that the entire text in $PARAM1, for instance, is styled the same way. Depending on your
needs or your personal preferences, you may want the $ to stand out. Thats where captures come in. Using
captures, you can break a pattern down into components to target them individually.
Lets rewrite one of our previous patterns to use captures:
9.6. Syntax Definitions

35

Sublime Text Unofficial Documentation, Release 2.0

{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Variables like $PARAM1, $TM_SELECTION..."
}

Captures introduce complexity to your rule, but they are pretty straightforward. Notice how numbers refer to parenthesized groups left to right. Of course, you can have as many capture groups as you want.
Arguably, youd want the other scope to be visually consistent with this one. Go ahead and change it too.
Begin-End Rules
Up to now weve been using a simple rule. Although weve seen how to dissect patterns into smaller components,
sometimes youll want to target a larger portion of your source code clearly delimited by start and end marks.
Literal strings enclosed in quotation marks and other delimited constructs are better dealt with with begin-end rules.
This is a skeleton for one of these rules:
{ "name": "",
"begin": "",
"end": ""
}

Well, at least in their simplest version. Lets take a look at one including all available options:
{ "name": "",
"begin": "",
"beginCaptures": {
"0": { "name": "" }
},
"end": "",
"endCaptures": {
"0": { "name": "" }
},
"patterns": [
{ "name": "",
"match": ""
}
],
"contentName": ""
}

Some elements may look familiar, but their combination might be daunting. Lets see them individually.
begin Regex for the opening mark for this scope.
end Regex for the end mark for this scope.
beginCaptures Captures for the begin marker. They work like captures for simple matches. Optional.
endCaptures Same as beginCaptures but for the end marker. Optional.
contentName Scope for the whole matched region, from the begin marker to the end marker, inclusive. This will
effectively create nested scopes for beginCaptures, endCaptures and patterns defined within this
rule. Optional.

36

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

patterns An array of patterns to match against the begin-end content only they are not matched against the text
consumed by begin or end.
Well use this rule to style nested complex fields in snippets:
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.ssraw" },
"3": { "name": "constant.numeric.ssraw" }
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
}

This is the most complex pattern well see in this tutorial. The begin and end keys are self-explanatory: they define
a region enclosed between ${<NUMBER>: and }. beginCaptures further divides the begin mark into smaller
scopes.
The most interesting part, however, is patterns. Recursion and the importance of ordering have finally made an
appearance here.
Weve seen further above that fields can be nested. In order to account for this, we need to recursively style nested
fields. Thats what the include rule does when furnished the $self value: it recursively applies our entire syntax
definition to the portion of text contained in our begin-end rule, excluding the text consumed by both begin and end.
Remember that matched text is consumed and is excluded from the next match attempt.
To finish off complex fields, well style place holders as strings. Since weve already matched all possible tokens
inside a complex field, we can safely tell Sublime Text to give any remaining text (.) a literal string scope.
Final Touches
Lastly, lets style escape sequences and illegal sequences, and wrap up.
{

"name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"

},
{

"name": "invalid.ssraw",
"match": "(\\$|\\<|\\>)"

The only hard thing here is getting the number of escape characters right. Other than that, the rules are pretty straightforward if youre familiar with regular expressions.
However, you must take care to put the second rule after any others matching the $ character, since otherwise you may
not get the desired result.
Also, note that after adding these two additional rules, our recursive begin-end rule above keeps working as expected.
At long last, heres the final syntax definition:
{

"name": "Sublime Snippet (Raw)",

"scopeName": "source.ssraw",

9.6. Syntax Definitions

37

Sublime Text Unofficial Documentation, Release 2.0

"fileTypes": ["ssraw"],
"patterns": [
{ "match": "\\$(\\d+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Tab stops like $1, $2..."
},
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Variables like $PARAM1, $TM_SELECTION..."
},
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.ssraw" },
"3": { "name": "constant.numeric.ssraw" }
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
},
{ "name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"
},
{ "name": "invalid.ssraw",
"match": "(\\$|\\>|\\<)"
}
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

There are more available constructs and code reuse techniques, but the above explanations should get you started with
the creation of syntax definitions.

9.7 Plugins
See Also:
API Reference More information on the Python API.
Plugins Reference More information about plugins.
Sublime Text 2 is programmable with Python scripts. Plugins reuse existing commands or create new ones to build a
feature. Plugins are rather a logical entity than a physical one.

38

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

9.7.1 Prerequisites
In order to write plugins, you must be able to program in Python.

9.7.2 Where to Store Plugins

Sublime Text 2 will look for plugins in these places:
Packages
Packages/<pkg_name>/
Consequently, any plugin nested deeper in Packages wont be loaded.
Keeping plugins right under Packages is discouraged, because Sublime Text sorts packages in a predefined way
before loading them. Thus, you might get confusing results if your plugins live outside of a package.

9.7.3 Your First Plugin

Lets write a Hello, World! plugin for Sublime Text 2:
1. Select Tools | New Plugin. . . in the menu.
2. Save to Packages/User/hello_world.py.
Youve just written your first plugin. Lets put it to use:
1. Create a new buffer (Ctrl+n).
2. Open the python console (Ctrl+).
3. Type: view.run_command("example") and press enter.
You should see the text Hello, World! in your new buffer.

9.7.4 Analyzing Your First Plugin

The plugin created in the previous section should look roughly like this:
import sublime, sublime_plugin
class ExampleCommand(sublime_plugin.TextCommand):
def run(self, edit):
self.view.insert(edit, 0, "Hello, World!")

The sublime and sublime_plugin modules are both provided by Sublime Text 2.
New commands derive from the *Command classes defined in sublime_plugin (more on this later).
The rest of the code is concerned with particulars of the TextCommand or the API that well discuss in the next
sections.
Before moving on, though, well look at how we called the new command: We first opened the python console, and
then issued a call to view.run_command(). This is a rather inconvenient way of using plugins, but its often
useful when youre in the development phase. For now, keep in mind that your commands can be accessed through
key bindings or other means, just as other commands are.

9.7. Plugins

39

Sublime Text Unofficial Documentation, Release 2.0

Conventions for Command Names

You might have noticed that our command is defined with the name ExampleCommand, but we pass the
string example to the API call instead. This is necessary because Sublime Text 2 normalizes command
names by stripping the Command suffix and separating CamelCasedPhrases with underscores, like this:
camel_cased_phrases.
New commands should follow the pattern mentioned above for class names.

9.7.5 Types of Commands

You can create the following types of commands:
Application commands (ApplicationCommand)
Window commands (WindowCommand)
Text commands (TextCommand)
When writing plugins, consider your goal and choose the appropriate type of commands for your plugin.
Shared Traits of Commands
All commands need to implement a .run() method in order to work. Additionally, they can receive and arbitrarily
long number of keyword parameters.
Application Commands
Application commands derive from sublime_plugin.ApplicationCommand and can be executed with
sublime.run_command().
Window Commands
Window commands operate at the window level. This doesnt mean that you cannot manipulate views from window
commands, but rather that you dont need views to exist in order for window commands to be available. For instance,
the built-in command new_file is defined as a WindowCommand so it works too when no view is open. Requiring
a view to exist in that case wouldnt make sense.
Window command instances have a .window attribute pointing to the window instance that created them.
The .run() method of a window command does not need to take any required arguments.
Text Commands
Text commands operate at the buffer level and they require a buffer to exist in order to be available.
View command instances have a .view attribute pointing to the view instance that created them.
The .run() method of a text command needs to take an edit instance as a first positional argument.

40

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

Text Commands and the edit Object

The edit object groups modifications to the view so undo and macros work in a sensible way. You are responsible for
creating and closing edit objects. To do so, you can call view.begin_edit() and edit.end_edit(). Text
commands get passed an open edit object in their run method for convenience. Additionally, many View methods
require an edit object.
Responding to Events
Any command deriving from EventListener will be able to respond to events.
Another Plugin Example: Feeding the Completions List
Lets create a plugin that fetches data from Google Autocomplete service and feeds it to Sublime Text 2 completions
list. Please note that as ideas for plugins go, this a very bad one.
import sublime, sublime_plugin
from xml.etree import ElementTree as ET
from urllib import urlopen
GOOGLE_AC = r"http://google.com/complete/search?output=toolbar&q=%s"
class GoogleAutocomplete(sublime_plugin.EventListener):
def on_query_completions(self, view, prefix, locations):
elements = ET.parse(
urlopen(GOOGLE_AC % prefix)
).getroot().findall("./CompleteSuggestion/suggestion")
sugs = [(x.attrib["data"],) * 2 for x in elements]
return sugs

Note: Make sure you dont keep this plugin around after trying it or it will interefere with the autocompletion system.

9.7.6 Learning the API

In order to create plugins, you need to get acquainted with the Sublime Text API and the available commands. Documentation on both is scarce at the time of this writing, but you can read existing code and learn from it too. In
particular, the Packages/Default folder contains many examples of undocumented commands and API calls.

9.8 Packages
Packages are simply directories under Packages. They exist mainly for organizational purposes, but Sublime Text
follows a few rules when dealing with them. More on this later.
Heres a list of typical resources living inside packages:
build systems (.sublime-build)
key maps (.sublime-keymap)

9.8. Packages

41

Sublime Text Unofficial Documentation, Release 2.0

macros (.sublime-macro)
menus (.sublime-menu)
plugins (.py)
preferences (.tmPreferences)
settings (.sublime-settings)
syntax definitions (.tmLanguage)
snippets (.sublime-snippet)
themes (.sublime-theme)
Some packages may include support files for other packages or core features. For example, the spell checker uses
PackagesLanguage - English as a data store for English dictionaries.

9.8.1 Types of Packages

In order to talk about packages in this guide, well divide them in groups. This division is artificial and for the sake of
clarity in this topic. Sublime Text doesnt use it in any way.
core packages Sublime Text requires these packages in order to work.
shipped packages Sublime Text includes these packages in every installation, although they are not technically required. Shipped packages enhance Sublime Text out of the box. They may have been contributed by users or
third parties.
user packages These packages are installed by the user to further extend Sublime Text. They are not part of any
Sublime Text installation and are always contributed by users or third parties.
installed packages Any package that Sublime Text can restore if deleted.
Lets emphasize again that you dont need to memorize this classification. Also, its worth noting that by third party
we mainly refer to other editors users, like Textmates.

9.8.2 Installation of Packages

There are two main ways to install packages:
.sublime-package files
version control systems
Ultimately, installing a package consists simply in placing a directory containing Sublime Text resources under
Packages. The only thing that changes from one system to another is how you copy these files.
Installing Packages vs Installed Packages
Note that installing a package doesnt actually make that package an installed package. Installed packages are
.sublime-package files residing in the Installed Packages directory. In this guide, we use to install
a package to mean to copy a package to Packages.
Sublime Text can restore any package located in Installed Packages, but not every package located in
Packages.

42

Chapter 9. Extending Sublime Text

Sublime Text Unofficial Documentation, Release 2.0

Installation of .sublime-package Files

Copy the .sublime-package file to the Installed Packages directory and restart Sublime Text. If the
Installed Packages doesnt exist, you can create it.
Note that .sublime-package files are simply .zip archives with a custom file extension.
Installation of Packages from a Version Control System
Explaining how to use version control systems (VCSs) is outside the scope of this guide, but there are many user
packages available for free on public repositories like Google Code, GitHub and Bitbucket.
Also, there is a Sublime Text organization at GitHub open to contributors.

9.8.3 Packages and Magic

Theres little invisible magic involved in the way Sublime Text deals with packages. Two notable exceptions are that
macros defined in any package appear under Tools | Macros | <Your Package>, and snippets from any package appear
under Tools | Snippets | <Your Package>.
As mentioned at the beginning, however, there are some rules for packages. For instance, Package/User will never
be clobbered during updates of the software.
The User Package
Usually, unpackaged resources are stored in Packages/User. If you have a few loose snippets, macros or
plugins, this is a good place to keep them.

Merging and Order of Precedence

Packages/Default and Packages/User also receive a special treatment when merging files (e. g.
.sublime-keymap and .sublime-settings files). Before the merging can take place, the files have to be
arranged in an order. To that end, Sublime Text sorts them alphabetically by name with the exception of files contained in Default and User: Default will always go to the front of the list, and User to the end.

9.8.4 Restoring Packages

Sublime Text keeps a copy of all installed packages so it can recreate them when needed. This means it will be able
to reinstall core packages, shipped packages and user packages alike. However, only user packages installed as a
sublime-package are added to the registry of installed packages. Packages installed in alternative ways will be
completely lost if you delete them.
Reverting Sublime Text to Its Default Configuration
To revert Sublime Text to its default configuration, delete the data directory and restart the editor. Keep in mind,
though, that the Installed Packages directory will be deleted too, so you will lose all installed packages.
Always make sure to back up your data before taking an extreme measure like this one.

9.8. Packages

43

Sublime Text Unofficial Documentation, Release 2.0

9.8.5 The Installed Packages Directory

You will find this directory in the data directory. It contains a copy of every sublime-package installed. Used to
restore Packages.

9.8.6 The Pristine Packages Directory

You will find this directoy in the data directory. It contains a copy of every shipped and core package. Used to restore
Packages.

44

Chapter 9. Extending Sublime Text

CHAPTER

TEN

COMMAND LINE USAGE

See Also:
OS X Command Line Official Sublime Text Documentation

45

Sublime Text Unofficial Documentation, Release 2.0

46

Chapter 10. Command Line Usage

CHAPTER

ELEVEN

REFERENCE
In this section you will find concise information about many aspects of Sublime Text.
If youre looking for a slow-paced introduction to any of these topics, try the general index.

11.1 Snippets
11.1.1 Compatibility with Textmate
Sublime Text snippets are generally compatible with Textmate snippets.

11.1.2 File Format

Snippet files are XML files with the sublime-snippet extension.
<snippet>
<content><![CDATA[]]></content>
<tabTrigger></tabTrigger>
<scope></scope>
<description></description>
</snippet>

content Actual snippet content.

tabTrigger Implicit keybinding for this snippet. Last key (implicit) is TAB.
scope Scope selector to activate this snippet.
description User friendly description for menu item.

11.1.3 Escape Sequences

\$ Literal $.

47

Sublime Text Unofficial Documentation, Release 2.0

11.1.4 Environment Variables

$PARAM1 .. $PARAMn
$SELECTION
$TM_CURRENT_LINE
$TM_CURRENT_WORD
$TM_FILENAME
$TM_FILEPATH
$TM_FULLNAME
$TM_LINE_INDEX
$TM_LINE_NUMBER
$TM_SELECTED_TEXT
$TM_SOFT_TABS
$TM_TAB_SIZE

Arguments passed to the insertSnippet command.

The text that was selected when the snippet was triggered.
Content of the line the cursor was in when the snippet was triggered.
Current word under the cursor when the snippet was triggered.
File name of the file being edited including extension.
File path to the file being edited.
Users user name.
Column the snippet is being inserted at, 0 based.
Row the snippet is being inserted at, 1 based.
An alias for $SELECTION.
YES if translateTabsToSpaces is true, otherwise NO.
Spaces per-tab (controlled by the tabSize option).

11.1.5 Fields
Mark positions to cycle through by pressing TAB or SHIFT + TAB.
Syntax: $1 .. $n
$0 Exit mark. Position at which normal text editing should be resumed. By default, Sublime Text implicitly sets this
mark at the end of the snippets content element.
Fields with the same name mirror each other.

11.1.6 Place Holders

Fields with a default value.
Syntax: ${1:PLACE_HOLDER} .. ${n:PLACE_HOLDER}
Fields and place holders can be combined and nested within other place holders.

11.1.7 Substitutions
Syntax:
${var_name/regex/format_string/}
${var_name/regex/format_string/options}
var_name The fields name to base the substitution on: 1, 2, 3. . .
regex Perl-style regular expression: See the Boost library documentation for regular expressions.
format_string See the Boost library documentation for format strings.
options
Optional. Any of the following:
i Case-insensitive regex.
g Replace all occurrences of regex.
m Dont ignore newlines in the string.

48

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

11.2 Syntax Definitions

Warning: This topic is a draft and may contain wrong information.

11.2.1 Compatibility with Textmate

Sublime Text syntax definitions are generally compatible with Textmate language files.

11.2.2 File Format

Syntax definitions are files in the Plist format with the tmLanguage extension. In this reference files, however, JSON
is used instead and converted into Plist.
{ "name": "Sublime Snippet (Raw)",
"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
{ "match": "\\$(\\d+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Tab stops like $1, $2..."
},
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Variables like $PARAM1, $TM_SELECTION..."
},
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.control.ssraw" },
"3": { "name": "constant.numeric.ssraw" }
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
},
{ "name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"
},
{ "name": "invalid.ssraw",
"match": "(\\$|\\>|\\<)"
}
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

11.2. Syntax Definitions

49

Sublime Text Unofficial Documentation, Release 2.0

name Descriptive name for the syntax definition. Shows up in the syntax definition dropdown menu located in the
bottom right of Sublime Text interface. Its usually the name of the programming language or equivalent.
scopeName Name of the top-level scope for this syntax definition. Either source.<lang> or text.<lang>.
Use source for programming languages and text for everything else.
fileTypes And array of file type extensions for which this syntax should be automatically activated. Include the
extensions without the leading dot.
uuid Unique indentifier for this syntax definition. Currently ignored.
foldingStartMarker Currently ignored. Used for code folding.
foldingStopMarker Currently ignored. Used for code folding.
patterns Array of patterns to match against the buffers text.
repository Array of patterns abstracted out from the patterns element. Useful to keep the syntax definition tidy
as well as for specialized uses like recursive patterns. Optional.

11.2.3 The Patterns Array

Elements contained in the patterns array.
match Contains the following elements:
match
name
comment
captures

Pattern to search for.

Scope name to be assigned to matches of match.
Optional. For information only.
Optional. Refinement of match. See below.

In turn, captures can contain n of the following pairs of elements:

0..n
name

Name of the group referenced.

Scope to be assigned to the group.

Examples:
// Simple
{ "name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"
"comment". "Sequences like \$, \> and \<"
}
// With captures
{ "match": "\\$(\\d+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Tab stops like $1, $2..."
}

include Includes items in the repository, other syntax definitions or the current one.
References:
$self
#itemName
source.js

50

The current syntax definition.

itemName in the repository.
External syntax definitions.

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

Examples:
// Requires presence of DoubleQuotedStrings element in the repository.
{ "include": "#DoubleQuotedStrings" }
// Recursively includes the current syntax definition.
{ "include": "$self" }
// Includes and external syntax definition.
{ "include": "source.js" }

begin..end Defines a scope potentially spanning multiple lines

Contains the following elements:
begin
end
name
beginCaptures
endCaptures
patterns
contentName

The start marker pattern.

The end marker pattern.
Scope name for the whole region.
captures for begin. See captures.
captures for end. See captures.
patterns to be matched against the content.
Scope name for the content excluding the markers.

Example:
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.control.ssraw" },
"3": { "name": "constant.numeric.ssraw" }
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
}

11.2.4 Repository
Can be referenced from patterns or from itself in an include element. See include for more information.
The repository can contain the following elements:
Simple elements:
"elementName": {
"match": "some regexp",
"name":
"some.scope.somelang"
}

Complex elements:
"elementName": {
"patterns": [
{ "match": "some regexp",
"name":
"some.scope.somelang"

11.2. Syntax Definitions

51

Sublime Text Unofficial Documentation, Release 2.0

},
{ "match":
"name":
}

"other regexp",
"some.other.scope.somelang"

]
}

Examples:
"repository": {
"numericConstant": {
"patterns": [
{ "match": "\\d*(?<!\\.)(\\.)\\d+(d)?(mb|kb|gb)?",
"name":
"constant.numeric.double.powershell",
"captures": {
"1": { "name": "support.constant.powershell" },
"2": { "name": "support.constant.powershell" },
"3": { "name": "keyword.other.powershell" }
}
},
{ "match": "(?<!\\w)\\d+(d)?(mb|kb|gb)?(?!\\w)",
"name":
"constant.numeric.powershell",
"captures": {
"1": { "name": "support.constant.powershell" },
"2": { "name": "keyword.other.powershell" }
}
}
]
},
"scriptblock": {
"begin": "\\{",
"end":
"\\}",
"name":
"meta.scriptblock.powershell",
"patterns": [
{ "include": "$self" }
]
},
}

11.2.5 Escape Sequences

Be sure to escape JSON/XML sequences as needed.

11.3 Build Systems

Build systems let you run your files through external programs and see the output they generate within Sublime Text.
Build systems consist of two or optionally three parts:
configuration data in JSON format (the .sublime-build file contents)
a Sublime Text command driving the build process
optionally, an external executable file (script, binary file)
Essentially, .sublime-build files are configuration data for an external program as well as for the Sublime Text command
just mentioned. In them, you specify the switches, options and environment information you want forwarded.
52

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

The Sublime Text command then receives the data stored in the .sublime-build file. At this point, it can do whatever it needs to build the files. By default, build systems will use the exec command, implemented in Packages/Default/exec.py. As well explain below, you can override this command.
Lastly, the external program may be a shell script youve created to process your files, or a well-known utility like
make or tidy. Usually, these executable files will receive paths to files or directories, along with switches and
options to be run with.
Note that build systems need not call any external program at all if there isnt any reason to; you could implement a
build system entirely in a Sublime Text command.

11.3.1 File Format

.build-system files use JSON. Heres an example:
{
"cmd": ["python", "-u", "$file"],
"file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
"selector": "source.python"
}

11.3.2 Options
cmd Array containing the command to run and its desired arguments. If you dont specify an absolute path, the
external program will be searched in your PATH, one of your systems environmental variables.
On Windows, GUIs are supressed.
file_regex Optional. Regular expression (Perl-style) to capture error output of cmd. See the next section for
details.
line_regex Optional. If file_regex doesnt match on the current line, but line_regex exists, and it does
match on the current line, then walk backwards through the buffer until a line matching file regex is found,
and use these two matches to determine the file and line to go to.
selector Optional. Used when Tools | Build System | Automatic is set to true. Sublime Text uses this scope
selector to find the appropriate build system for the active view.
working_dir Optional. Directory to change the current directory to before running cmd. The original current
directory is restored afterwards.
encoding Optional. Output encoding of cmd. Must be a valid python encoding. Defaults to UTF-8.
target Optional. Sublime Text command to run. Defaults to exec (Packages/Default/exec.py). This command
receives the configuration data specified in the .build-system file.
Used to override the default build system command. Note that if you choose to override the default command
for build systems, you can add arbitrary variables in the .sublime-build file.
env Optional. Dictionary of environment variables to be merged with the current process before passing them to
cmd.
Use this element, for example, to add or modify environment variables without modifying your systems settings.
shell Optional. If true, cmd will be run through the shell (cmd.exe, bash. . . ).
path Optional. This string will replace the current process PATH before calling cmd. The old PATH value will be
restored after that.
Use this option to add directories to PATH without having to modify your systems settings.

11.3. Build Systems

53

Sublime Text Unofficial Documentation, Release 2.0

variants Optional. A list of dictionaries of options to override the main build systems options. Variant names
will appear in the Command Palette for easy access if the build systems selector matches for the active file.
name Only valid inside a variant (see variants). Identifies variant build systems. If name is Run, the variant
will show up under the Tools | Build System menu and be bound to Ctrl + Shift + B.
Capturing Error Output with file_regex
The file_regex option uses a Perl-style regular expression to capture up to four fields of error information from
the build programs output, namely: file name, line number, column number and error message. Use groups in the
pattern to capture this information. The file name field and the line number field are required.
When error information is captured, you can navigate to error instances in your projects files with F4 and Shift+F4.
If available, the captured error message will be displayed in the status bar.
Platform-specific Options
The windows, osx and linux elements let you provide platform-specific data in the build system. Heres an
example:
{
"cmd": ["ant"],
"file_regex": "^ *\\[javac\\] (.+):([0-9]+):() (.*)$",
"working_dir": "${project_path:${folder}}",
"selector": "source.java",
"windows":
{
"cmd": ["ant.bat"]
}
}

In this case, ant will be executed for every platform except Windows, where ant.bat will be used instead.
Variants
Heres a contrived example of a build system with variants:
{
"selector": "source.python",
"cmd": ["date"],
"variants": [
{ "cmd": ["ls -l *.py"],
"name": "List Python Files",
"shell": true
},
{ "cmd": ["wc", "$file"],
"name": "Word Count (current file)"
},
{ "cmd": ["python", "-u", "$file"],
"name": "Run"
}

54

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

]
}

Given these settings, Ctrl + B would run the date command, Crtl + Shift + B would run the Python interpreter and the
remaining variants would appear in the Command Palette whenever the build system was active.

11.3.3 Build System Variables

Build systems expand the following variables in .sublime-build files:
$file_path
$file
$file_name
$file_extension
$file_base_name
$packages
$project
$project_path
$project_name
$project_extension
$project_base_name

The directory of the current file, e. g., C:\Files.

The full path to the current file, e. g., C:\Files\Chapter1.txt.
The name portion of the current file, e. g., Chapter1.txt.
The extension portion of the current file, e. g., txt.
The name only portion of the current file, e. g., Document.
The full path to the Packages folder.
The full path to the current project file.
The directory of the current project file.
The name portion of the current project file.
The extension portion of the current project file.
The name only portion of the current project file.

Place Holders for Variables

Features found in snippets can be used with these variables. For example:
${project_name:Default}

This will emit the name of the current project if there is one, otherwise Default.
${file/\.php/\.txt/}

This will emit the full path of the current file, replacing .php with .txt.

11.3.4 Running Build Systems

Select the desired build system from Tools | Build System, and then select Tools | Build or press F7.

11.3.5 Troubleshooting Build Systems

Build systems will look for executables in your PATH, unless you specify an absolute path to the executable. Therefore,
your PATH variable must be correctly set.
On some operating systems, the value for PATH will vary from a terminal window to a graphical application. Thus,
even if the command you are using in your build system works in the command line, it may not work from Sublime
Text. This is due to user profiles in shells.
To solve this issue, make sure you set the desired PATH so that graphical applications such as Sublime Text can find
it. See the links below for more information.
Alternatively, you can use the path element in .sublime-build files to override the PATH used to locate the executable
specified in cmd. This new value for PATH will only be in effect for as long as your build system is running. After
that, the old PATH will be restored.

11.3. Build Systems

55

Sublime Text Unofficial Documentation, Release 2.0

See Also:
Managing Environment Variables in Windows Search Microsoft knowledge base for this topic.
Setting environment variables in OSX StackOverflow topic.

11.4 Key Bindings

Key bindings map key presses to commands.

11.4.1 File Format

Key bindings are stored in .sublime-keymap files and defined in JSON. All key map file names need to follow
this pattern: Default (<platform>).sublime-keymap. Otherwise, Sublime Text will ignore them.
Platform-Specific Key Maps
Each platform gets its own key map:
Default (Windows).sublime-keymap
Default (OSX).sublime-keymap
Default (Linux).sublime-keymap
Separate key maps exist to abide by different vendor-specific HCI guidelines.
Structure of a Key Binding
Key maps are arrays of key bindings. Below youll find valid elements in key bindings.
keys An array of case-sensitive keys to be pressed. Modifiers can be specified with the + sign. Chords are built by
adding elements to the array, e. g. ["ctrl+k","ctrl+j"]. Ambiguous chords are resolved with a timeout.
command Name of the command to be executed.
args Dictionary of arguments to be passed to command. Keys must be the names of parameters to command.
context Array of contexts to selectively enable the key binding. All contexts must be true for the key binding to
trigger. See Structure of a Context below.
Heres an example illustrating most of the features outlined above:

{ "keys": ["shift+enter"], "command": "insert_snippet", "args": {"contents": "\n\t$0\n"}, "context":

[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true },
{ "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true }
{ "key": "preceding_text", "operator": "regex_contains", "operand": "\\{$", "match_al
{ "key": "following_text", "operator": "regex_contains", "operand": "^\\}", "match_al
]
}

56

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

Structure of a Context
key Name of a context operand to query.
operator Type of test to perform against key.
operand Value against which the result of key is tested.
match_all Requires the test to succeed for all selections. Defaults to false.
Context Operands

auto_complete_visible Returns true if the autocomplete list is visible.

has_next_field Returns true if theres a next snippet field available.
has_prev_field Returns true if theres a previous snippet field available.
num_selections Returns the number of selections.
overlay_visible Returns true if any overlay is visible.
panel_visible Returns true if any panel is visible.
following_text Restricts the test to the text following the caret.
preceding_text Restricts the test to the text preceding the caret.
selection_empty Returns true if the selection is an empty region.
setting.x Returns the value of the x setting. x can be any string.
text Restricts the test to the selected text.
selector Returns the current scope.
Context Operators

equal, not_equal Test for equality.

regex_match, not_regex_match Match against a regular expression.
regex_contains, not_regex_contains Match against a regular expression (containment).

11.4.2 Command Mode

Sublime Text provides a command_mode setting to prevent key presses from being sent to the buffer. This is useful
to emulate Vims modal behavior.

11.4.3 Bindable Keys

Keys may be specified literally or by name. Below youll find the list of valid names:
up
down
right
left

11.4. Key Bindings

57

Sublime Text Unofficial Documentation, Release 2.0

insert
home
end
pageup
pagedown
backspace
delete
tab
enter
pause
escape
space
keypad0
keypad1
keypad2
keypad3
keypad4
keypad5
keypad6
keypad7
keypad8
keypad9
keypad_period
keypad_divide
keypad_multiply
keypad_minus
keypad_plus
keypad_enter
clear
f1
f2
f3
f4
f5
f6
f7

58

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

f8
f9
f10
f11
f12
f13
f14
f15
f16
f17
f18
f19
f20
sysreq
break
context_menu
browser_back
browser_forward
browser_refresh
browser_stop
browser_search
browser_favorites
browser_home
Modifiers
shift
ctrl
alt
super (Windows key, Command key. . . )
Warning about Bindable Keys
If youre developing a package, keep this in mind:
Ctrl+Alt+<alphanum> should not be used on any Windows key bindings.
Option+<alphanum> should not be used on any OS X key bindings.
In both cases, the users ability to insert non-ascii characters would be compromised.
If you are the end-user, you are free to remap those key combinations.

11.4. Key Bindings

59

Sublime Text Unofficial Documentation, Release 2.0

11.4.4 Keeping Key Maps Organized

Sublime Text ships with default key maps under Packages/Default. Other packages may include their own key
map files. The recommended storage location for your personal key map is Packages/User.
See Merging and Order of Precedence for information about how Sublime Text sorts files for merging.

11.4.5 International Keyboards

Due to the way Sublime Text maps key names to physical keys, there might be a mismatch between the two.

11.4.6 Troubleshooting
See sublime.log_commands(flag) to enable command logging. It may help when debugging key maps.

11.5 Settings (Reference)

11.5.1 Global Settings
Target file: Global.sublime-settings.
theme Theme to be used. Accepts a file base name (e. g.: Default.sublime-theme).
remember_open_files Determines whether to reopen the buffers that were open when Sublime Text was last
closed.
folder_exclude_patterns Excludes the matching folders from the side bar, GoTo Anything, etc.
file_exclude_patterns Excludes the matching files from the side bar, GoTo Anything, etc.
scroll_speed Set to 0 to disable smooth scrolling. Set to a value between 0 and 1 to scroll slower, or set to a
value larger than 1 to scroll faster.
show_tab_close_buttons If false, hides the tabs close buttons until the mouse is hovered over the tab.
mouse_wheel_switches_tabs If true, scrolling the mouse wheel will cause tabs to switch if the cursor is in
the tab area.
open_files_in_new_window OS X only. When filters are opened from Finder, or by dragging onto the dock
icon, this controls if a new window is created or not.

11.5.2 File Settings

Target files: Base File.sublime-settings, <file_type>.sublime-settings.
Whitespace and Indentation
auto_indent Toggles automatic indentation.
tab_size Number of spaces a tab is considered to be equal to.
translate_tabs_to_spaces Determines whether to replace a tab character with tab_size number of spaces
when Tab is pressed.

60

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

use_tab_stops If translate_tabs_to_spaces is true, will make Tab and Backspace insert/delete

tab_size number of spaces per key press.
trim_automatic_white_space Toggles deletion of white space added by auto_indent.
detect_indentation Set to false to disable detection of tabs vs. spaces whenever a buffer is loaded. If set to
true, it will automatically modify translate_tabs_to_spaces and tab_size.
draw_white_space Valid values: none, selection, all.
trim_trailing_white_space_on_save Set to true to remove white space on save.
Visual Settings
color_scheme Sets the colors used for text highlighting. Accepts a path rooted at the data directory (e. g.:
Packages/Color Scheme - Default/Monokai Bright.tmTheme).
font_face Font face to be used for editable text.
font_size Size of the font for editable text.
font_options Valid
values:
bold,
italic,
subpixel_antialias, directwrite (Windows).

no_antialias,

gray_antialias,

gutter Toggles display of gutter.

rulers Columns in which to display vertical rules. Accepts a list of numeric values (e. g. [79, 89, 99] or a
single numeric value (e. g. 79).
draw_minimap_border Set to true to draw a border around the minimaps region corresponding to the the
views currently visible text. The active color schemes minimapBorder key controls the borders color.
highlight_line Set to false to stop highlighting lines with a cursor.
line_padding_top Additional spacing at the top of each line, in pixels.
line_padding_bottom Additional spacing at the bottom of each line, in pixels.
scroll_past_end Set to false to disable scrolling past the end of the buffer. If true, Sublime Text will leave
a wide, empty margin between the last line and the bottom of the window.
line_numbers Toggles display of line numbers in the gutter.
word_wrap If set to false, long lines will be clipped instead of wrapped. Scroll the screen horizontally to see the
clipped text.
wrap_width If greater than 0, wraps long lines at the specified column as opposed to the window width. Only takes
effect if wrap_width is set to true.
indent_subsequent_lines If set to false, wrapped lines will not be indented.
wrap_width is set to true.

Only takes effect if

draw_centered If set to true, text will be drawn centered rather than left-aligned.
match_brackets Set to false to disable underlining the brackets surrounding the cursor.
match_brackets_content Set to false is youd rather only highlight the brackets when the cursor is next to
one.
match_brackets_square Set to false to stop highlighting square brackets.
match_brackets is true.

Only takes effect if

match_bracktets_braces Set to false to stop highlighting curly brackets.

match_brackets is true.

Only takes effect if

11.5. Settings (Reference)

61

Sublime Text Unofficial Documentation, Release 2.0

match_bracktets_angle Set to false to stop highlighting angle brackets.

match_brackets is true.

Only takes effect if

Automatic Behavior
auto_match_enabled Toggles automatic pairing of quotes, brackets, etc.
save_on_focus_lost Set to true to automatically save files when switching to a different file or application.
find_selected_text If true, the selected text will be copied into the find panel when its shown.
word_separators Characters considered to separate words in actions like advancing the cursor, etc. They are not
used in all contexts where a notion of a word separator is useful (e. g.: word wrapping). In such other contexts,
the text might be tokenized based on other criteria (e. g. the syntax definition rules).
ensure_newline_at_eof_on_save Always adds a new line at the end of the file if not present when saving.
System and Miscellaneous Settings
is_widget Returns true if the buffer is an input field in a dialog as opposed to a regular buffer.
spell_check Toggles the spell checker.
dictionary Word list to be used by the spell checker. Accepts a path rooted at the data directory (e. g.:
Packages/Language - English/en_US.dic). You can add more dictionaries.
fallback_encoding The encoding to use when the encoding cant be determined automatically. ASCII, UTF-8
and UTF-16 encodings will be automatically detected.
default_line_ending Determines what characters to use to designate new lines. Valid values: system (OSdependant), windows (CRLF) and unix (LF).
tab_completion Determines whether pressing Tab will insert completions.
Build and Error Navigation Settings
result_file_regex Regular expression used to extract error information from some output dumped into a view
or output panel. Follows the same rules as error capturing in build systems.
result_line_regex Regular expression used to extract error information from some output dumped into a view
or output panel. Follows the same rules as error capturing in build systems.
result_base_dir Directory to start looking for offending files in based on information extracted with
result_file_regex and result_line_regex.
build_env List of paths to add to build systems by default.
File and Directory Settings
default_dir Sets the default save directory for the view.
Input Settings
command_mode If set to true, the buffer will ignore key strokes. Useful to emulate Vim.

62

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

11.6 Command Palette

The command palette is fed entries with .sublime-commands files.

11.6.1 File Format (.sublime-commands Files)

Heres an excerpt from Packages/Default/Default.sublime-commands:
[
{ "caption": "Project: Save As", "command": "save_project_as" },
{ "caption": "Project: Close", "command": "close_project" },
{ "caption": "Project: Add Folder", "command": "prompt_add_folder" },
{
{
{
{
{

"caption":
"caption":
"caption":
"caption":
"caption":

"Preferences:
"Preferences:
"Preferences:
"Preferences:
"Preferences:

Default File Settings", "command": "open_file", "args": {"file": "${pa

User File Settings", "command": "open_file", "args": {"file": "${packa
Default Global Settings", "command": "open_file", "args": {"file": "${
User Global Settings", "command": "open_file", "args": {"file": "${pac
Browse Packages", "command": "open_dir", "args": {"dir": "$packages"}

caption Text for display in the command palette.

command Command to be executed.
args Arguments to pass to command. Note that to locate the packages folder you need to use a snippet-like variable:
${packages} or $packages. This different to other areas of the editor due to different implementations of the
lower level layers.

11.6.2 How to Use the Command Palette

1. Press Ctrl+Shift+P
2. Select command
Entries are filtered by current context. Not all entries will be visible at all times.

11.7 Completions
Completions provide an IDE-like functionality to insert dynamic content through the completions list or by pressing
Tab.

11.7.1 File Format

Completions are JSON files with the .sublime-completions extension.

11.7.2 Structure of a Completions List

scope Determines whether the completions are to be sourced from this file. See Scopes for more information.
completions Array of completions.
Heres an excerpt from the html completions:

11.6. Command Palette

63

Sublime Text Unofficial Documentation, Release 2.0

{
"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",
"completions":
[
{ "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
{ "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
]
}

11.7.3 Types of Completions

Plain Strings
Plain strings are equivalent to an entry where the trigger is identical to the contents:
"foo"
# is equivalent to:
{ "trigger": "foo", "contents": "foo" }

Trigger-based Completions
trigger Text that will be displayed in the completions list and will cause the contents to be inserted when
validated.
contents Text to be inserted in the buffer. Can use snippet features.

11.7.4 Sources for Completions

These are the sources for completions the user can control:
.sublime-completions
EventListener.on_query_completions()
Additionally, other completions are folded into the final list:
Snippets
Words in the buffer
Priority of Sources for Completions
Snippets
API-injected completions
.sublime-completions files
Words in buffer
Snippets will only be automatically completed against an exact match of their tab trigger. Other sources for completions are filtered with a case insensitve fuzzy search instead.
64

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

11.7.5 The Completions List

To use the completions list:
Press Ctrl+spacebar to open
Optionally, press Ctrl+spacebar again to select next entry
Press Enter or Tab to validate selection
Note: The current selection in the completions list can actually be validated with any punctuation sign that isnt itself
bound to a snippet.
Snippets show up in the completions list following the pattern: <tab_trigger> :
completions, you will just see the text to be inserted.

<name>. For the other

If the list of completions can be narrowed down to one choice, the autocomplete dialog will be bypassed and the
corresponding content will be inserted straight away according to the priority rules stated above.

11.7.6 Enabling and Disabling Tab Completion for Completions

The tab_completion setting is true by default. Set it to false if you want Tab to stop sourcing the most likely
completion. This setting has no effect on triggers defined in .sublime-snippet files, so snippets will always be
inserted after a Tab.
With tab_completion on, The same order of priority as stated above applies, but, unlike in the case of the completions list, Sublime Text will always insert a completion, even if faced with an ambiguous choice.
Inserting a Literal Tab
If tab_completion is true, you can press Shift+Tab after a prefix to insert a literal tab character.

11.8 Plugins
See Also:
API Reference More information on the Python API.
Plugins are Python scripts implementing *Command classes from sublime_plugin.

11.8.1 Where to Store Plugins

Sublime Text 2 will look for plugins in these places:
Packages
Packages/<pkg_name>
Any plugin nested deeper in Packages wont be loaded.
All plugins should live inside a directory of their own and not directly under Packages.

11.8. Plugins

65

Sublime Text Unofficial Documentation, Release 2.0

11.8.2 Conventions for Command Names

Sublime Text 2 command class names are suffixed by convention with Command and written as
CamelCasedPhrases.
However, Sublime Text 2 transforms the class name from CamelCasedPhrases to camel_cased_phrases.
So ExampleCommand would turn into example and AnotherExampleCommand would turn into
another_example.
For class definition names, use CamelCasedPhrasesCommand; to call a command from the API, use the normalized name (camel_cased_phrases).

11.8.3 Types of Commands

sublime_plugin.ApplicationCommand
sublime_plugin.WindowCommand
sublime_plugin.TextCommand
sublime_plugin.EventListener
Instances of WindowCommand have a .window attribute pointing to the window instance that created them. Similarly, instances of TextCommand have a .view attribute.
Shared Traits for Commands
All commands must implement a .run() method. All commands can receive and arbitrarily long number of keyword
arguments, but they must be valid JSON types.

11.8.4 How to Call Commands from the API

Use a reference to a View or a Window, or sublime depending on the type of command, and call
object.run_command(command_name). In addition, you can pass a dictionary where keys are names of
parameters to command_name.
window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})

Command Arguments
*****************
All user-provided arguments to commands must be valid JSON types. Only
Sublime Text can pass other types of arguments to commands (such as edit
objects, view instances, etc.).

11.8.5 Text Commands and the edit Object

The two API functions of interest are view.begin_edit(), which takes an optional command name and an
optional dictionary of arguments, and view.end_edit(), which finishes the edit.
All actions done within an edit are grouped as a single undo action. Callbacks such as on_modified() and
on_selection_modified() are called when the edit is finished.

66

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

Its important to call view.end_edit() after each view.begin_edit(), otherwise the buffer will be in an
inconsistent state. An attempt will be made to fix it automatically if the edit object gets collected, but that often
doesnt happen when you expect, and will result in a warning printed to the console. In other words, you should
always bracket an edit in a try..finally block.
The command name passed to begin_edit() is used for repeat, macro recording, and for describing the action
when undoing/redoing it. If youre making an edit outside of a TextCommand, you should almost never supply a
command name.
If you have created an edit object, and call a function that creates another one, thats fine: the edit is only considered
finished when the outermost call to end_edit() runs.
As well as grouping modifications, you can use edit objects for grouping changes to the selection, so theyre undone
in a single step.

11.8.6 Responding to Events

Any subclass of EventListener will be able to respond to events. You cannot make a class derive from both
EventListener and any other type of command.
A Word of Warning about EventListener
Expensive operations in event listeners can cause Sublime Text 2 to become unresponsive, especially in events
triggered frequently, like on_modified and on_selection_modified. Be careful of how much work is
done in those and do not implement events you dont need, even if they just pass.

11.8.7 Python and the Standard Library

Sublime Text ships with a trimmed down standard library. Notable missing modules are the Tkinter, multiprocessing
and sqlite3 modules.

11.8.8 Automatic Plugin Reload

Sublime Text will automatically reload top-level Python modules from packages as they change (perhaps because you
are editing a .py file). Note that Python subpackages wont be reloaded; this can lead to confusion while developing
plugins. Generally, its best to restart Sublime Text after youve made changes to plugin files so all changes take effect.

11.8.9 Multithreading
Only the .set_timeout() function is safe to call from different threads.

11.9 Python API

See Also:
Official Documentation API documentation.

11.9. Python API

67

Sublime Text Unofficial Documentation, Release 2.0

11.9.1 Exploring the API

A quick way to see the API in action:
1. Add Packages\Default (Preferences | Browse Packages. . . ) to your project.
2. CTRL + SHIFT + F
3. Enter *.py in the In Files: field
4. Check Use Buffer option
5. Search API name
6. F4
7. Study relevant source code

11.10 Commands
11.10.1 Overview
This list of commands is a work in progress.

11.10.2 About Paths in Command Arguments

Some commands take paths as parameters. Among these, some support snippet-like syntax, while others dont. A
command of the first kind would take a parameter like ${packages}/SomeDir/SomeFile.Ext whereas a command of the
second kind would take a parameter like Packages/SomeDir/SomeFile.Ext.
Generally, newer commands support the snippet-like syntax.
Often, relative paths in arguments to commands are assumed to start at the Data directory.
Variables in Paths as Arguments
The same variables available to build systems are expanded in arguments to commands. See Build System Variables
for more information.

11.10.3 Commands
build Runs a build system.
variant [String]: Optional. The name of the variant to be run.
run_macro_file Runs a .sublime-macro file.
file [String]: Path to the macro file.
insert_snippet Inserts a snippet from a string or .sublime-snippet file.
contents [String]: Snippet as a string to be inserted.
name [String]: Path to the .sublime-snippet file to be inserted.
insert Inserts a string.
characters [String]: String to be inserted.

68

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

move Advances the caret by predefined units.

by [Enum]: Values: characters, words, word_ends, subwords, subword_ends, lines, pages, stops.
forward [Bool]: Whether to advance or reverse in the buffer.
word_begin [Bool]
empty_line [Bool]
punct_begin [Bool]
separators [Bool]
move_to Advances the caret to predefined locations.
to [Enum]: Values: bol, eol, bof, eof, brackets.
extend [Bool]: Whether to extend the selection. Defaults to false.
new_window Opens a new window.
close_window Closes the active window.
switch_file Switches between two files with the same name and different extensions.
extensions [[String]]: Extensions (without leading dot) for which switching will be enabled.
close Closes the active view.
close_file Closes the active view and, under certain circumsances, the whole application. XXX Sounds kinda wrong.
toggle_sidebar Shows or hides the sidebar.
toggle_full_screen Toggles full screen mode on or off.
toggle_distraction_free Toggles distraction free mode on or off.
left_delete Deletes the character right before the caret.
right_delete Deletes the character right after the caret.
undo Undoes the latest action.
redo Reapplies the latest undone action.
redo_or_repeat Performs the latest action again.
soft_undo Undoes each action stepping through granular edits.
soft_redo Redoes each action stepping through granular edits.
cut Removes the selected text and sends it to the system clipboard. Put differently, it cuts.
copy Sends the selected text to to the system clipboard.
paste Inserts the clipboard contents after the caret.
paste_and_indent Inserts the clipboard contents after the caret and indents contextually.
select_lines Adds a line to the current selection.
forward [Bool]: Whether to add the next or previous line. Defaults to true.
scroll_lines Scrolls lines in the view.
amount [Float]: Positive values scroll lines down and negative values scroll lines up.
prev_view Switches to the previous view.
next_view Switches to the next view.

11.10. Commands

69

Sublime Text Unofficial Documentation, Release 2.0

next_view_in_stack Switches to the most recently active view.

previous_view_in_stack Switches to the view that was active before the most recently active view. I dont think this
is very clear or even true.
select_all Select the views content.
split_selection_into_lines Unsurprisingly, it splits the selection into lines.
single_selection Collapses multiple selections into a single selection.
clear_fields Breaks out of the active snippet field cycle.
hide_panel Hides the active panel.
cancel [Bool]: Notifies the panel to restore the selection to what it
was when the panel was opened. (Only incremental find panel.)
hide_overlay Hides the active overlay. Show the overlay using the show_overlay command.
hide_auto_complete Hides the auto complete list.
insert_best_completion Inserts the best completion that can be inferred from the current context. XXX Probably
useless. XXX
default [String]: String to insert failing a best completion.
replace_completion_with_next_completion XXX Useless for users. XXX
reindent XXX ??? XXX
indent Increments indentation.
next_field Advances the caret to the text snippet field in the current snippet field cycle.
prev_field Moves the caret to the previous snippet field in the current snippet field cycle.
commit_completion Inserts into the buffer the item thats currently selected in the auto complete list. XXX Probably
not useful for users. XXX
unindent Unindents.
toggle_overwrite Toggles overwriting on or off.
expand_selection Extends the selection up to predifined limits.
to [Enum]: Values: bol, hardbol, eol, hardeol, bof, eof, brackets, line.
find_under_expand Adds a new selection based on the current selection or expands the selection to the current word.
close_tag Surrounds the current inner text with the appropiate tags.
toggle_record_macro Starts or stops the macro recorder.
run_macro Runs the macro stored in the macro buffer.
show_overlay Shows the requested overlay. Use the hide_overlay command to hide it.
overlay [Enum]: The type of overlay to show. Possible values:
goto: Show the Goto Anything overlay.
command_palette: Show the command palette.
show_files [Bool]: If using the goto overlay, start by displaying files rather than an empty widget.
text [String]: The initial contents to put in the overlay.
show_panel Shows a panel.

70

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

panel [Enum]: Values: incremental_find, find, replace, find_in_files, console

reverse [Bool]: Whether to search backwards in the buffer.
toggle [Bool]: Whether to hide the panel if its already visible.
find_next Finds the next occurrence of the current search term.
find_prev Finds the previous occurrence of the current search term.
find_under Finds the next occurrence of the current selection or the current word.
find_under_prev Finds the previous occurrence of the current selection or the current word.
find_all_under Finds all occurrences of the current selection or the current word.
slurp_find_string Copies the current selection or word into the find field of the find panel.
slurp_replace_string Copies the current selection or word into the replace field of the find and replace panel.
next_result Advance to the next captured result.
prev_result Move to the previous captured result.
toggle_setting Toggles the value of a boolean setting.
setting [String]: The name of the setting to be toggled.
next_misspelling Advance to the next misspelling
prev_misspelling Move to the previous misspelling.
swap_line_down Swaps the current line with the line below.
swap_line_up Swaps the current line with the line above.
toggle_comment Comments or uncomments the active lines.
block [Bool]: Whether to use a block comment.
join_lines Joins the current line with the next one.
duplicate_line Duplicates the current line.
auto_complete Opens the auto comeplete list.
replace_completion_with_auto_complete XXX Useless for users. XXX
show_scope_name Shows the name for the carets scope in the status bar.
exec Runs an external process asynchronously.
XXX Document all options.
transpose Makes stuff dance.
sort_lines Sorts lines.
case_sensitive [Bool]: Whether the sort should be case sensitive.
set_layout XXX
focus_group XXX
move_to_group XXX
select_by_index XXX
next_bookmark Select the next bookmarked region.
prev_bookmark Select the previous bookmarked region.

11.10. Commands

71

Sublime Text Unofficial Documentation, Release 2.0

toggle_bookmark Sets or unsets a bookmark for the active region(s). (Bookmarks can be accessed via the regions
API using "bookmarks" as the key.)
clear_bookmarks Removes all bookmarks.
select_all_bookmarks Selects all bookmarked regions.
wrap_lines Wraps lines. By default, it wraps lines at the first rulers column.
width [Int]: Specifies the column at which lines should be wrapped.
upper_case Makes the selection upper case.
lower_case Makes the selection lower case.
set_mark XXX
select_to_mark XXX
delete_to_mark XXX
swap_with_mark XXX
yank XXX
show_at_center XXX
increase_font_size Increases the font size.
decrease_font_size Decreases the font size.
fold XXX
unfold XXX
fold_by_level XXX
context_menu Shows the context menu.

11.11 Keyboard Shortcuts - Windows/Linux

Warning: This topic is a draft and may contain wrong information.

72

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

11.11.1 Editing
Keypress
Ctrl + X
Ctrl +
Ctrl + +
Ctrl + +
Ctrl + +
Ctrl + L
Ctrl + D
Ctrl + M
Ctrl + + M
Ctrl + KK
Ctrl + K +
Ctrl + ]
Ctrl + [
Ctrl + + D
Ctrl + J
Ctrl + /
Ctrl + + /
Ctrl + Y
Ctrl + + V
Ctrl + Space
Ctrl + U

Command
Delete line
Insert line after
Insert line before
Move line/selection up
Move line/selection down
Select line - Repeat to select next lines
Select word - Repeat select others occurrences
Jump to closing parentheses Repeat to jump to opening parentheses
Select all contents of the current parentheses
Delete from cursor to end of line
Delete from cursor to start of line
Indent current line(s)
Un-indent current line(s)
Duplicate line(s)
Join line below to the end of the current line
Comment/un-comment current line
Block comment current selection
Redo, or repeat last keyboard shortcut command
Paste and indent correctly
Select next auto-complete suggestion
soft undo; jumps to your last change before undoing change when repeated

11.11.2 Navigation/Goto Anywhere

Keypress
Ctrl + P
Ctrl + R
Ctrl + ;
Ctrl + G

Command
Quick-open files by name
Goto symbol
Goto word in current file
Goto line in current file

11.11.3 General
Keypress
Ctrl + + P
Ctrl + KB
Ctrl + + Alt + P

Command
Command prompt
Toggle side bar
Show scope in status bar

11.11.4 Find/Replace
Keypress
Ctrl + F
Ctrl + H
Ctrl + + F

Command
Find
Replace
Find in files

11.11. Keyboard Shortcuts - Windows/Linux

73

Sublime Text Unofficial Documentation, Release 2.0

11.11.5 Tabs
Keypress
Ctrl + + t
Ctrl + PgUp
Ctrl + PgDn
Ctrl +
Alt + [NUM]

Command
Open last closed tab
Cycle up through tabs
Cycle down through tabs
Find in files
Switch to tab number [NUM] where [NUM] <= number of tabs

11.11.6 Split window

Keypress
Alt + + 2
Alt + + 1
Alt + + 5
Ctrl + [NUM]
Ctrl + + [NUM]

Command
Split view into two columns
Revert view to single column
Set view to grid (4 groups)
Jump to group where num is 1-4
Move file to specified group where num is 1-4

11.11.7 Bookmarks
Keypress
Ctrl + F2
F2
+ F2
Ctrl + + F2

Command
Toggle bookmark
Next bookmark
Previous bookmark
Clear bookmarks

11.11.8 Text manipulation

Keypress
Ctrl + KU
Ctrl + KL

Command
Transform to Uppercase
Transform to Lowercase

11.12 Keyboard Shortcuts - OSX

Warning: This topic is a draft and may contain wrong information.

74

Chapter 11. Reference

Sublime Text Unofficial Documentation, Release 2.0

11.12.1 Editing
Keypress
+X
+
+ +
+ +
+ +
+L
+D
+M
+ +M
+ K, + K
+K+
+]
+[
+ +D
+/
+ +/
+Y
+ +V
+ Space
+U

Command
Delete line
Insert line after
Insert line before
Move line/selection up
Move line/selection down
Select line - Repeat to select next lines
Select word - Repeat select others occurrences
Jump to closing parentheses Repeat to jump to opening parentheses
Select all contents of the current parentheses
Delete from cursor to end of line
Delete from cursor to start of line
Indent current line(s)
Un-indent current line(s)
Duplicate line(s)
Join line below to the end of the current line
Comment/un-comment current line
Block comment current selection
Redo, or repeat last keyboard shortcut command
Paste and indent correctly
Select next auto-complete suggestion
soft undo; jumps to your last change before undoing change when repeated

11.12.2 Navigation/Goto Anywhere

Keypress
+P
+R
+G

Command
Quick-open files by name
Goto symbol
Goto word in current file
Goto line in current file

11.12.3 General
Keypress
+ +P
+ K, + B
+ +P

Command
Command prompt
Toggle side bar
Show scope in status bar

11.12.4 Find/Replace
Keypress
+F
+ +F

Command
Find
Replace
Find in files

11.12. Keyboard Shortcuts - OSX

75

Sublime Text Unofficial Documentation, Release 2.0

11.12.5 Tabs
Keypress
+ +t

Command
Open last closed tab
Cycle up through tabs
Cycle down through tabs
Find in files

11.12.6 Split window

Keypress
+ +2
+ +1
+ +5
+ [NUM]
+ + [NUM]

Command
Split view into two columns
Revert view to single column
Set view to grid (4 groups)
Jump to group where num is 1-4
Move file to specified group where num is 1-4

11.12.7 Bookmarks
Keypress
+ F2
F2
+ F2
+ + F2

Command
Toggle bookmark
Next bookmark
Previous bookmark
Clear bookmarks

11.12.8 Text manipulation

Keypress
+ K, + U
+ K, + L

76

Command
Transform to Uppercase
Transform to Lowercase

Chapter 11. Reference

CHAPTER

TWELVE

GLOSSARY
buffer Data of a loaded file and additional metadata. Associated with one or more views. The distinction between
buffer and view is technical. Most of the time, both terms can be used interchangeably.
view Graphical display of a buffer. Multiple views can show the same buffer.
plugin A feature impemented in Python. It can consist of a single command or multiple commands. It can be
contained in one .py file or many .py files.
package This term in ambiguous in the context of Sublime Text, because it can refer to a Python package (unlikely), a
directory inside Packages or a .sublime-package file. Most of the time, it means a directory inside Packages
containing resources that belong together to build a new feature or provide support for a programming or markup
language.
panel An input/output widget such as a search panel or the output panel.
overlay An input widget of a special kind. Goto Anything is an overlay.

77