Usage

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.

Startup actions

When SublimeLinter is loaded by Sublime Text 3, it performs a number of actions to initialize its environment:

Settings

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.

Color scheme

SublimeLinter has to convert color schemes for its use. For more information, see Choosing color schemes.

Customized syntax definitions

SublimeLinter supports linting of embedded syntaxes, such as JavaScript and CSS within an HTML file, by specifying a scope to which the linter is limited. Unfortunately the stock syntax definitions that ship with Sublime Text 3 incorrectly classify the scope of embedded languages, which leads to false errors during linting. To solve this problem, at load time SublimeLinter installs fixed versions of the HTML and HTML (Rails) syntax packages in the Packages directory.

Note

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.

Assigning linters

When a file is opened in Sublime Text 3, SublimeLinter checks the syntax assigned to the file (Python, JavaScript, etc.), and then uses that name (lowercased) to locate any linters (there may be several) that have advertised they can lint that syntax. Any found linters are assigned to that view of the file. SublimeLinter assigns separate linter instances to each view, even if there are multiple views of the same file.

Linting

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.

    For more information on lint modes, see Lint Modes. The delay can be configured, for more information see Global Settings.

  • 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 bash, zsh, or 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:

/bin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/php/bin:/usr/local/php5/bin

Warning

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.

Python paths

When locating python and python scripts such as flake8, SublimeLinter goes through a special process. For more information, see the @python meta setting.

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.

Toggling linters

You can quickly toggle a linter on or off. To do so:

  1. Bring up the Command Palette (cmd+shift+p on Mac OS X, ctrl+shift+p on Linux/Windows) and type toggle, disable, or enable according to what you want to view all linters, only enabled linters, or only disabled linters.
  2. Among the commands you should see SublimeLinter: Toggle Linter, SublimeLinter: Disable Linter or SublimeLinter: Enable Linter, depending on what you typed. If the command is not highlighted, use the keyboard or mouse to select it.
  3. 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.
  4. 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.

Warning

If you choose an unconverted color scheme and an existing converted color scheme exists in Packages/User/SublimeLinter, it will be overwritten.

Note

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.

User interface

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.