VSCodeVim is automatically enabled following [installation](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) and reloading of VSCode.
Vimscript is _not_ supported, therefore we are _not_ able to load your `.vimrc` or use `.vim` plugins. You have to replicate these using our [Settings](#settings) and [Emulated plugins](#emulated-plugins).
Like real vim, VSCodeVim will take over your control keys. This behaviour can be adjusted with the [`useCtrlKeys`](#vimusectrlkeys) and [`handleKeys`](#vimhandlekeys) settings.
If you have configured `vim.useSystemClipboard: "true"`, we rely on [clipboardy](https://github.com/sindresorhus/clipboardy) which is dependent on `xsel`:
The settings documented here are a subset of the supported settings; the full list is described in the `Contributions` tab in the extensions menu of VSCode.
| vim.cursorStylePerMode._{Mode}_ | Configure a specific cursor style for _{Mode}_. Omitted modes will use [default cursor type](https://github.com/VSCodeVim/Vim/blob/4a6fde6dbd4d1fac1f204c0dc27c32883651ef1a/src/mode/mode.ts#L34) Supported cursors: line, block, underline, line-thin, block-outline, and underline-thin. | String | None |
| vim.debug.loggingLevel | Maximum level of messages to log. Logs are visible in the [developer tools](https://code.visualstudio.com/docs/extensions/developing-extensions#_developer-tools-console). Supported values: 'error', 'warn', 'info', 'verbose', 'debug'). | String | error |
| vim.disableExtension | Disable VSCodeVim extension. This setting can also be toggled using `toggleVim` command in the Command Palette | Boolean | false |
| vim.handleKeys | Delegate configured keys to be handled by VSCode instead of by the VSCodeVim extension. Any key in `keybindings` section of the [package.json](https://github.com/VSCodeVim/Vim/blob/master/package.json) that has a `vim.use<C-...>` in the when argument can be delegated back to VSCode by setting `"<C-...>": false`. Example: to use `ctrl+f` for find (native VSCode behaviour): `"vim.handleKeys": { "<C-f>": false }`. | String | `"<C-d>": true` |
| vim.overrideCopy | Override VSCode's copy command with our own, which works correctly with VSCodeVim. If cmd-c/ctrl-c is giving you issues, set this to false and complain [here](https://github.com/Microsoft/vscode/issues/217). | Boolean | false |
| vim.searchHighlightColor | Set the color of search highlights | String | rgba(150, 150, 150, 0.3) |
| vim.startInInsertMode | Start in Insert mode instead of Normal Mode | Boolean | false |
| vim.substituteGlobalFlag | Similar to Vim's `gdefault` setting. `/g` flag in a substitute command replaces all occurrences in the line. Without this flag, replacement occurs only for the first occurrence in each line. With this setting enabled, the `g` is on by default. | Boolean | false |
| vim.useCtrlKeys | Enable Vim ctrl keys overriding common VSCode operations such as copy, paste, find, etc. | Boolean | true |
| vim.visualstar | In visual mode, start a search with `*` or `#` using the current selection | Boolean | false |
- Bind `<leader>m` to add a bookmark and `<leader>b` to open the list of all bookmarks (using the [Bookmarks](https://github.com/alefragnani/vscode-bookmarks) extension):
- Non-recursive keybinding overrides to use for insert, normal, and visual modes
- _Example:_ Bind `j` to `gj`. Notice that if you attempted this binding normally, the j in gj would be expanded into gj, on and on forever. Stop this recursive expansion using insertModeKeyBindingsNonRecursive and/or normalModeKeyBindingNonRecursive.
VSCodeVim explicitly instructs VSCode which key events we care about through the [package.json](https://github.com/VSCodeVim/Vim/blob/1a5f358a1a57c62d5079093ad0dd12c2bf018bba/package.json#L53). If the key you are trying to remap is a key in which vim/vscodevim generally does not handle, then it's most likely that this extension does not receive those key events from VS Code. With [logging level](#vimdebuglogginglevel) adjusted to 'debug', as you press keys, you should see output similar to:
| vim.autoindent | Copy indent from current line when starting a new line | Boolean | true |
| vim.hlsearch | Highlights all text matching current search | Boolean | false |
| vim.ignorecase | Ignore case in search patterns | Boolean | true |
| vim.incsearch | Show the next match while entering a search | Boolean | true |
| vim.leader | Defines key for `<leader>` to be used in key remappings | String | `\` |
| vim.showcmd | Show (partial) command in status bar | Boolean | true |
| vim.showmodename | Show name of current mode in status bar | Boolean | true |
| vim.smartcase | Override the 'ignorecase' setting if search pattern contains uppercase characters | Boolean | true |
| vim.textwidth | Width to word-wrap when using `gq` | Number | 80 |
| vim.timeout | Timeout in milliseconds for remapped commands | Number | 1000 |
| vim.whichwrap | Controls wrapping at beginning and end of line. Comma-separated set of keys that should wrap to next/previous line. Arrow keys are represented by `[` and `]` in insert mode, `<` and `>` in normal and visual mode. To wrap "everything", set this to `h,l,<,>,[,]`. | String | `` |
-`gb`, a new shortcut we added which is equivalent to `cmd-d` (OSX) or `ctrl-d` (Windows). It adds another cursor at the next word that matches the word the cursor is currently on.
- Running "Add Cursor Above/Below" or the shortcut on any platform.
Once you have multiple cursors, you should be able to use Vim commands as you see fit. Most should work; some are unsupported (ref [PR#587](https://github.com/VSCodeVim/Vim/pull/587)).
> :warning: Experimental feature. Due to VSCode API limitations, this function modifies settings.json in the workspace resulting in latency and a constant changing diff in your working directory (see [issue#2124](https://github.com/VSCodeVim/Vim/issues/2124)).
Change the color of the status bar based on the current mode. Once enabled, configure `"vim.statusBarColors"`. Colors can be defined for each mode either as `string` (background only), or `string[]` (background, foreground).
Based on [vim-easymotion](https://github.com/easymotion/vim-easymotion). To activate easymotion, you need to make sure that `easymotion` is set to `true` in settings.json (default is `false`).
Once easymotion is active, initiate motions using the following commands. After you initiate the motion, text decorators/markers will be displayed and you can press the keys displayed to jump to that position. `leader` is configurable and is `\` by default.
| `vim.easymotionMarkerBackgroundColor` | The background color of the marker box. |
| `vim.easymotionMarkerForegroundColorOneChar` | The font color for one-character markers. |
| `vim.easymotionMarkerForegroundColorTwoChar` | The font color for two-character markers, used to differentiate from one-character markers. |
| `vim.easymotionMarkerWidthPerChar` | The width in pixels allotted to each character. |
| `vim.easymotionMarkerHeight` | The height of the marker. |
| `vim.easymotionMarkerFontFamily` | The font family used for the marker text. |
| `vim.easymotionMarkerFontSize` | The font size used for the marker text. |
| `vim.easymotionMarkerFontWeight` | The font weight used for the marker text. |
| `vim.easymotionMarkerYOffset` | The distance between the top of the marker and the text (will typically need some adjusting if height or font size have been changed). |
| `vim.easymotionKeys` | The characters used for jump marker name |
| `vim.easymotionJumpToAnywhereRegex` | Custom regex to match for JumpToAnywhere motion (analogous to `Easymotion_re_anywhere`). Example setting (which also matches start & end of line, as well as Javascript comments in addition to the regular behavior (note the double escaping required): ^\\s\*. | \\b[A-Za-z0-9] | [A-Za-z0-9]\\b | \_. | \\#. | [a-z][a-z] | // | .$" |
Based on [surround.vim](https://github.com/tpope/vim-surround), the plugin is used to work with surrounding characters like parenthesis, brackets, quotes, and XML tags.
Similar to [vim-commentary](https://github.com/tpope/vim-commentary), but uses the VSCode native "Toggle Line Comment" and "Toggle Block Comment" features.
-`gc` - toggles line comment. For example `gcc` to toggle line comment for current line and `gc2j` to toggle line comments for the current line and the next two lines.
-`gC` - toggles block comment. For example `gCi)` to comment out everything within parenthesis.
Based on [vim-indent-object](https://github.com/michaeljsmith/vim-indent-object), it allows for treating blocks of code at the current indentation level as text objects. Useful in languages that don't use braces around statements (e.g. Python).
Based on [vim-sneak](https://github.com/justinmk/vim-sneak). To activate sneak, you need to make sure that `sneak` is set to `true` in settings.json (default is `false`).
`"vim.sneakUseIgnorecaseAndSmartcase": true` can be set if desired to allow for respecting `vim.ignorecase` and `vim.smartcase` while sneaking (default is `false`)
Once sneak is active, initiate motions using the following commands. For operators sneak uses `z` instead of `s` because `s` is already taken by the surround plugin.
You can use any third-party program to switch input methods. We recommend [im-select](https://github.com/daipeihust/im-select), and the following will walkthrough installation and configuration for im-select.
For most people, their default input method key is 1033, the locale ID of en_US. But if your default keyboard layout is not en_US, you can use im-select.exe to find out, the guide is [here](https://github.com/daipeihust/im-select#to-get-current-keyboard-locale). You can also find your locale ID in [this page](https://www.science.co.il/language/Locale-codes.php), the `LCID Decimal` column is the locale ID.
If using an alternative program to switch input methods and it requires a command-line options to switch or get the input method, you should add the options to the configuration. For example, if your program's usage is `my-program -s imKey` to switch input method, your `vim.autoSwitchInputMethod.switchIMCmd` should be `/path/to/my-program -s {im}`.
-`gq` - on a visual selection reflow and wordwrap blocks of text, preserving commenting style. Great for formatting documentation comments.
-`gb` - adds another cursor on the next word it finds which is the same as the word under the cursor.
-`af` - visual mode command which selects increasingly large blocks of text. For example, if you had "blah (foo [bar 'ba|z'])" then it would select 'baz' first. If you pressed `af` again, it'd then select [bar 'baz'], and if you did it a third time it would select "(foo [bar 'baz'])".
-`gh` - equivalent to hovering your mouse over wherever the cursor is. Handy for seeing types and error messages without reaching for the mouse!
Try setting `vim.foldfix` to `true`. This is a hack; it works fine, but there are side effects (see [issue#22276](https://github.com/Microsoft/vscode/issues/22276)).
This extension exposes a remappable command to show a vscode style quick-pick, limited functionality, version of the commandline. This can be remapped as follows in visual studio keybindings.json settings file.
This project is maintained by a group of awesome [people](https://github.com/VSCodeVim/Vim/graphs/contributors) and contributions are extremely welcome :heart:. For a quick tutorial on how you can help, see our [contributing guide](/.github/CONTRIBUTING.md).
- Thanks to @xconverge for making over 100 commits to the repo. If you're wondering why your least favorite bug packed up and left, it was probably him.
- Thanks to @Metamist for implementing EasyMotion!
- Thanks to @sectioneight for implementing text objects!
- Special props to [Kevin Coleman](http://kevincoleman.io), who created our awesome logo!
- Shoutout to @chillee aka Horace He for his contributions and hard work.
