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 [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
81Vim's macro support (`q` and `@`) is implemented using Zed's actions. This lets us support recording and replaying of autocompleted code, etc. Unlike Vim, Zed does not re-use the yank registers for recording macros, they are two separate namespaces.
82
83Finally, 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.
84
85## Custom key bindings
86
87You can edit your personal key bindings with `:keymap`.
88For vim-specific shortcuts, you may find the following template a good place to start.
89
90> **Note:** We made some breaking changes in Zed version `0.145.0`. For older versions, see [the previous version of this document](https://github.com/zed-industries/zed/blob/c67aeaa9c58619a58708722ac7d7a78c75c29336/docs/src/vim.md#L90).
91
92```json
93[
94 {
95 "context": "VimControl && !menu",
96 "bindings": {
97 // put key-bindings here if you want them to work in normal & visual mode
98 }
99 },
100 {
101 "context": "vim_mode == insert",
102 "bindings": {
103 // "j k": "vim::NormalBefore" // remap jk in insert mode to escape.
104 }
105 },
106 {
107 "context": "EmptyPane || SharedScreen",
108 "bindings": {
109 // put key-bindings here (in addition to above) if you want them to
110 // work when no editor exists
111 // "space f": "file_finder::Toggle"
112 }
113 }
114]
115```
116
117If 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.
118
119You 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).
120
121#### Contexts
122
123Zed's keyboard bindings are evaluated only when the `"context"` matches the location you are in on the screen. Locations are nested, so when you're editing you're in the `"Workspace"` location is at the top, containing a `"Pane"` which contains an `"Editor"`. Contexts are matched only on one level at a time. So it is possible to combine `Editor && vim_mode == normal`, but `Workspace && vim_mode == normal` will never match because we set the vim context at the `Editor` level.
124
125Vim mode adds several contexts to the `Editor`:
126
127- `vim_mode` is similar to, but not identical to, the current mode. It starts as one of `normal`, `visual`, `insert` or `replace` (depending on your mode). If you are mid-way through typing a sequence, `vim_mode` will be either `waiting` if it's waiting for an arbitrary key (for example after typing `f` or `t`), or `operator` if it's waiting for another binding to trigger (for example after typing `c` or `d`).
128- `vim_operator` is set to `none` unless `vim_mode == operator` in which case it is set to the current operator's default keybinding (for example after typing `d`, `vim_operator == d`).
129- `"VimControl"` indicates that vim keybindings should work. It is currently an alias for `vim_mode == normal || vim_mode == visual || vim_mode == operator`, but the definition may change over time.
130
131### Restoring some sense of normality
132
133If you're using Vim mode on Linux or Windows, you may find that it has overridden keybindings
134that you can't live without. You can restore them to their defaults by copying these into your keymap:
135
136```
137{
138 "context": "Editor && !menu",
139 "bindings": {
140 "ctrl-c": "editor::Copy", // vim default: return to normal mode
141 "ctrl-x": "editor::Cut", // vim default: decrement
142 "ctrl-v": "editor::Paste", // vim default: visual block mode
143 "ctrl-y": "editor::Undo", // vim default: line up
144 "ctrl-f": "buffer_search::Deploy", // vim default: page down
145 "ctrl-o": "workspace::Open", // vim default: go back
146 "ctrl-a": "editor::SelectAll", // vim default: increment
147 }
148},
149```
150
151## Command palette
152
153Vim 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.
154
155Additionally 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.
156
157We 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.
158
159As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
160
161Currently supported vim-specific commands:
162
163```
164# window management
165:w[rite][!], :wq[!], :q[uit][!], :wa[ll][!], :wqa[ll][!], :qa[ll][!], :[e]x[it][!], :up[date]
166 to save/close tab(s) and pane(s) (no filename is supported yet)
167:cq
168 to quit completely.
169:vs[plit], :sp[lit]
170 to split vertically/horizontally (no filename is supported yet)
171:new, :vne[w]
172 to create a new file in a new pane above or to the left
173:tabedit, :tabnew
174 to create a new file in a new tab.
175:tabn[ext], :tabp[rev]
176 to go to previous/next tabs
177:tabc[lose]
178 to close the current tab
179
180# navigating diagnostics
181:cn[ext], :cp[rev], :ln[ext], :lp[rev]
182 to go to the next/prev diagnostics
183:cc, :ll
184 to open the errors page
185
186# jump to position
187:<number>
188 to jump to a line number
189:$
190 to jump to the end of the file
191:/foo and :?foo
192 to jump to next/prev line matching foo
193
194# replacement (/g is always assumed and Zed uses different regex syntax to vim)
195:%s/foo/bar/
196 to replace instances of foo with bar
197:X,Ys/foo/bar/
198 to limit replacement between line X and Y
199 other ranges are not yet implemented
200
201# editing
202:j[oin]
203 to join the current line (no range is yet supported)
204:d[elete][l][p]
205 to delete the current line (no range is yet supported)
206:s[ort] [i]
207 to sort the current selection (with i, case-insensitively)
208```
209
210As any Zed command is available, you may find that it's helpful to remember mnemonics that run the correct command. For example:
211
212```
213:diff Toggle Hunk [Diff]
214:diffs Toggle all Hunk [Diffs]
215:revert Revert Selected Hunks
216:cpp [C]o[p]y [P]ath to file
217:crp [C]opy [r]elative [P]ath
218:reveal [Reveal] in finder
219:zlog Open [Z]ed Log
220```
221
222## Settings
223
224Vim mode is not enabled by default. To enable Vim mode, you need to add the following configuration to your settings file:
225
226```json
227{
228 "vim_mode": true
229}
230```
231
232Alternatively, you can enable Vim mode by running the `toggle vim mode` command from the command palette.
233
234Some vim settings are available to modify the default vim behavior:
235
236```json
237{
238 "vim": {
239 // "always": use system clipboard when no register is specified
240 // "never": don't use system clipboard unless "+ or "* is specified
241 // "on_yank": use system clipboard for yank operations when no register is specified
242 "use_system_clipboard": "always",
243 // Lets `f` and `t` motions extend across multiple lines
244 "use_multiline_find": true
245 }
246}
247```
248
249There are also a few Zed settings that you may also enjoy if you use vim mode:
250
251```json
252{
253 // disable cursor blink
254 "cursor_blink": false,
255 // use relative line numbers
256 "relative_line_numbers": true,
257 // hide the scroll bar
258 "scrollbar": { "show": "never" },
259 // allow cursor to reach edges of screen
260 "vertical_scroll_margin": 0,
261 "gutter": {
262 // disable line numbers completely:
263 "line_numbers": false
264 },
265 "command_aliases": {
266 "W": "w",
267 "Wq": "wq",
268 "Q": "q"
269 }
270}
271```
272
273If 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:
274
275```json
276{
277 "context": "Dock",
278 "bindings": {
279 "ctrl-w h": ["workspace::ActivatePaneInDirection", "Left"],
280 "ctrl-w l": ["workspace::ActivatePaneInDirection", "Right"],
281 "ctrl-w k": ["workspace::ActivatePaneInDirection", "Up"],
282 "ctrl-w j": ["workspace::ActivatePaneInDirection", "Down"]
283 // ... or other keybindings
284 }
285}
286```
287
288Subword motion is not enabled by default. To enable it, add these bindings to your keymap.
289
290```json
291 {
292 "context": "VimControl && !menu",
293 "bindings": {
294 "w": "vim::NextSubwordStart",
295 "b": "vim::PreviousSubwordStart",
296 "e": "vim::NextSubwordEnd",
297 "g e": "vim::PreviousSubwordEnd"
298 }
299 },
300```
301
302Surrounding the selection in visual mode is also not enabled by default (`shift-s` normally behaves like `c`). To enable it, add the following to your keymap.
303
304```json
305{
306 "context": "vim_mode == visual",
307 "bindings": {
308 "shift-s": [
309 "vim::PushOperator",
310 {
311 "AddSurrounds": {}
312 }
313 ]
314 }
315}
316```
317
318## Supported plugins
319
320Zed has nascent support for some Vim plugins:
321
322- From `vim-surround`, `ys`, `cs` and `ds` work. Though you cannot add new HTML tags yet.
323- From `vim-commentary`, `gc` in visual mode and `gcc` in normal mode. Though you cannot operate on arbitrary objects yet.
324- From `netrw`, most keybindings are supported in the project panel.
325- From `vim-spider`/`CamelCaseMotion` you can use subword motions as described above.
326
327## Regex differences
328
329Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
330
331Notably:
332
333- Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
334- On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
335- When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
336- Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
337- 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`.
338
339To 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".
340
341For the full syntax supported by Zed's regex engine see the [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).