mirrors/zed
1
0
Fork 0
mirror of https://github.com/zed-industries/zed.git synced 2024-12-27 19:02:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

docs: Edit Vim mode introduction, add instructions about toggling Vim mode (#17214)

Browse source 
Release Notes:

- N/A

This is a first contribution to the vim docs following a session
watching Conrad Irwin code a vim mode feature. He told me contributions
on the docs would be welcome.

I'm starting with a relatively small change as per your contributing
guidelines and pairing this with a proposal for a bigger change in this
issue: #17215
This commit is contained in:
Nathan Lovato 2024-09-04 20:47:03 +02:00 committed by GitHub
parent de1d301993
commit b0045b9324
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 19 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
docs/src/vim.md
View file

@ -1,18 +1,26 @@
# 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". On this page, you will learn how to turn Zed's vim mode on or off, what tools and commands are available, and how to customize keybindings.
## Philosophy
Vim 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.
Vim mode tries to offer a familiar experience to Vim users: it replicates the behavior of motions and commands precisely when it makes sense and uses Zed-specific functionality to provide an editing experience that "just works" without requiring configuration on your part. This includes support for semantic navigation, multiple cursors, or other features usually provided by plugins like surrounding text.
This 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).
So, Zed's vim mode does not replicate Vim one-to-one, but it meshes Vim's modal design with Zed's modern features to provide a more fluid experience. It's also configurable, so you can add your own key bindings or override the defaults.
> **Note:** The foundations of Zed's vim mode should already cover many use cases, and we're always looking to improve it. If you find missing features that you rely on in your workflow, please [file an issue](https://github.com/zed-industries/zed/issues).
## Enabling and disabling vim mode
When you first open Zed, a checkbox will appear on the welcome screen, allowing you to enable vim mode.
If you missed this, you can toggle vim mode on or off anytime by opening the command palette and using the workspace command `toggle vim mode`.
## Zed-specific features
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.
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.
Vim mode has several "core Zed" key bindings that will help you make the most of Zed's specific feature set.
```
# Language server
@ -81,7 +89,7 @@ Vim mode emulates visual block mode using Zed's multiple cursor support. This ag
Vim'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.
Finally, 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.
Finally, 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.
## Custom key bindings
@ -119,7 +127,7 @@ If you would like to emulate vim's `map` (`nmap` etc.) commands you can bind to
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).
#### Contexts
### Contexts
Zed'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.
@ -129,10 +137,9 @@ Vim mode adds several contexts to the `Editor`:
- `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`).
- `"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.
### Restoring some sense of normality
### Restoring common text editing keybindings
If you're using Vim mode on Linux or Windows, you may find that it has overridden keybindings
that you can't live without. You can restore them to their defaults by copying these into your keymap:
If you're using vim mode on Linux or Windows, you may find it overrides keybindings you can't live without: <kbd>Ctrl</kbd>+<kbd>v</kbd> to copy, <kbd>Ctrl</kbd>+<kbd>f</kbd> to search, etc. You can restore them by copying this data into your keymap:
```json
{
@ -222,7 +229,7 @@ As any Zed command is available, you may find that it's helpful to remember mnem
## Settings
Vim mode is not enabled by default. To enable Vim mode, you need to add the following configuration to your settings file:
Vim mode is not enabled by default. To enable vim mode, you need to add the following configuration to your settings file:
```json
{
@ -230,7 +237,7 @@ Vim mode is not enabled by default. To enable Vim mode, you need to add the foll
}
```
Alternatively, you can enable Vim mode by running the `toggle vim mode` command from the command palette.
Alternatively, you can enable vim mode by running the `toggle vim mode` command from the command palette.
Some vim settings are available to modify the default vim behavior: