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 <space> Open the current search excerpt
52<ctrl-w> <space> Open the current search excerpt in a split
53<ctrl-w> g d Go to definition in a split
54<ctrl-w> g D Go to type definition in a split
55
56# Insert mode
57ctrl-x ctrl-o Open the completion menu
58ctrl-x ctrl-c Request GitHub Copilot suggestion (if configured)
59ctrl-x ctrl-a Open the inline AI assistant (if configured)
60ctrl-x ctrl-l Open the code actions menu
61ctrl-x ctrl-z Hides all suggestions
62
63# Ex commands
64:E[xplore] Open the project panel
65:C[ollab] Open the collaboration panel
66:Ch[at] Open the chat panel
67:A[I] Open the AI panel
68:No[tif] Open the notifications panel
69:fe[edback] Open the feedback window
70:cl[ist] Open the diagnostics window
71:te[rm] Open the terminal
72:Ext[ensions] Open the extensions window
73```
74
75Vim 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.
76
77Vim mode emulates visual block mode using Zed's multiple cursor support. This again leads to some differences, but is much more powerful.
78
79Finally, 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.
80
81## Custom key bindings
82
83You can edit your personal key bindings with `:keymap`.
84For vim-specific shortcuts, you may find the following template a good place to start:
85
86```json
87[
88 {
89 "context": "Editor && (vim_mode == normal || vim_mode == visual) && !VimWaiting && !menu",
90 "bindings": {
91 // put key-bindings here if you want them to work in normal & visual mode
92 }
93 },
94 {
95 "context": "Editor && vim_mode == normal && !VimWaiting && !menu",
96 "bindings": {
97 // put key-bindings here if you want them to work only in normal mode
98 // "down": ["workspace::SendKeystrokes", "4 j"]
99 // "up": ["workspace::SendKeystrokes", "4 k"]
100 }
101 },
102 {
103 "context": "Editor && vim_mode == visual && !VimWaiting && !menu",
104 "bindings": {
105 // visual, visual line & visual block modes
106 }
107 },
108 {
109 "context": "Editor && vim_mode == insert && !menu",
110 "bindings": {
111 // put key-bindings here if you want them to work in insert mode
112 // e.g.
113 // "j j": "vim::NormalBefore" // remap jj in insert mode to escape.
114 }
115 }
116]
117```
118
119If 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.
120
121You 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).
122
123The 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.
124
125### Examples
126
127Binding `jk` to exit insert mode and go to normal mode:
128
129```
130{
131 "context": "Editor && vim_mode == insert && !menu",
132 "bindings": {
133 "j k": ["vim::SwitchMode", "Normal"]
134 }
135}
136```
137
138## Command palette
139
140Vim 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.
141
142Additionally 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.
143
144We 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.
145
146As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
147
148Currently supported vim-specific commands:
149
150```
151# window management
152:w[rite][!], :wq[!], :q[uit][!], :wa[ll][!], :wqa[ll][!], :qa[ll][!], :[e]x[it][!], :up[date]
153 to save/close tab(s) and pane(s) (no filename is supported yet)
154:cq
155 to quit completely.
156:vs[plit], :sp[lit]
157 to split vertically/horizontally (no filename is supported yet)
158:new, :vne[w]
159 to create a new file in a new pane above or to the left
160:tabedit, :tabnew
161 to create a new file in a new tab.
162:tabn[ext], :tabp[rev]
163 to go to previous/next tabs
164:tabc[lose]
165 to close the current tab
166
167# navigating diagnostics
168:cn[ext], :cp[rev], :ln[ext], :lp[rev]
169 to go to the next/prev diagnostics
170:cc, :ll
171 to open the errors page
172
173# jump to position
174:<number>
175 to jump to a line number
176:$
177 to jump to the end of the file
178:/foo and :?foo
179 to jump to next/prev line matching foo
180
181# replacement (/g is always assumed and Zed uses different regex syntax to vim)
182:%s/foo/bar/
183 to replace instances of foo with bar
184:X,Ys/foo/bar/
185 to limit replcaement between line X and Y
186 other ranges are not yet implemented
187
188# editing
189:j[oin]
190 to join the current line (no range is yet supported)
191:d[elete][l][p]
192 to delete the current line (no range is yet supported)
193:s[ort] [i]
194 to sort the current selection (with i, case-insensitively)
195```
196
197As any Zed command is available, you may find that it's helpful to remember mnemonics that run the correct command. For example:
198
199```
200:diff Toggle Hunk [Diff]
201:diffs Toggle all Hunk [Diffs]
202:revert Revert Selected Hunks
203:cpp [C]o[p]y [P]ath to file
204:crp [C]opy [r]elative [P]ath
205:reveal [Reveal] in finder
206:zlog Open [Z]ed Log
207```
208
209## Settings
210
211Some vim settings are available to modify the default vim behavior:
212
213```json
214{
215 "vim": {
216 // "always": use system clipboard
217 // "never": don't use system clipboard
218 // "on_yank": use system clipboard for yank operations
219 "use_system_clipboard": "always",
220 // Lets `f` and `t` motions extend across multiple lines
221 "use_multiline_find": true
222 }
223}
224```
225
226There are also a few Zed settings that you may also enjoy if you use vim mode:
227
228```json
229{
230 // disable cursor blink
231 "cursor_blink": false,
232 // use relative line numbers
233 "relative_line_numbers": true,
234 // hide the scroll bar
235 "scrollbar": { "show": "never" },
236 // allow cursor to reach edges of screen
237 "vertical_scroll_margin": 0,
238 "gutter": {
239 // disable line numbers completely:
240 "line_numbers": false
241 }
242}
243```
244
245If 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:
246
247```json
248{
249 "context": "Dock",
250 "bindings": {
251 "ctrl-w h": ["workspace::ActivatePaneInDirection", "Left"],
252 "ctrl-w l": ["workspace::ActivatePaneInDirection", "Right"],
253 "ctrl-w k": ["workspace::ActivatePaneInDirection", "Up"],
254 "ctrl-w j": ["workspace::ActivatePaneInDirection", "Down"]
255 // ... or other keybindings
256 }
257}
258```
259
260Subword motion is not enabled by default. To enable it, add these bindings to your keymap.
261
262```json
263 {
264 "context": "Editor && VimControl && !VimWaiting && !menu",
265 "bindings": {
266 "w": "vim::NextSubwordStart",
267 "b": "vim::PreviousSubwordStart",
268 "e": "vim::NextSubwordEnd",
269 "g e": "vim::PreviousSubwordEnd"
270 }
271 },
272```
273
274## Supported plugins
275
276Zed has nascent support for some Vim plugins:
277
278- From `vim-surround`, `ys`, `cs` and `ds` work. Though you cannot add new HTML tags yet.
279- From `vim-commentary`, `gc` in visual mode and `gcc` in normal mode. Though you cannot operate on arbitrary objects yet.
280- From `netrw`, most keybindings are supported in the project panel.
281- From `vim-spider`/`CamelCaseMotion` you can use subword motions as described above.
282
283## Regex differences
284
285Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
286
287Notably:
288
289- Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
290- On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
291- When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
292- Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
293- 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`.
294
295To 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".
296
297For the full syntax supported by Zed's regex engine see the [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).