SublimeLinter is designed to work well out of the box, but there are many ways to customize it to your taste. Before we get to that, though, let’s take a look at how SublimeLinter works.
When SublimeLinter is loaded by Sublime Text 3, it performs a number of actions to initialize its environment:
The default settings are loaded from the plugin and merged with the settings in
Packages/User/SublimeLinter.sublime-settings. For more information on SublimeLinter settings, see Settings.
SublimeLinter has to convert color schemes for its use. For more information, see Choosing color schemes.
Customized syntax definitions¶
HTML (Rails) syntax packages in the
The first time the fixed syntaxes are installed, you may need to restart Sublime Text 3 for them to be applied to source files in those syntaxes.
Here’s where the magic happens.
When you activate or make any modifications to a file, the following sequence of events occurs:
SublimeLinter checks to see if the syntax of the file has changed; and if so, reassigns linters to the view.
If the lint mode is
background, a lint request is added to a threaded queue with a delay. The delay is there to prevent lints from occurring instantly on every keystroke — you don’t want the linter complaining too much while you are typing, it quickly becomes annoying. The delay is there to allow a little idle time before a lint occurs.
The lint request is eventually pulled off the queue after the given delay. If the view it belongs to has been modified since the lint request was made, the request is discarded, since another lint request was generated when the view was modified.
Each of the linters assigned to the base syntax of the view is run with the current text of the view. The linter calls an external linter binary (such as jshint), or if the linter is python-based (such as flake8), it may directly call a python linting library.
If any linters assigned to the view support embedded code and that embedded code is found, the linters are run with the appropriate embedded code.
Each linter adds a set of regions indicating the portions of the source code that generated errors or warnings.
When all of the linters have finished, if the view has still not been modified since the initial lint request, all of the error and warning regions are aggregated and drawn according to the currently configured mark style and gutter theme. Errors and warnings are marked with separate colors and gutter icons to make it easy to see which is which.
How linter executables are located¶
When calling a system linter binary, the user’s
PATH environment variable is used to locate the binary. On Windows, the
PATH environment variable is used as is. On Mac OS X and Linux, if the user’s shell is
fish, a login shell is used to get the
PATH value. If you are using a shell other than the ones just mentioned,
PATH effectively becomes:
On Mac OS X and Linux, special care must be taken to ensure your
PATH is set up in such a way that SublimeLinter can read it. For more information, see Debugging PATH problems.
In addition to the
PATH SublimeLinter reads from the system, any directories in the global
"paths" setting for the current platform are searched when attempting to locate a binary. For more information, see the Global Settings documentation.
Disabling all linters¶
There may be times when you want to turn off all linting. To do so, bring up the Command Palette and type
disable. Among the commands you should see
SublimeLinter: Disable Linting. If that command is not highlighted, use the keyboard or mouse to select it.
Once you do this, all linters are disabled and all error marks are cleared from all views. To re-enable linting, follow the same steps as above, but select
SublimeLinter: Don’t Disable Linting. Note that this does not enable all linters; if you have disabled individual linters in the settings, they will remain disabled.
You can quickly toggle a linter on or off. To do so:
- Bring up the Command Palette (
cmd+shift+pon Mac OS X,
ctrl+shift+pon Linux/Windows) and type
enableaccording to what you want to view all linters, only enabled linters, or only disabled linters.
- Among the commands you should see
SublimeLinter: Toggle Linter,
SublimeLinter: Disable Linteror
SublimeLinter: Enable Linter, depending on what you typed. If the command is not highlighted, use the keyboard or mouse to select it.
- Once you select the command, a list of the relevant linters appears. If you chose
SublimeLinter: Disable Linter, only the enabled linters appear in the list. If you chose
SublimeLinter: Enable Linter, only the disabled linters appear.
- Select a linter from the list. It will be toggled, disabled or enabled, depending on the command you chose.
Choosing color schemes¶
In order to color errors, warnings and gutter icons correctly, SublimeLinter relies on specific named colors being available in the current color scheme. Whenever a color scheme is loaded — either implicitly at startup or by selecting a color scheme — SublimeLinter checks to see if the color scheme contains its named colors. If not, it adds those colors to a copy of the color scheme, writes it to the
Packages/User/SublimeLinter directory with a “ (SL)” suffix added to the filename, and switches to the modified color scheme.
For example, if you select
Preferences > Color Scheme > Color Scheme - Default > Monokai, SublimeLinter will convert it, write the converted color scheme to
Packages/User/SublimeLinter/Monokai (SL).tmTheme, and switch to that color scheme. If you then open the
Preferences > Color Scheme menu,
User > SublimeLinter > Monokai (SL) is checked.
If you choose an unconverted color scheme and an existing converted color scheme exists in
Packages/User/SublimeLinter, it will be overwritten.
If you ever want to clean up, and delete all the SublimeLinter made color schemes not being used in the settings, simply use the
SublimeLinter: Clear Color Scheme Folder command from the Command Pallete, Tools menus, or Context menu.
For more information on customizing the colors used by SublimeLinter, see Global Settings.
There are four main aspects to the SublimeLinter user interface:
- Lint mode — The lint mode determines when linting occurs.
- Mark style — The mark style determines how errors are marked in the text.
- Gutter theme — The gutter theme determines how lines with errors are marked in the gutter.
- Navigating errors — Once linters find errors in your code, you can quickly and easily navigate through them.