mirror of
https://github.com/zed-industries/zed.git
synced 2024-11-24 06:19:37 +00:00
Restore vim docs (#11491)
These got reset to the wrong version as part of the docs migration Release Notes: - N/A
This commit is contained in:
Conrad Irwin
GitHub
parent
72c47b7f01
commit
ceab446409
2 changed files with 105 additions and 42 deletions
146
docs/src/vim.md
146
docs/src/vim.md
|
|
@ -1,6 +1,6 @@
|
|||
# Vim Mode
|
||||
|
||||
Zed 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.
|
||||
Zed 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.
|
||||
|
||||
## Philosophy
|
||||
|
||||
|
|
@ -10,36 +10,59 @@ This means Zed will never be 100% vim compatible, but should be 100% vim familia
|
|||
|
||||
## Zed-specific features
|
||||
|
||||
Zed is built on a modern foundation that (among other things) uses tree-sitter to understand the content of the file you're editing, and supports multiple cursors out of the box.
|
||||
Zed 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.
|
||||
|
||||
Vim mode has several "core Zed" key bindings, that will help you make the most of Zed's specific feature set.
|
||||
|
||||
```
|
||||
# Normal mode
|
||||
# Language server
|
||||
g d Go to definition
|
||||
g D Go to type definition
|
||||
c d Rename (change definition)
|
||||
g A Go to All references to the current word
|
||||
|
||||
g <space> Open the current search excerpt in its own tab
|
||||
|
||||
g s Find symbol in current file
|
||||
g S Find symbol in entire project
|
||||
|
||||
g n Add a visual selection for the next copy of the current word
|
||||
g N The same, but backwards
|
||||
g ] Go to next diagnostic
|
||||
g [ Go to previous diagnostic
|
||||
g h Show inline error (hover)
|
||||
g . Open the code actions menu
|
||||
|
||||
# Treesitter
|
||||
] x Select a smaller syntax node
|
||||
[ x Select a larger syntax node
|
||||
|
||||
# Multi cursor
|
||||
g l Add a visual selection for the next copy of the current word
|
||||
g L The same, but backwards
|
||||
g > Skip latest word selection, and add next.
|
||||
g < The same, but backwards
|
||||
g a Add a visual selection for every copy of the current word
|
||||
|
||||
g h Show inline error (hover)
|
||||
# Pane management
|
||||
g <space> Open the current search excerpt
|
||||
<ctrl-w> <space> Open the current search excerpt in a split
|
||||
<ctrl-w> g d Go to definition in a split
|
||||
<ctrl-w> g D Go to type definition in a split
|
||||
|
||||
# Insert mode
|
||||
ctrl-x ctrl-o Open the completion menu
|
||||
ctrl-x ctrl-c Request GitHub Copilot suggestion (if configured)
|
||||
ctrl-x ctrl-a Open the inline AI assistant (if configured)
|
||||
ctrl-x ctrl-l Open the LSP code actions
|
||||
ctrl-x ctrl-l Open the code actions menu
|
||||
ctrl-x ctrl-z Hides all suggestions
|
||||
|
||||
# Ex commands
|
||||
:E[xplore] Open the project panel
|
||||
:C[ollab] Open the collaboration panel
|
||||
:Ch[at] Open the chat panel
|
||||
:A[I] Open the AI panel
|
||||
:No[tif] Open the notifications panel
|
||||
:fe[edback] Open the feedback window
|
||||
:cl[ist] Open the diagnostics window
|
||||
:te[rm] Open the terminal
|
||||
:Ext[ensions] Open the extensions window
|
||||
```
|
||||
|
||||
Vim 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.
|
||||
|
|
@ -50,15 +73,13 @@ Finally, Vim mode's search and replace functionality is backed by Zed's. This me
|
|||
|
||||
## Custom key bindings
|
||||
|
||||
Zed does not yet have an equivalent to vim’s `map` command to convert one set of keystrokes into another, however you can bind any sequence of keys to fire any Action documented in the [Key bindings documentation](https://zed.dev/docs/key-bindings).
|
||||
|
||||
You can edit your personal key bindings with `:keymap`.
|
||||
For vim-specific shortcuts, you may find the following template a good place to start:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"context": "Editor && VimControl && !VimWaiting && !menu",
|
||||
"context": "Editor && (vim_mode == normal || vim_mode == visual) && !VimWaiting && !menu",
|
||||
"bindings": {
|
||||
// put key-bindings here if you want them to work in normal & visual mode
|
||||
}
|
||||
|
|
@ -67,6 +88,8 @@ For vim-specific shortcuts, you may find the following template a good place to
|
|||
"context": "Editor && vim_mode == normal && !VimWaiting && !menu",
|
||||
"bindings": {
|
||||
// put key-bindings here if you want them to work only in normal mode
|
||||
// "down": ["workspace::SendKeystrokes", "4 j"]
|
||||
// "up": ["workspace::SendKeystrokes", "4 k"]
|
||||
}
|
||||
},
|
||||
{
|
||||
|
|
@ -79,12 +102,16 @@ For vim-specific shortcuts, you may find the following template a good place to
|
|||
"context": "Editor && vim_mode == insert && !menu",
|
||||
"bindings": {
|
||||
// put key-bindings here if you want them to work in insert mode
|
||||
// e.g.
|
||||
// "j j": "vim::NormalBefore" // remap jj in insert mode to escape.
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
You can see the bindings that are enabled by default in vim mode [here](https://zed.dev/ref/vim.json).
|
||||
If 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.
|
||||
|
||||
You 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).
|
||||
|
||||
The 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.
|
||||
|
||||
|
|
@ -101,22 +128,6 @@ Binding `jk` to exit insert mode and go to normal mode:
|
|||
}
|
||||
```
|
||||
|
||||
## Subword motion
|
||||
|
||||
Subword motion is not enabled by default. To enable it, add these bindings to your keymap.
|
||||
|
||||
```json
|
||||
{
|
||||
"context": "Editor && VimControl && !VimWaiting && !menu",
|
||||
"bindings": {
|
||||
"w": "vim::NextSubwordStart",
|
||||
"b": "vim::PreviousSubwordStart",
|
||||
"e": "vim::NextSubwordEnd",
|
||||
"g e": "vim::PreviousSubwordEnd"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## Command palette
|
||||
|
||||
Vim 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.
|
||||
|
|
@ -127,7 +138,7 @@ We do not (yet) emulate the full power of vim’s command line, in particular we
|
|||
|
||||
As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
|
||||
|
||||
Currently supported vim-specific commands (as of Zed 0.106):
|
||||
Currently supported vim-specific commands:
|
||||
|
||||
```
|
||||
# window management
|
||||
|
|
@ -160,9 +171,12 @@ Currently supported vim-specific commands (as of Zed 0.106):
|
|||
:/foo and :?foo
|
||||
to jump to next/prev line matching foo
|
||||
|
||||
# replacement
|
||||
# replacement (/g is always assumed and Zed uses different regex syntax to vim)
|
||||
:%s/foo/bar/
|
||||
to replace instances of foo with bar (/g is always assumed, the range must always be %, and Zed uses different regex syntax to vim)
|
||||
to replace instances of foo with bar
|
||||
:X,Ys/foo/bar/
|
||||
to limit replcaement between line X and Y
|
||||
other ranges are not yet implemented
|
||||
|
||||
# editing
|
||||
:j[oin]
|
||||
|
|
@ -173,7 +187,16 @@ Currently supported vim-specific commands (as of Zed 0.106):
|
|||
to sort the current selection (with i, case-insensitively)
|
||||
```
|
||||
|
||||
## Vim settings
|
||||
As any Zed command is available, you may find that it's helpful to remember mnemonics that run the correct command. For example:
|
||||
|
||||
```
|
||||
:cpp [C]o[p]y [P]ath to file
|
||||
:crp [C]opy [r]elative [P]ath
|
||||
:reveal [Reveal] in finder
|
||||
:zlog Open [Z]ed Log
|
||||
```
|
||||
|
||||
## Settings
|
||||
|
||||
Some vim settings are available to modify the default vim behavior:
|
||||
|
||||
|
|
@ -184,17 +207,13 @@ Some vim settings are available to modify the default vim behavior:
|
|||
// "never": don't use system clipboard
|
||||
// "on_yank": use system clipboard for yank operations
|
||||
"use_system_clipboard": "always",
|
||||
// Enable multi-line find for `f` and `t` motions
|
||||
"use_multiline_find": false,
|
||||
// Enable smartcase find for `f` and `t` motions
|
||||
"use_smartcase_find": false
|
||||
// Lets `f` and `t` motions extend across multiple lines
|
||||
"use_multiline_find": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Related settings
|
||||
|
||||
There are a few Zed settings that you may also enjoy if you use vim mode:
|
||||
There are also a few Zed settings that you may also enjoy if you use vim mode:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -203,10 +222,54 @@ There are a few Zed settings that you may also enjoy if you use vim mode:
|
|||
// use relative line numbers
|
||||
"relative_line_numbers": true,
|
||||
// hide the scroll bar
|
||||
"scrollbar": { "show": "never" }
|
||||
"scrollbar": { "show": "never" },
|
||||
// allow cursor to reach edges of screen
|
||||
"vertical_scroll_margin": 0,
|
||||
"gutter": {
|
||||
// disable line numbers completely:
|
||||
"line_numbers": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"context": "Dock",
|
||||
"bindings": {
|
||||
"ctrl-w h": ["workspace::ActivatePaneInDirection", "Left"],
|
||||
"ctrl-w l": ["workspace::ActivatePaneInDirection", "Right"],
|
||||
"ctrl-w k": ["workspace::ActivatePaneInDirection", "Up"],
|
||||
"ctrl-w j": ["workspace::ActivatePaneInDirection", "Down"]
|
||||
// ... or other keybindings
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Subword motion is not enabled by default. To enable it, add these bindings to your keymap.
|
||||
|
||||
```json
|
||||
{
|
||||
"context": "Editor && VimControl && !VimWaiting && !menu",
|
||||
"bindings": {
|
||||
"w": "vim::NextSubwordStart",
|
||||
"b": "vim::PreviousSubwordStart",
|
||||
"e": "vim::NextSubwordEnd",
|
||||
"g e": "vim::PreviousSubwordEnd"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## Supported plugins
|
||||
|
||||
Zed has nascent support for some Vim plugins:
|
||||
|
||||
- From `vim-surround`, `ys`, `cs` and `ds` work. Though you cannot add new HTML tags yet.
|
||||
- From `vim-commentary`, `gc` in visual mode and `gcc` in normal mode. Though you cannot operate on arbitrary objects yet.
|
||||
- From `netrw`, most keybindings are supported in the project panel.
|
||||
- From `vim-spider`/`CamelCaseMotion` you can use subword motions as described above.
|
||||
|
||||
## Regex differences
|
||||
|
||||
Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
|
||||
|
|
@ -216,7 +279,6 @@ Notably:
|
|||
- Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
|
||||
- On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
|
||||
- When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
|
||||
- Vim uses `\<` and `\>` to represent word boundaries, in Zed these are both handled by `\b`
|
||||
- Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
|
||||
- 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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,6 +25,7 @@ extend-exclude = [
|
|||
|
||||
[default]
|
||||
extend-ignore-re = [
|
||||
'cl\[ist]',
|
||||
'"ba"',
|
||||
":ba\\|z",
|
||||
# :/ crates/collab/migrations/20231009181554_add_release_channel_to_rooms.sql
|
||||
|
|
|
|||
Loading…
Reference in a new issue