Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vscode-neovim/vscode-neovim
Vim mode for VSCode, powered by Neovim
https://github.com/vscode-neovim/vscode-neovim
hacktoberfest neovim neovim-backend neovim-clients neovim-guis nvim vim vscode vscode-extension vscode-neovim
Last synced: 5 days ago
JSON representation
Vim mode for VSCode, powered by Neovim
- Host: GitHub
- URL: https://github.com/vscode-neovim/vscode-neovim
- Owner: vscode-neovim
- License: mit
- Created: 2019-10-31T00:46:23.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-17T07:36:59.000Z (3 months ago)
- Last Synced: 2024-10-29T10:13:56.293Z (2 months ago)
- Topics: hacktoberfest, neovim, neovim-backend, neovim-clients, neovim-guis, nvim, vim, vscode, vscode-extension, vscode-neovim
- Language: TypeScript
- Homepage: https://marketplace.visualstudio.com/items?itemName=asvetliakov.vscode-neovim
- Size: 4.38 MB
- Stars: 6,263
- Watchers: 34
- Forks: 216
- Open Issues: 50
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-starred-test - vscode-neovim/vscode-neovim - Vim mode for VSCode, powered by Neovim (TypeScript)
- awesome-repositories - vscode-neovim/vscode-neovim - Vim mode for VSCode, powered by Neovim (TypeScript)
README
# VSCode Neovim
VSCode Neovim Integration
[Neovim](https://neovim.io/) is a fork of Vim to allow greater extensibility and integration. This extension uses a
fully embedded Neovim instance, no more half-complete Vim emulation! VSCode's native functionality is used for insert
mode and VSCode commands, making the best use of both editors.
- 🎉 Feature-complete Vim integration (except insert-mode and some Nvim UI plugins) by utilizing Nvim as a backend.
- 🔧 Supports custom `init.lua` and most Nvim 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).
Table of Contents
- [🧰 Getting Started](#-getting-started)
- [Installation](#installation)
- [Neovim configuration](#neovim-configuration)
- [VSCode Settings \& Commands](#vscode-settings--commands)
- [💡 Tips and Features](#-tips-and-features)
- [VSCode specific differences](#vscode-specific-differences)
- [Troubleshooting](#troubleshooting)
- [Performance](#performance)
- [Composite escape keys](#composite-escape-keys)
- [Jumplist](#jumplist)
- [Multiple cursors](#multiple-cursors)
- [Remote development](#remote-development)
- [⚡️ API](#️-api)
- [vscode.action(name, opts)](#vscodeactionname-opts)
- [vscode.call(name, opts, timeout)](#vscodecallname-opts-timeout)
- [vscode.on(event, callback)](#vscodeonevent-callback)
- [vscode.has_config(name)](#vscodehas_configname)
- [vscode.get_config(name)](#vscodeget_configname)
- [vscode.update_config(name, value, target)](#vscodeupdate_configname-value-target)
- [vscode.notify(msg)](#vscodenotifymsg)
- [vscode.eval(code\[, opts, timeout\])](#vscodeevalcode-opts-timeout)
- [vscode.eval_async(code\[, opts\])](#vscodeeval_asynccode-opts)
- [vscode.with_insert(callback)](#vscodewith_insertcallback)
- [Builtin module overrides](#builtin-module-overrides)
- [VimScript](#vimscript)
- [⌨️ Keybindings (shortcuts)](#️-keybindings-shortcuts)
- [Keybinding Passthroughs](#keybinding-passthroughs)
- [Insert mode control keys passthrough](#insert-mode-control-keys-passthrough)
- [Normal mode control keys passthrough](#normal-mode-control-keys-passthrough)
- [Cmdline mode special keys passthrough](#cmdline-mode-special-keys-passthrough)
- [Disable passthrough for certain filetypes](#disable-passthrough-for-certain-filetypes)
- [Remove other vscode or passthrough keybindings](#remove-other-vscode-or-passthrough-keybindings)
- [Code navigation bindings](#code-navigation-bindings)
- [Explorer/list navigation bindings](#explorerlist-navigation-bindings)
- [Explorer file manipulation bindings](#explorer-file-manipulation-bindings)
- [Hover widget manipulation bindings](#hover-widget-manipulation-bindings)
- [📟 Neovim Commands](#-neovim-commands)
- [File management](#file-management)
- [Tab management](#tab-management)
- [Buffer/window management](#bufferwindow-management)
- [🎨 Highlights](#-highlights)
- [🧰 Developing](#-developing)
- [❤️ Credits \& External Resources](#️-credits--external-resources)
## 🧰 Getting Started
### Installation
Install the [vscode-neovim](https://marketplace.visualstudio.com/items?itemName=asvetliakov.vscode-neovim) extension.
Install [Neovim](https://github.com/neovim/neovim/wiki/Installing-Neovim) **0.10.0** or greater.
> **Note:** Though the extension strives to be as compatible as possible with older versions of Neovim, some older
> versions may have quirks that are not present anymore. In light of this, certain configuration settings are
> recommended in some older versions for the best experience. These can be found
> [on the wiki](https://github.com/vscode-neovim/vscode-neovim/wiki/Version-Compatibility-Notes).
\[Optional\] Set the Neovim path in the extension settings under
"`vscode-neovim.neovimExecutablePaths.win32/linux/darwin`", respective to your system. For example,
"`C:\Neovim\bin\nvim.exe`" or "`/usr/local/bin/nvim`".
> **WSL Users:** If you want to use Neovim from WSL, set the `useWSL` configuration toggle and specify the Linux path to
> the 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.
>
> **Snap Users:** If you want to use Neovim from Snap, the Neovim path must be resolved to the snap binary location. On
> some systems it might be "`/snap/nvim/current/usr/bin/nvim`". To check if you're running as a snap package, see if
> `which nvim` resolves to `/usr/bin/snap`.
### Neovim configuration
Since many Vim plugins can cause issues in VSCode, it is recommended to start from an empty `init.vim`. For a guide for
which types of plugins are supported, see [troubleshooting](#troubleshooting).
Before creating an issue on Github, make sure you can reproduce the problem with an empty `init.vim` and no VSCode
extensions.
To determine if Neovim is running in VSCode, add to your `init.vim`:
```vim
if exists('g:vscode')
" VSCode extension
else
" ordinary Neovim
endif
```
In lua:
```lua
if vim.g.vscode then
-- VSCode extension
else
-- ordinary Neovim
end
```
To conditionally activate plugins, the best solution is to use the
[LazyVim VSCode extra](https://www.lazyvim.org/extras/vscode). However, `packer.nvim` and `lazy.nvim` have built-in
support for `cond = vim.g.vscode` and `vim-plug` has a
[few solutions](https://github.com/junegunn/vim-plug/wiki/tips#conditional-activation). See
[plugins](https://github.com/vscode-neovim/vscode-neovim/wiki/Plugins) in the wiki for tips on configuring Vim plugins.
### VSCode Settings & Commands
You can view all available [settings](https://code.visualstudio.com/docs/getstarted/settings) and commands by opening
the [vscode-neovim](vscode:extension/asvetliakov.vscode-neovim) extension details pane, and navigating to the features
tab.
## 💡 Tips and Features
### VSCode specific differences
- File and editor management commands such as `:e`/`:q`/`:vsplit`/`:tabnext`/etc are mapped to corresponding VSCode
commands and behavior may be different ([see below](#%EF%B8%8F-keybindings-shortcuts)).
- **Do not** use vim commands like `:e` 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
`require('vscode').call()` (see [API](#%EF%B8%8F-api)).
- Since version 1.18.0, `:w`, `:wa` and `:sav` commands are supported and no longer alias to VSCode commands. You
can use them as you would in Neovim.
- When you type some commands they may be substituted for another, check
[AlterCommand](https://github.com/search?q=repo%3Avscode-neovim%2Fvscode-neovim%20AlterCommand&type=code) for the list
of substitutions.
- 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` in insert mode, then move the cursor to `abc` 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.
### Troubleshooting
- View the logs via `Output: Focus on Output View` and select `vscode-neovim`.
- **To enable debug logs,** click the "gear" icon and select `Debug`, then click it again and choose
`Set As Default`.
- Enable `vscode-neovim.neovimClean` in VSCode settings, which starts Nvim _without_ your plugins (`nvim --clean`). Nvim
plugins can do _anything_. Visual effects in particular can cause visual artifacts. vscode-neovim does its best to
merge the visual effects of Nvim and VSCode, but it's far from perfect. You may need to disable some Nvim plugins that
cause visual effects.
- If you encounter rendering issues (visual artifacts), try CTRL-L to force Nvim to redraw.
- If you get the `Unable to init vscode-neovim: command 'type' already exists` message, uninstall other VSCode
extensions that use `registerTextEditorCommand("type", …)` (like
[VSCodeVim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) or
[Overtype](https://marketplace.visualstudio.com/items?itemName=adammaras.overtype)).
- 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`.
- To fix the remapped escape key not working in Linux, set `"keyboard.dispatch": "keyCode"`.
### Performance
If you have any performance problems (cursor jitter usually) make sure you're not using 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. Specifically, you don't need any
code highlighting, completion, LSP plugins, or plugins that spawn windows/buffers (nerdtree , fuzzy-finders, etc). Most
navigation/textobject/editing plugins should be fine.
For example, make sure you're not using 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)
> If you're not sure, disable all other extensions, **reload VSCode window**, and see if the problem persists before
> reporting it.
### Composite escape keys
Set with `compositeKeys` and tweak with `compositeTimeout`.
Examples: add to your `settings.json`:
jj to escape
```jsonc
{
"vscode-neovim.compositeKeys": {
"jj": {
"command": "vscode-neovim.escape",
},
},
}
```
jk to escape and save
```jsonc
{
"vscode-neovim.compositeKeys": {
"jk": {
// Use lua to execute any logic
"command": "vscode-neovim.lua",
"args": [
[
"local code = require('vscode')",
"code.action('vscode-neovim.escape')",
"code.action('workbench.action.files.save')",
],
],
},
},
}
```
### Jumplist
VSCode's jumplist is used instead of Neovim's. This is to make VSCode native navigation (mouse click, jump to
definition, etc) 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.
### 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:
> **Note**: The built-in multi-cursor support may not meet your needs. Please refer to the plugin
> [vscode-multi-cursor.nvim](https://github.com/vscode-neovim/vscode-multi-cursor.nvim) for more multi-cursor features
### Remote development
We intend to use vscode-neovim as a UI extension, so when you're using remote development, vscode-neovim is enabled in
the Local Extension Host, and it should work out of the box.
If you prefer to use the remote environment's copy of Neovim, rather than the locally installed one, vscode-neovim
should be installed in the Remote Extension Host. You can set the following in your VSCode `settings.json`:
```json
{
"remote.extensionKind": {
"asvetliakov.vscode-neovim": ["workspace"]
}
}
```
> **Note**: You will need to install neovim in the remote environment.
For more information:
- [Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
- [Extension Host](https://code.visualstudio.com/api/advanced-topics/extension-host)
- [Remote Extensions](https://code.visualstudio.com/api/advanced-topics/remote-extensions)
## ⚡️ API
Load the module:
```lua
local vscode = require('vscode')
```
> [!TIP]
> The previously used module named "vscode-neovim" is now deprecated, so don't be confused if "vscode-neovim" is used in old discussions or other resources.
1. `vscode.action()`: asynchronously executes a vscode command.
2. `vscode.call()`: synchronously executes a vscode command.
3. `vscode.on()`: defines a handler for some Nvim UI events.
4. `vscode.has_config()`: checks if a vscode setting exists.
5. `vscode.get_config()`: gets a vscode setting value.
6. `vscode.update_config()`: sets a vscode setting.
7. `vscode.notify()`: shows a vscode message (see also Nvim's `vim.notify`).
8. `vscode.to_op()`: A helper for `map-operator`. See [code_actions.lua](./runtime/vscode/code_actions.lua) for the
usage
9. `g:vscode_clipboard`: Clipboard provider using VSCode's clipboard API. Used by default when in WSL. See
`:h g:clipboard` for more details. Usage: `vim.g.clipboard = vim.g.vscode_clipboard`
10. `vscode.eval()`: evaluate javascript synchronously in vscode and return the result
11. `vscode.eval_async()`: evaluate javascript asynchronously in vscode
12. `vscode.with_insert()`: perform operations in insert mode.
### vscode.action(name, opts)
Asynchronously executes a vscode command.
Parameters:
- `name` (string): The name of the action, generally a vscode command.
- `opts` (table): Map of optional parameters:
- `args` (table): List of arguments passed to the vscode command. If the command only requires a single object
parameter, you can directly pass in a map-like table.
- Examples:
- `action('foo', { args = { 'foo', 'bar', … } })`
- `action('foo', { args = { foo = bar, … } })`
- `range` (table): Specific range for the action. Implicitly passed in visual mode. Has three possible forms (all
values are 0-indexed):
- `[start_line, end_line]`
- `[start_line, start_character, end_line, end_character]`
- `{start = { line = start_line, character = start_character}, end = { line = end_line, character = end_character}}`
- `restore_selection` (boolean): Whether to preserve the current selection. Only valid when `range` is specified.
Defaults to `true`.
- `callback`: Function to handle the action result. Must have this signature: `function(err: string|nil, ret: any)`:
- `err` is the error message, if any
- `ret` is the result
- If no callback is provided, error will be shown as a VSCode notification.
Example: open definition aside (default binding):
```vim
nnoremap gd lua require('vscode').action('editor.action.revealDefinitionAside')
```
Example: find in files for word under cursor (see the
[vscode command definition](https://github.com/microsoft/vscode/blob/43b0558cc1eec2528a9a1b9ee1c7a559823bda31/src/vs/workbench/contrib/search/browser/searchActionsFind.ts#L177-L197)
for the expected parameter format):
```vim
nnoremap ? lua require('vscode').action('workbench.action.findInFiles', { args = { query = vim.fn.expand('') } })
```
Example: use in lua script:
```lua
-- Format current document
vscode.action("editor.action.formatDocument")
do -- Comment the three lines below the cursor
local curr_line = vim.fn.line(".") - 1 -- 0-indexed
vscode.action("editor.action.commentLine", {
range = { curr_line + 1, curr_line + 3 },
})
end
do -- Comment the previous line
local curr_line = vim.fn.line(".") - 1 -- 0-indexed
local prev_line = curr_line - 1
if prev_line >= 0 then
vscode.action("editor.action.commentLine", {
range = { prev_line , prev_line },
})
end
end
do -- Find in files for word under cursor
vscode.action("workbench.action.findInFiles", {
args = { query = vim.fn.expand('') }
})
end
```
Currently, two built-in actions are provided for testing purposes:
1. `_ping` returns `"pong"`
2. `_wait` waits for the specified milliseconds and then returns `"ok"`
```lua
do -- Execute _ping asynchronously and print the result
vscode.action("_ping", {
callback = function(err, res)
if err == nil then
print(res) -- outputs: pong
end
end,
})
end
```
### vscode.call(name, opts, timeout)
Synchronously executes a vscode command.
Parameters:
- `name` (string): The name of the action, generally a vscode command.
- `opts` (table): Same as [vscode.action()](#vscodeactionname-opts).
- `timeout` (number): Timeout in milliseconds. The default value is -1, which means there is no timeout.
Returns: the result of the action
Example: format selection (default binding):
```vim
xnoremap = lua require('vscode').call('editor.action.formatSelection')
nnoremap = lua require('vscode').call('editor.action.formatSelection')
nnoremap == lua require('vscode').call('editor.action.formatSelection')
```
Example: use in lua script:
```lua
-- Execute _ping synchronously and print the result
print(vscode.call("_ping")) -- outputs: pong
-- Wait for 1 second and print the return value 'ok'
print(vscode.call("_wait", { args = { 1000 } })) -- outputs: ok
-- Wait for 2 seconds with a timeout of 1 second
print(vscode.call("_wait", { args = { 2000 } }), 1000)
-- error: Call '_wait' timed out
```
### vscode.on(event, callback)
Currently no available events for user use.
### vscode.has_config(name)
Check if configuration has a certain value.
Parameters:
- `name` (string|string[]): The configuration name or an array of configuration names.
Returns:
- `boolean|boolean[]`: Returns `true` if the configuration has a certain value, `false` otherwise. If `name` is an
array, returns an array of booleans indicating whether each configuration has a certain value or not.
Examples:
```lua
-- Check if the configuration "not.exist" exists
print(vscode.has_config("not.exist"))
-- Should return: false
-- Check multiple configurations
vim.print(vscode.has_config({ "not.exist", "existing.config" }))
-- Should return: { false, true }
```
### vscode.get_config(name)
Get configuration value.
Parameters:
- `name` (string|string[]): The configuration name or an array of configuration names.
Returns:
- `unknown|unknown[]`: The value of the configuration. If `name` is an array, returns an array of values corresponding
to each configuration.
Examples:
```lua
-- Get the value of "editor.tabSize"
print(vscode.get_config("editor.tabSize")) -- a number
-- Get multiple configurations
vim.print(vscode.get_config({ "editor.fontFamily", "editor.tabSize" }))
-- Should return: { "the font family", "the editor tabSizse" }
```
### vscode.update_config(name, value, target)
Update configuration value.
Parameters:
- `name` (string|string[]): The configuration name or an array of configuration names.
- `value` (unknown|unknown[]): The new value for the configuration.
- `target` ("global"|"workspace"): The configuration target. Optional
Examples:
```lua
-- Update the value of "editor.tabSize"
vscode.update_config("editor.tabSize", 16, "global")
-- Update multiple configurations
vscode.update_config({ "editor.fontFamily", "editor.tabSize" }, { "Fira Code", 14 })
```
### vscode.notify(msg)
Show a vscode notification
You can set `vscode.notify` as your default notify function.
```lua
vim.notify = vscode.notify
```
### vscode.eval(code[, opts, timeout])
Evaluate javascript inside vscode and return the result. The code is executed in an async function context (so `await`
can be used). Use a `return` statement to return a value back to lua. Arguments passed from lua are available as the
`args` variable. The evaluated code has access to the
[VSCode API](https://code.visualstudio.com/api/references/vscode-api) through the `vscode` global.
Tips:
- Make sure to `await` on asynchronous functions when accessing the API.
- Use the global `logger` (e.g. `logger.info(...)`) to log messages to the output of vscode-neovim.
- JSON serializable values (primitives and simple objects) can be returned and will be automatically serialized then
deserialized to an equivalent lua value. If the return value is not JSON serializable then an error will be raised.
- `globalThis['some_name'] = ...` can be used to persist values between calls.
Parameters:
- `code` (string): The javascript to execute.
- `opts` (table): Map of optional parameters:
- `args` (any): a value to make available as the `args` variable in javascript. Can be a single value such as a
string or a table of multiple values.
- `timeout` (number): The number of milliseconds to wait for the evaluation to complete before cancelling. By default
there is no timeout.
Returns:
- The result of executing the provided code.
Examples:
```lua
local current_file = vscode.eval("return vscode.window.activeTextEditor.document.fileName")
local current_tab_is_pinned = vscode.eval("return vscode.window.tabGroups.activeTabGroup.activeTab.isPinned")
vscode.eval("await vscode.env.clipboard.writeText(args.text)", { args = { text = "some text" } })
```
### vscode.eval_async(code[, opts])
Like `vscode.eval()` but returns immediately and evaluates in the background instead.
Parameters:
- `code` (string): The javascript to execute.
- `opts` (table): Map of optional parameters:
- `args` (any): a value to make available as the `args` variable in javascript. Can be a single value such as a
string or a table of multiple values.
- `callback`: Function to handle the eval result. Must have this signature: `function(err: string|nil, ret: any)`:
- `err` is the error message, if any
- `ret` is the result
- If no callback is provided, error will be shown as a VSCode notification.
### vscode.with_insert(callback)
Perform operations in insert mode. If in visual mode, this function will **preserve the selection** after switching to
insert mode.
Parameters:
- `callback` (function): Callback function to run after switching to insert mode
Example: make `editor.action.addSelectionToNextFindMatch` work correctly in any mode.
```lua
vim.keymap.set({ "n", "x", "i" }, "", function()
vscode.with_insert(function()
vscode.action("editor.action.addSelectionToNextFindMatch")
end)
end)
```
Example: make "editor.action.refactor" work correctly on the selection and support snippet manipulation after entering
VSCode snippet mode.
```lua
vim.keymap.set({ "n", "x" }, "r", function()
vscode.with_insert(function()
vscode.action("editor.action.refactor")
end)
end)
```
### Builtin module overrides
1. [`vim.ui`](/runtime/vscode/ui.lua): use VSCode's UI components.
2. [`vim.lsp.buf`](/runtime/vscode/lsp/buf.lua): execute corresponding VSCode LSP commands.
### VimScript
> **Note:** Since 1.0.0, vimscript functions are deprecated. Use the [Lua](#%EF%B8%8F-api) api instead.
- `VSCodeNotify()`/`VSCodeCall()`: deprecated, use [Lua](#%EF%B8%8F-api) `require('vscode').call()` instead.
- `VSCodeNotifyRange()`/`VSCodeCallRange()`: deprecated, use [Lua](#%EF%B8%8F-api)
`require('vscode').call(…, {range:…})` instead.
- `VSCodeNotifyRangePos()`/`VSCodeCallRangePos()`: deprecated, use [Lua](#%EF%B8%8F-api)
`require('vscode').call(…, {range:…})` instead.
You can also use `v:lua.require("vscode")` to access the API from VimScript.
## ⌨️ Keybindings (shortcuts)
There are three types of default/user keybindings in vscode-neovim:
- **Neovim keybindings**: These are the keybindings that are defined in the extension's vimscript files or the user's
`init.vim` file. These provide code navigation, buffer management, and other neovim-specific overrides.
- **VSCode keybindings**: These are the keybindings that are defined in the extension's `package.json` or the user's
`keybindings.json` file. These provide the ability to interact with VSCode's built-in features, and are used to make
VSCode more Vim-like.
- **VSCode passthrough keybindings**: These are the keybindings that are defined in the extension's `package.json` or
the user's `keybindings.json` file, but simply pass the keypress through to Neovim. These are used to allow Neovim to
handle certain keypresses that would otherwise be handled by VSCode.
This document only mentions some special cases, it is not an exhaustive list of keybindings and commands. Use VSCode and
Nvim features to see documentation and all defined shortcuts:
- Run the `Preferences: Open Keyboard Shortcuts` vscode command and search for "neovim" to see all vscode and
passthrough keybindings.
- Use the Nvim `:help` command to see the documentation for a given neovim command or keybinding. For example try
`:help :split` or `:help zo`.
- Note that `:help` for `` bindings is spelled `CTRL-…`. For example to see the help for ``, run
`:help CTRL-W`.
- Search the online Nvim documentation:
### Keybinding Passthroughs
Every special (control/alt/non-alphanumerical) keyboard shortcut must be explicitly defined in VSCode to send to neovim.
By default, only bindings that are used by Neovim by default are sent.
> **Note:** if you want to pass additional control keys without adding a custom passthrough, see below.
To add a custom passthrough, for example A-h in normal mode, add to your `keybindings.json`:
```jsonc
{
"command": "vscode-neovim.send",
// the key sequence to activate the binding
"key": "alt+h",
// don't activate during insert mode
"when": "editorTextFocus && neovim.mode != insert",
// the input to send to Neovim
"args": "",
}
```
#### Insert mode control keys passthrough
Set by `vscode-neovim.ctrlKeysForInsertMode`.
Default: `["a", "d", "h", "j", "m", "o", "r", "t", "u", "w"]`
#### Normal mode control keys passthrough
Set by `ctrlKeysForNormalMode`.
Default:
`["a", "b", "d", "e", "f", "h", "i", "j", "k", "l", "m", "o", "r", "t", "u", "v", "w", "x", "y", "z", "/", "]"]`
#### Cmdline mode special keys passthrough
Always enabled.
- Tab, Up, Down
- Ctrl keys: `` `` `` `` `` `` `` ``
- All `` prefixed keys
#### Disable passthrough for certain filetypes
Set by `editorLangIdExclusions`.
Disable keybindings defined by this extension in certain filetypes. Please note that this will not affect all
keybindings.
#### Remove other vscode or passthrough keybindings
If the above configuration flags do not provide enough control, you can remove the keybindings by editing your
`keybindings.json` or using the VSCode keybindings editor:
### Code navigation bindings
| Key | VSCode Command |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| = / == | `editor.action.formatSelection` |
| gh / K | `editor.action.showHover` |
| gd / C-] | `editor.action.revealDefinition`
Also works in vim help. |
| gf | `editor.action.revealDeclaration` |
| gH | `editor.action.referenceSearch.trigger` |
| gO | `workbench.action.gotoSymbol` |
| C-w gd / C-w gf | `editor.action.revealDefinitionAside` |
| gD | `editor.action.peekDefinition` |
| gF | `editor.action.peekDeclaration` |
| Tab | `togglePeekWidgetFocus`
Switch between peek editor and reference list. |
| C-n / C-p | Navigate lists, parameter hints, suggestions, quick-open, cmdline history, peek reference list |
> 💡 To specify the default peek mode, modify `editor.peekWidgetDefaultFocus` in your settings.
### Explorer/list navigation bindings
| Key | VSCode Command |
| ----------------------------------- | ------------------------------- |
| j or k | `list.focusDown/Up` |
| h or l | `list.collapse/select` |
| Enter | `list.select` |
| gg | `list.focusFirst` |
| G | `list.focusLast` |
| o | `list.toggleExpand` |
| C-u or C-d | `list.focusPageUp/Down` |
| zo or zO | `list.expand` |
| zc | `list.collapse` |
| zC | `list.collapseAllToFocus` |
| za or zA | `list.toggleExpand` |
| zm or zM | `list.collapseAll` |
| / or Escape | `list.toggleKeyboardNavigation` |
### Explorer file manipulation bindings
| Key | VSCode Command |
| ------------ | --------------------------------------------- |
| r | `renameFile` |
| d | `deleteFile` |
| y | `filesExplorer.copy` |
| x | `filesExplorer.cut` |
| p | `filesExplorer.paste` |
| v | `explorer.openToSide` |
| a | `explorer.newFile` |
| A | `explorer.newFolder` |
| R | `workbench.files.action.refreshFilesExplorer` |
### Hover widget manipulation bindings
| Key | VSCode Command |
| -------------- | -------------------------------- |
| K | `editor.action.showHover` |
| h | `editor.action.scrollLeftHover` |
| j | `editor.action.scrollDownHover` |
| k | `editor.action.scrollUpHover` |
| l | `editor.action.scrollRightHover` |
| gg | `editor.action.goToTopHover` |
| G | `editor.action.goToBottomHover` |
| C-f | `editor.action.pageDownHover` |
| C-b | `editor.action.pageUpHover` |
## 📟 Neovim Commands
Default commands and bindings are available for file/scroll/window/tab management.
#### File management
See [vscode-file-commands.vim](/runtime/vscode/overrides/vscode-file-commands.vim) for file commands reference.
The extension aliases various Nvim commands (`:edit`, `:enew`, `:find`, `:quit`, etc.) to equivalent vscode commands.
Also their normal-mode equivalents (where applicable) such as C-w q, etc.
#### Tab management
See [vscode-tab-commands.vim](/runtime/vscode/overrides/vscode-tab-commands.vim) for tab commands reference.
The extension aliases various Nvim tab commands (`:tabedit`, `:tabnew`, `:tabfind`, `:tabclose`, `:tabnext`,
`:tabprevious`, `:tabfirst`, `:tablast`) to equivalent vscode commands. Also their normal-mode equivalents (where
applicable) such as gt, etc.
#### Buffer/window management
See [vscode-window-commands.vim](/runtime/vscode/overrides/vscode-window-commands.vim) for file commands reference.
The extension aliases various Nvim buffer/window commands (`:split`, `:vsplit`, `:new`, `:vnew`, `:only`) to equivalent
vscode commands. Also their normal-mode equivalents (where applicable) such as C-w s, etc.
> 💡 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`
Copy this into init.vim
```vim
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 > call manageEditorSize(v:count, 'increase')
xnoremap > call manageEditorSize(v:count, 'increase')
nnoremap + call manageEditorSize(v:count, 'increase')
xnoremap + call manageEditorSize(v:count, 'increase')
nnoremap < call manageEditorSize(v:count, 'decrease')
xnoremap < call manageEditorSize(v:count, 'decrease')
nnoremap - call manageEditorSize(v:count, 'decrease')
xnoremap - call manageEditorSize(v:count, 'decrease')
```
## 🎨 Highlights
There are two ways to customize highlight colors:
1. Set colors in nvim
**Note**: Due to the support for the `syntax` option requiring processing of syntax highlights, all built-in
highlight groups may be overridden or cleared. Therefore, please do not link any highlights to the built-in
highlight groups.
2. Set colors in vscode
- [vscode-neovim.highlightGroups.highlights](https://github.com/vscode-neovim/vscode-neovim/blob/2657c4506b3dffe0d069db2891e30cebd963c2be/package.json#L160C1-L202C19)
- [ThemeColor](https://code.visualstudio.com/api/references/theme-color)
## 🧰 Developing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
## ❤️ Credits & External Resources
- [vim-altercmd](https://github.com/kana/vim-altercmd) - Used for rebinding default commands to call VSCode command.
- [neovim nodejs client](https://github.com/neovim/node-client) - NodeJS library for communicating with Neovim.
- [VSCodeVim](https://github.com/VSCodeVim/Vim) - Used for various inspiration.