Sublime Text 3 insert tab character manually

Question

When using Sublime Text 3, most of my files are set to be indented using spaces. However I sometimes wish to insert a literal tab. When I was using vim I'd use <Ctrl>+v <Tab> but that doesn't work with Sublime Text 3.

I've been searching and searching and cannot find anything. Please help!

Answer 1

There is a default key binding of Shift+Tab to insert a raw tab character into the document, although in certain contextual cases (such as when expanding a snippet) it takes on other functions instead.

However, Indent Using Spaces is controlled by the following setting:

// Set to true to insert spaces when tab is pressed
"translate_tabs_to_spaces": false,

As seen here it defaults to false, but when you have Indent using spaces turned on, it's set to true. As the comment alludes to, when this setting is set to true any attempt to insert a raw tab character gets converted to some number of spaces instead.

As a result, even the official key binding does not insert a raw tab in this case.

Depending on how often you care to insert a literal tab you can work around this by temporarily turning that setting on and off, but this is far from ideal, even when the setting is toggled from the menu in the status bar.

Since Sublime is so customizable, we can automate it into doing that work for us.

To start with, create a file with the following contents and save it in your User package as literal_tab.sublime-macro (use Preferences > Browse Packages... to find your User package if you're not sure where it is):

[
    { "command": "toggle_setting", "args": { "setting": "translate_tabs_to_spaces" } },
    { "command": "insert", "args": { "characters": "\t" } },
    { "command": "toggle_setting", "args": { "setting": "translate_tabs_to_spaces" } }
]

Then, add the following two key bindings to your user bindings (Preferences > Key Bindings in the menu; if there are multiple options, choose User and not Default):

{ 
    "keys": ["ctrl+k","tab"], 
    "command": "insert", 
    "args": {
        "characters": "\t"
    },
    "context":
    [
        { "key": "setting.translate_tabs_to_spaces", "operator": "equal", "operand": false }
    ]
},

{ 
    "keys": ["ctrl+k","tab"], 
    "command": "run_macro_file", 
    "args": {
        "file": "Packages/User/literal_tab.sublime-macro"
    },
    "context":
    [
        { "key": "setting.translate_tabs_to_spaces", "operator": "equal", "operand": true }
    ]
}    

Both bindings include a context that causes it to trigger or not based on the value of the translate_tabs_to_spaces setting, so at any given time only one of them is actually in effect and the other one is automatically disabled.

The first binding is for the case when the setting is turned off, in which case it just needs to insert a tab character and it's done. The second case instead runs our custom macro from above, which turns the setting off, inserts the tab, and then turns the setting on again.

In theory you really only need the second one if you always leave the indent setting turned on, but due to the Principle of Least Surprise it's a good idea to set it up to work regardless of the setting.

Naturally you can use any key stroke that you want (I'm also used to this one from vim), and the name of the macro file doesn't matter as long as it has the correct extension and it matches what the binding tries to execute.

---

Note: Although you mentioned Sublime Text 3 in your question, you tagged Sublime Text 2 as well, so for completeness I'll also note that the information and solution presented here applies to both versions equally.