Installation

Sublime Six is implemented as a Python plugin without any external dependencies.

The easiest way to install Six is through Package Control, a package manager for Sublime Text.

To install Six, look for the Six package in Package Control and install it.

After installing Six, restart Sublime Text. Six should then load and enter normal mode.

Channels

Six is available through two channels: stable and dev.

After installing Six, you are automatically subscribed to the stable channel.

Stable builds are published less often than dev builds, but in exchange they tend to be more stable.

All builds are regularly tested on Linux, macOS and Windows.

If you want to use the dev channel, you need to open your Package Control settings (located in Packages/User) and add the following line:

"install_prereleases": ["Six"]

Uninstallation

If you want to uninstall Six, use the corresponding Package Control command or delete Packages/Six.

Disabling Six for Selected Views

Some Sublime Text plug-ins may not interact well with Six. This is specially true for plug-ins that use command mode to implement Vim-style navigation with regular keys (for example, k and j to move up and down). In such cases, it’s possible to selectively disable Six for some views.

To disable Six for a given view, set any of the following view settings to true:

  • __vi_external_disable
  • __vi_external_disable_keys

Both settings currently have the same effect: Six will not be available in the corresponding view (key presses will not be intercepted).

This configuration should normally be made by the affected plug-in.

Differences with Vim

Six strives to be as close to Vim as the Sublime Text API permits.

Generally speaking, the Vim documentation should apply equally to Six and Vim as far as operators and motions are concerned. Motions and operators in Six aim to be 100% ports of Vim’s.

Six does not currently implement every single Vim feature, but is designed to eventually become a comprehensive port.

The current focus of Six is normal mode, visual and visual line modes, and a subset of command-line mode.

Additionally, Six implements modes and features that let you take advantage of unique Sublime Text features, like multiple selections, while keeping in with Vim principles.

Non-standard Commands

Non-standard commands generally exist to enable better interoperability with key Sublime Text features.

List of Six commands that are not standard Vim commands:

Command Context Description
ctrl+j autocomplete list next item
ctrl+k autocompoete list previous item
ctrl+q normal mode open Go To Symbol
ctrl+shift+q normal mode open Go To Symbol in Project

Non-standard Modes

Non-standard modes generally exist to enable better interoperability with key Sublime Text features.

Six includes two non-standard modes with which you can take advantage of Sublime Text’s multiple selections.

Multiple Selection Mode

Using the Multiple Selection Mode, you can add selections based on the word under the caret.

Commands available in Multiple Selection Mode:

Command Action
gh Enter Multiple Selection Mode
j Add selection
k Remove selection
l Skip selection
J Add all selections
i Enter Insert Mode
Esc Enter Normal Mode

You cannot operate on text while in Multile Selection Mode. Before operating on text, switch to insert mode or to normal mode.

Multiple Line Selection Mode

Using the Multiple Line Selection Mode, you can add lines.

Commands available in Multiple Line Selection Mode:

Command Action
gH Enter Multiple Line Selection Mode
j Add selection down
k Add selection up
i Enter Insert Mode
Esc Enter Normal Mode

You cannot operate on text while in Multile Line Selection Mode. Before operating on text, switch to insert mode or to normal mode.

Regular Expressions

Six uses the same regular expressions’ engine and synxtax for searches as Sublime Text.

The Vim regexp language is currently not supported.

Settings and Configuration

Currently, you can configure Six using two methods: a Sublime Six settings file, and an initialization script. Both methods can be used at the same time.

Configuring Six with a Sublime Settings File

To configure Six, select Preferences: Six Settings from Sublime Text’s command palette. Two files will open side by side. You can check the meaning of individual settings in the file on the left-hand side, but do only edit settings in the file on the right-hand side.

Only settings stored in the User/Six.sublime-settings file get saved. Settings stored in Six/Six.sublime-settings will be overwritten with every update to Six.

Configuring Six with an Initialization Script

You can create a User/sixrc.py file to customize some aspects of Six. Watch the sample sixrc.py repository to see detailed instructions and to keep up to date with all the customization options.

Vim options are not supported at the moment. Future versions of Six will implement :set and similar commands for managing settings.

Mappings

Support for mappings is partially implemented.

Normal Mode Mappings

Six currently supports non-recursive Vim mappings in normal mode.

To set a new mapping:

:nmap Y y$

To see available mappings:

:nmap

You can use a User/sixrc.py file to persist mappings See the Settings and Configuration section for more information.

Insert Mode Mappings

Mappings in insert mode can be defined in a .sublime-keymap file.

For example:

{"keys": ["j", "j"], "command": "six_press_key", "args": {"key": "<Esc>"}, "context": [{"key": "six_is_in_insert_mode"}, {"key": "six_is_accepting_input", "operand": false}]}

The six_is_accepting_input context is generally necessary to avoid disrupting commands that expect input, like c<motion>, /<input>, etc.

This is the complete list of contexts that you can use in .sublime-keymap files:

Context Description
six_is_in_command_mode true if Six is in normal or any visual mode
six_is_in_insert_mode true if Six is in insert mode
six_is_in_multiple_selection_mode true if Six is in multiple selection mode
six_is_accepting_input true if Six is currently accepting command input
six_enable_ctrl_keys true if the enable_ctrl_keys setting is true

The Sublime Text API offers limited support to capture and process keys in insert mode. Therefore, insert mode mappings must be defined in .sublime-keymap files.

Extending Six

Six experimentally supports plug-ins in the form of Python code.

Vimscript plugins are not supported.

You can follow the evolution of plug-in support in Six by watching the Six Surround plugin repository.

Miscellaneous

Multiple Selections and Vim Commands

Most Six operators and motions support Sublime Text multiple selections, but some don’t.