1# Vim Mode
  2
  3Zed includes a vim emulation layer known as "vim mode". This document aims to describe how it works, and how to make the most out of it.
  4
  5## Philosophy
  6
  7Vim mode in Zed is supposed to primarily "do what you expect": it mostly tries to copy vim exactly, but will use Zed-specific functionality when available to make things smoother.
  8
  9This means Zed will never be 100% Vim compatible, but should be 100% Vim familiar! We expect that our Vim mode already copes with 90% of your workflow, and we'd like to keep improving it. If you find things that you can’t yet do in Vim mode, but which you rely on in your current workflow, please leave feedback in the editor itself (`:feedback`), or [file an issue](https://github.com/zed-industries/zed/issues).
 10
 11## Zed-specific features
 12
 13Zed is built on a modern foundation that (among other things) uses tree-sitter and language servers to understand the content of the file you're editing, and supports multiple cursors out of the box.
 14
 15Vim mode has several "core Zed" key bindings, that will help you make the most of Zed's specific feature set.
 16
 17```
 18# Language server
 19g d     Go to definition
 20g D     Go to type definition
 21g cmd-d Go to implementation
 22c d     Rename (change definition)
 23g A     Go to All references to the current word
 24
 25g s   Find symbol in current file
 26g S   Find symbol in entire project
 27
 28g ]   Go to next diagnostic
 29g [   Go to previous diagnostic
 30] d   Go to next diagnostic
 31[ d   Go to previous diagnostic
 32g h   Show inline error (hover)
 33g .   Open the code actions menu
 34
 35# Git
 36] c   Go to next git change
 37[ c   Go to previous git change
 38
 39# Treesitter
 40] x   Select a smaller syntax node
 41[ x   Select a larger syntax node
 42
 43# Multi cursor
 44g l   Add a visual selection for the next copy of the current word
 45g L   The same, but backwards
 46g >   Skip latest word selection, and add next.
 47g <   The same, but backwards
 48g a   Add a visual selection for every copy of the current word
 49
 50# Pane management
 51g /        Open a project-wide search
 52g <space>  Open the current search excerpt
 53<ctrl-w> <space>  Open the current search excerpt in a split
 54<ctrl-w> g d      Go to definition in a split
 55<ctrl-w> g D      Go to type definition in a split
 56
 57# Insert mode
 58i a / a a      Select the function argument the cursor is in
 59ctrl-x ctrl-o  Open the completion menu
 60ctrl-x ctrl-c  Request GitHub Copilot suggestion (if configured)
 61ctrl-x ctrl-a  Open the inline AI assistant (if configured)
 62ctrl-x ctrl-l  Open the code actions menu
 63ctrl-x ctrl-z  Hides all suggestions
 64
 65# Ex commands
 66:E[xplore]    Open the project panel
 67:C[ollab]     Open the collaboration panel
 68:Ch[at]       Open the chat panel
 69:A[I]         Open the AI panel
 70:No[tif]      Open the notifications panel
 71:fe[edback]   Open the feedback window
 72:cl[ist]      Open the diagnostics window
 73:te[rm]       Open the terminal
 74:Ext[ensions] Open the extensions window
 75```
 76
 77Vim mode uses Zed to define concepts like "brackets" (for the `%` key) and "words" (for motions like `w` and `e`). This does lead to some differences, but they are mostly positive. For example `%` considers `|` to be a bracket in languages like Rust; and `w` considers `$` to be a word-character in languages like Javascript.
 78
 79Vim mode emulates visual block mode using Zed's multiple cursor support. This again leads to some differences, but is much more powerful.
 80
 81Finally, Vim mode's search and replace functionality is backed by Zed's. This means that the pattern syntax is slightly different, see the section on [Regex differences](#regex-differences) for details.
 82
 83## Custom key bindings
 84
 85You can edit your personal key bindings with `:keymap`.
 86For vim-specific shortcuts, you may find the following template a good place to start:
 87
 88```json
 89[
 90  {
 91    "context": "Editor && (vim_mode == normal || vim_mode == visual) && !VimWaiting && !menu",
 92    "bindings": {
 93      // put key-bindings here if you want them to work in normal & visual mode
 94    }
 95  },
 96  {
 97    "context": "Editor && vim_mode == normal && !VimWaiting && !menu",
 98    "bindings": {
 99      // put key-bindings here if you want them to work only in normal mode
100      // "down": ["workspace::SendKeystrokes", "4 j"]
101      // "up": ["workspace::SendKeystrokes", "4 k"]
102    }
103  },
104  {
105    "context": "Editor && vim_mode == visual && !VimWaiting && !menu",
106    "bindings": {
107      // visual, visual line & visual block modes
108    }
109  },
110  {
111    "context": "Editor && vim_mode == insert && !menu",
112    "bindings": {
113      // put key-bindings here if you want them to work in insert mode
114      // e.g.
115      // "j j": "vim::NormalBefore" // remap jj in insert mode to escape.
116    }
117  }
118]
119```
120
121If you would like to emulate vim's `map` (`nmap` etc.) commands you can bind to the [`workspace::SendKeystrokes`](/docs/key-bindings#remapping-keys) action in the correct context.
122
123You can see the bindings that are enabled by default in vim mode [here](https://github.com/zed-industries/zed/blob/main/assets/keymaps/vim.json).
124
125The details of the context are a little out of scope for this doc, but suffice to say that `menu` is true when a menu is open (e.g. the completions menu), `VimWaiting` is true after you type `f` or `t` when we’re waiting for a new key (and you probably don’t want bindings to happen). Please reach out on [GitHub](https://github.com/zed-industries/zed) if you want help making a key bindings work.
126
127### Examples
128
129Binding `jk` to exit insert mode and go to normal mode:
130
131```
132{
133  "context": "Editor && vim_mode == insert && !menu",
134  "bindings": {
135    "j k": ["vim::SwitchMode", "Normal"]
136  }
137}
138```
139
140## Command palette
141
142Vim mode allows you to enable Zed’s command palette with `:`. This means that you can use vim's command palette to run any action that Zed supports.
143
144Additionally vim mode contains a number of aliases for popular vim commands to ensure that muscle memory works. For example `:w<enter>` will save the file.
145
146We do not (yet) emulate the full power of vim’s command line, in particular we special case specific patterns instead of using vim's range selection syntax, and we do not support arguments to commands yet. Please reach out on [GitHub](https://github.com/zed-industries/zed) as you find things that are missing from the command palette.
147
148As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
149
150Currently supported vim-specific commands:
151
152```
153# window management
154:w[rite][!], :wq[!], :q[uit][!], :wa[ll][!], :wqa[ll][!], :qa[ll][!], :[e]x[it][!], :up[date]
155    to save/close tab(s) and pane(s) (no filename is supported yet)
156:cq
157    to quit completely.
158:vs[plit], :sp[lit]
159    to split vertically/horizontally (no filename is supported yet)
160:new, :vne[w]
161    to create a new file in a new pane above or to the left
162:tabedit, :tabnew
163    to create a new file in a new tab.
164:tabn[ext], :tabp[rev]
165    to go to previous/next tabs
166:tabc[lose]
167    to close the current tab
168
169# navigating diagnostics
170:cn[ext], :cp[rev], :ln[ext], :lp[rev]
171    to go to the next/prev diagnostics
172:cc, :ll
173    to open the errors page
174
175# jump to position
176:<number>
177    to jump to a line number
178:$
179    to jump to the end of the file
180:/foo and :?foo
181    to jump to next/prev line matching foo
182
183# replacement (/g is always assumed and Zed uses different regex syntax to vim)
184:%s/foo/bar/
185  to replace instances of foo with bar
186:X,Ys/foo/bar/
187    to limit replcaement between line X and Y
188    other ranges are not yet implemented
189
190# editing
191:j[oin]
192    to join the current line (no range is yet supported)
193:d[elete][l][p]
194    to delete the current line (no range is yet supported)
195:s[ort] [i]
196    to sort the current selection (with i, case-insensitively)
197```
198
199As any Zed command is available, you may find that it's helpful to remember mnemonics that run the correct command. For example:
200
201```
202:diff    Toggle Hunk [Diff]
203:diffs    Toggle all Hunk [Diffs]
204:revert  Revert Selected Hunks
205:cpp  [C]o[p]y [P]ath to file
206:crp  [C]opy [r]elative [P]ath
207:reveal [Reveal] in finder
208:zlog Open [Z]ed Log
209```
210
211## Settings
212
213Some vim settings are available to modify the default vim behavior:
214
215```json
216{
217  "vim": {
218    // "always": use system clipboard
219    // "never": don't use system clipboard
220    // "on_yank": use system clipboard for yank operations
221    "use_system_clipboard": "always",
222    // Lets `f` and `t` motions extend across multiple lines
223    "use_multiline_find": true
224  }
225}
226```
227
228There are also a few Zed settings that you may also enjoy if you use vim mode:
229
230```json
231{
232  // disable cursor blink
233  "cursor_blink": false,
234  // use relative line numbers
235  "relative_line_numbers": true,
236  // hide the scroll bar
237  "scrollbar": { "show": "never" },
238  // allow cursor to reach edges of screen
239  "vertical_scroll_margin": 0,
240  "gutter": {
241    // disable line numbers completely:
242    "line_numbers": false
243  }
244}
245```
246
247If you want to navigate between the editor and docks (terminal, project panel, AI assistant, ...) just like you navigate between splits you can use the following key bindings:
248
249```json
250{
251  "context": "Dock",
252  "bindings": {
253    "ctrl-w h": ["workspace::ActivatePaneInDirection", "Left"],
254    "ctrl-w l": ["workspace::ActivatePaneInDirection", "Right"],
255    "ctrl-w k": ["workspace::ActivatePaneInDirection", "Up"],
256    "ctrl-w j": ["workspace::ActivatePaneInDirection", "Down"]
257    // ... or other keybindings
258  }
259}
260```
261
262Subword motion is not enabled by default. To enable it, add these bindings to your keymap.
263
264```json
265  {
266    "context": "Editor && VimControl && !VimWaiting && !menu",
267    "bindings": {
268      "w": "vim::NextSubwordStart",
269      "b": "vim::PreviousSubwordStart",
270      "e": "vim::NextSubwordEnd",
271      "g e": "vim::PreviousSubwordEnd"
272    }
273  },
274```
275
276## Supported plugins
277
278Zed has nascent support for some Vim plugins:
279
280- From `vim-surround`, `ys`, `cs` and `ds` work. Though you cannot add new HTML tags yet.
281- From `vim-commentary`, `gc` in visual mode and `gcc` in normal mode. Though you cannot operate on arbitrary objects yet.
282- From `netrw`, most keybindings are supported in the project panel.
283- From `vim-spider`/`CamelCaseMotion` you can use subword motions as described above.
284
285## Regex differences
286
287Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
288
289Notably:
290
291- Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
292- On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
293- When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
294- Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
295- Vim uses `/i` to indicate "case-insensitive", in Zed you can either use `(?i)` at the start of the pattern or toggle case-sensitivity with `cmd-option-c`.
296
297To help with the transition, the command palette will fix parentheses and replace groups for you when you run `:%s//`. So `%s:/\(a\)(b)/\1/` will be converted into a search for "(a)\(b\)" and a replacement of "$1".
298
299For the full syntax supported by Zed's regex engine see the [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).