asvetliakov / Vscode Neovim

VSCode Neovim

VSCode Neovim Integration

Neovim is a fork of VIM to allow greater extensibility and integration. This extension uses a full embedded Neovim instance, no more half-complete VIM emulation! VSCode's native functionality is used for insert mode and editor commands, making the best use of both editors.

• 🎉 Almost fully feature-complete VIM integration by utilizing neovim as a backend.
• 🔧 Supports custom init.vim and many vim plugins.
• 🥇 First-class and lag-free insert mode, letting VSCode do what it does best.
• 🤝 Complete integration with VSCode features (lsp/autocompletion/snippets/multi-cursor/etc).

🧰 Installation

• Install the vscode-neovim extension.
• Install Neovim 0.5.0 or greater.
  • Set the neovim path in the extension settings. You must specify full path to neovim, like "C:\Neovim\bin\nvim.exe" or "/usr/local/bin/nvim".
  • The setting id is "vscode-neovim.neovimExecutablePaths.win32/linux/darwin", respective to your system.
• If you want to use neovim from WSL, set the useWSL configuration toggle and specify linux path to nvim binary. wsl.exe windows binary and wslpath linux binary are required for this. wslpath must be available through $PATH linux env setting. Use wsl --list to check for the correct default linux distribution.

❗ Neovim 0.5.0 or greater is required. Any version lower than that won't work. Many linux distributions have an old version of neovim in their package repo - always check what version are you installing. You can install neovim separately, outside your system's package manager installation, for example using the appimage from the neovim releases page.

🐛 See the issues section for known issues.

💡 Tips and Features

Important

• If you get "Unable to init vscode-neovim: command 'type' already exists" message, uninstall other VSCode extensions that register the type command (like VSCodeVim or Overtype).
• If you already have a big init.vim it is recommended to wrap existing settings & plugins with if !exists('g:vscode') to prevent potential conflicts. If you have any problems, try with empty init.vim first.
• On a Mac, the h, j, k and l movement keys may not repeat when held, to fix this open Terminal and execute the following command: defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false.
• The extension works best if editor.scrollBeyondLastLine is disabled.

VSCode specific differences

• File and editor management commands such as :e/:w/:q/:vsplit/:tabnext/etc are mapped to corresponding vscode commands and behavior may be different (see below). Do not use vim commands like :w in scripts/keybindings, they won't work. If you're using them in some custom commands/mappings, you might need to rebind them to call vscode commands from neovim with VSCodeCall/VSCodeNotify (see below).
• Visual modes don't produce vscode selections, so any vscode commands expecting selection won't work. To round the corners, invoking the VSCode command picker from visual mode through the default hotkeys (f1/ctrl/cmd+shift+p) converts vim selection to real vscode selection. This conversion is also done automatically for some commands like commenting and formatting. If you're using some custom mapping for calling vscode commands that depends on real vscode selection, you can use VSCodeNotifyRange/VSCodeNotifyRangePos/VSCodeNotifyVisual (linewise, characterwise, and automatic) which will convert vim visual mode selection to vscode selection before calling the command (see below).
• When you type some commands they may be substituted for the another, like :write will be replaced by :Write.
• Scrolling is done by VSCode. C-d/C-u/etc are slightly different.
• Editor customization (relative line number, scrolloff, etc) is handled by VSCode.
• Dot-repeat (.) is slightly different - moving the cursor within a change range won't break the repeat. sequence. In neovim, if you type abc<cursor> in insert mode, then move cursor to a<cursor>bc and type 1 here the repeat sequence would be 1. However in vscode it would be a1bc. Another difference is that when you delete some text in insert mode, dot repeat only works from right-to-left, meaning it will treat Del key as BS keys when running dot repeat.

Performance problems

If you have any performance problems (cursor jitter usually) make sure you're not using these kinds of extensions:

• Anything that renders decorators very often:
  • Line number extensions (VSCode has built-in support for normal/relative line numbers)
  • Indent guide extensions (VSCode has built-in indent guides)
  • Brackets highlighter extensions (VSCode has built-in feature)
• VSCode extensions that delay the extension host like "Bracket Pair Colorizer"
• VIM plugins that increase latency and cause performance problems.
  • Make sure to disable unneeded plugins, as many of them don't make sense with vscode and may cause problems.
  • You don't need any code, highlighting, completion, lsp plugins as well any plugins that spawn windows/buffers (nerdtree and similar), fuzzy-finders, etc.
  • Many navigation/textobject/editing plugins should be fine.

If you're not sure, disable all other extensions, reload vscode window, and see if the problem persists before reporting.

Conditional init.vim

To determine if neovim is running in vscode, add to your init.vim:

if exists('g:vscode')
    " VSCode extension
else
    " ordinary neovim
endif

To conditionally activate plugins, vim-plug has a few solutions. For example, using the Cond helper, you can conditionally activate installed plugins (source):

" inside plug#begin:
" use normal easymotion when in vim mode
Plug 'easymotion/vim-easymotion', Cond(!exists('g:vscode'))
" use vscode easymotion when in vscode mode
Plug 'asvetliakov/vim-easymotion', Cond(exists('g:vscode'), { 'as': 'vsc-easymotion' })

Custom escape keys

Since VSCode is responsible for insert mode, custom insert-mode vim mappings don't work. To map composite escape keys, put into your keybindings.json:

for jj

{
    "command": "vscode-neovim.compositeEscape1",
    "key": "j",
    "when": "neovim.mode == insert && editorTextFocus",
    "args": "j"
}

to enable jk add also:

{
    "command": "vscode-neovim.compositeEscape2",
    "key": "k",
    "when": "neovim.mode == insert && editorTextFocus",
    "args": "k"
}

Currently, there is no way to map both jk and kj, or to map jk without also mapping jj.

Jumplist

VSCode's jumplist is used instead of Neovim's. This is to make VSCode native navigation (mouse click, jump to definition, ect) navigable through the jumplist.

Make sure to bind to workbench.action.navigateBack / workbench.action.navigateForward if you're using custom mappings. Marks (both upper & lowercased) should work fine.

Wildmenu completion

Command menu has the wildmenu completion on type. The completion options appear after 1.5s (to not bother you when you write :w or :noh). Up/Down selects the option and Tab accepts it. See the gif:

Multiple cursors

Multiple cursors work in:

1. Insert mode
2. Visual line mode
3. Visual block mode

To spawn multiple cursors from visual line/block modes type ma/mA or mi/mI (by default). The effect differs:

• For visual line mode, mi will start insert mode on each selected line on the first non whitespace character and ma will on the end of line.
• For visual block mode, mi will start insert on each selected line before the cursor block and ma after.
• mA/mI versions accounts for empty lines (only for visual line mode, for visual block mode they're same as ma/mi).

See gif in action:

Keyboard Quickfix

By default, the quickfix menu can be opened using z= or C-.. However, it is currently not possible to add mappings to the quickfix menu, so it can only be navigated with arrow keys. A workaround vscode extension has been made to use the quick open menu, which can be navigated with custom bindings.

To use, install the keyboard-quickfix extension, and add to your keybindings.json:

{
    "key": "ctrl+.",
    "command": "keyboard-quickfix.openQuickFix",
    "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly"
},

and add to your init.vim:

nnoremap z= <Cmd>call VSCodeNotify('keyboard-quickfix.openQuickFix')<CR>

Invoking VSCode actions from neovim

There are a few helper functions that could be used to invoke any vscode commands:

💡 Functions with Notify in their name are non-blocking, the ones with Call are blocking. Generally use Notify unless you really need a blocking call.

Examples

Produce linewise/characterwise selection and show vscode commands (default binding):

function! VSCodeNotifyVisual(cmd, leaveSelection, ...)
    let mode = mode()
    if mode ==# 'V'
        let startLine = line('v')
        let endLine = line('.')
        call VSCodeNotifyRange(a:cmd, startLine, endLine, a:leaveSelection, a:000)
    elseif mode ==# 'v' || mode ==# "\<C-v>"
        let startPos = getpos('v')
        let endPos = getpos('.')
        call VSCodeNotifyRangePos(a:cmd, startPos[1], endPos[1], startPos[2], endPos[2] + 1, a:leaveSelection, a:000)
    else
        call VSCodeNotify(a:cmd, a:000)
    endif
endfunction

xnoremap <C-S-P> <Cmd>call VSCodeNotifyVisual('workbench.action.showCommands', 1)<CR>

Open definition aside (default binding):

nnoremap <C-w>gd <Cmd>call VSCodeNotify('editor.action.revealDefinitionAside')<CR>

Run Find in files for word under cursor in vscode:

nnoremap ? <Cmd>call VSCodeNotify('workbench.action.findInFiles', { 'query': expand('<cword>')})<CR>

⌨️ Bindings

Custom keymaps for scrolling/window/tab/etc management

• See vscode-scrolling.vim for scrolling commands reference
• See vscode-file-commands.vim for file commands reference
• See vscode-tab-commands.vim for tab commands reference
• See vscode-window-commands.vim for window commands reference

💡 "With bang" refers to adding a "!" to the end of a command.

File management

Tab management

Buffer/window management

💡 Split size distribution is controlled by workbench.editor.splitSizing setting. By default, it's distribute, which is equal to vim's equalalways and eadirection = 'both' (default).

To use VSCode command 'Increase/decrease current view size' instead of separate bindings for width and height:

• workbench.action.increaseViewSize
• workbench.action.decreaseViewSize

function! s:manageEditorSize(...)
    let count = a:1
    let to = a:2
    for i in range(1, count ? count : 1)
        call VSCodeNotify(to ==# 'increase' ? 'workbench.action.increaseViewSize' : 'workbench.action.decreaseViewSize')
    endfor
endfunction

" Sample keybindings. Note these override default keybindings mentioned above.
nnoremap <C-w>> <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
xnoremap <C-w>> <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
nnoremap <C-w>+ <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
xnoremap <C-w>+ <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
nnoremap <C-w>< <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
xnoremap <C-w>< <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
nnoremap <C-w>- <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
xnoremap <C-w>- <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>

Insert mode special keys

Enabled by useCtrlKeysForInsertMode (default true).

Other keys are not supported in insert mode.

Normal mode control keys

Enabled by useCtrlKeysForNormalMode (default true).

Refer to vim manual for their use.

• C-a
• C-b
• C-c
• C-d
• C-e
• C-f
• C-i
• C-o
• C-r
• C-u
• C-v
• C-w
• C-x
• C-y
• C-]
• C-j
• C-k
• C-l
• C-h
• C-/

Cmdline special keys

Always enabled.

VSCode specific bindings

Editor command

💡 To specify the default peek mode, modify editor.peekWidgetDefaultFocus in your settings.

Explorer/list navigation

💡 To enable explorer list navigation, add "workbench.list.automaticKeyboardNavigation": false to your settings.json.

Explorer file manipulation

Custom keybindings

Control keys which are not in the above tables are not sent to neovim by default. To pass additional ctrl keys to neovim, for example C-Tab, add to your keybindings.json:

{
    "command": "vscode-neovim.send",
    // the key sequence to activate the binding
    "key": "ctrl+tab",
    // don't activate during insert mode
    "when": "editorTextFocus && neovim.mode != insert",
    // the input to send to neovim
    "args": "<C-Tab>"
}

To disable existing an ctrl key sequence, for example C-A add to your keybindings.json:

{
    "command": "-vscode-neovim.send",
    "key": "ctrl+a"
}

🤝 Vim Plugins

Most vim plugins will work out of the box, but certain plugins may require some fixes to work properly.

vim-easymotion

While the original vim-easymotion functions as expected, it works by replacing your text with markers then restoring back, which leads to broken text and many errors reported in VSCode.

For this reason I created the special vim-easymotion fork which doesn't touch your text and instead use vscode text decorations. Just add my fork to your vim-plug block or by using your favorite vim plugin installer and delete original vim-easymotion. Also overwin motions won't work (obviously) so don't use them.

By default, text decorations will appear behind of the associated text as shown in the screenshot. To show the decorations on top of the text, set vscode-neovim.textDecorationsAtTop to true.

Happy jumping!

vim-commentary

You can use vim-commentary if you like it. But vscode already has such functionality so why don't use it? Add to your init.vim/init.nvim:

xmap gc  <Plug>VSCodeCommentary
nmap gc  <Plug>VSCodeCommentary
omap gc  <Plug>VSCodeCommentary
nmap gcc <Plug>VSCodeCommentaryLine

Similar to vim-commentary, gcc is comment line (accept count), use gc with motion/in visual mode. VSCodeCommentary is just a simple function which calls editor.action.commentLine.

quick-scope

quick-scope plugin uses default vim HL groups by default but they are normally ignored. To fix, add

highlight QuickScopePrimary guifg='#afff5f' gui=underline ctermfg=155 cterm=underline
highlight QuickScopeSecondary guifg='#5fffff' gui=underline ctermfg=81 cterm=underline

to your init.vim. The underline color can be changed by the guisp tag.

📑 How it works

• VScode connects to neovim instance
• When opening a some file, a scratch buffer is created in nvim and being init with text content from vscode
• Normal/visual mode commands are being sent directly to neovim. The extension listens for buffer events and applies edits from neovim
• When entering the insert mode, the extensions stops listen for keystroke events and delegates typing mode to vscode (no neovim communication is being performed here)
• After pressing escape key from the insert mode, extension sends changes obtained from the insert mode to neovim

❤️ Credits & External Resources

• vim-altercmd - Used for rebinding default commands to call vscode command
• neovim nodejs client - NodeJS library for communicating with Neovim
• VSCodeVim - Used for various inspiration