Contexts, Actions, and Precedence in Zed Key Bindings

"cmd-k cmd-s": "zed::OpenKeymap", // matches ⌘-k then ⌘-s "space e": "editor::Complete", // type space then e "ç": "editor::Complete", // matches ⌥-c "shift shift": "file_finder::Toggle", // matches pressing and releasing shift twice } ``` The `shift-` modifier can only be used in combination with a letter to indicate the uppercase version. For example `shift-g` matches typing `G`. Although on many keyboards shift is used to type punctuation characters like `(`, the keypress is not considered to be modified and so `shift-(` does not match. The `alt-` modifier can be used on many layouts to generate a different key. For example on macOS US keyboard the combination `alt-c` types `ç`. You can match against either in your keymap file, though by convention Zed spells this combination as `alt-c`. It is possible to match against typing a modifier key on its own. For example `shift shift` can be used to implement JetBrains search everywhere shortcut. In this case the binding happens on key release instead of keypress. ### Contexts If a binding group has a `"context"` key it will be matched against the currently active contexts in Zed. Zed's contexts make up a tree, with the root being `Workspace`. Workspaces contain Panes and Panels, and Panes contain Editors, etc. The easiest way to see what contexts are active at a given moment is the key context view, which you can get to with `dev: Open Key Context View` in the command palette. Contexts can contain extra attributes in addition to the name, so that you can (for example) match only in markdown files with `"context": "Editor && extension==md"`. It's worth noting that you can only use attributes at the level they are defined. For example: ``` # in an editor, it might look like this: Workspace os=macos keyboard_layout=com.apple.keylayout.QWERTY Pane Editor mode=full extension=md inline_completion vim_mode=insert # in the project panel Workspace os=macos Dock ProjectPanel not_editing ``` Context expressions can contain the following syntax: - `X && Y`, `X || Y` to and/or two conditions - `!X` to negate a condition - `(X)` for grouping - `X > Y` to match if a parent in the tree matches X and this layer matches Y. If you're using Vim mode, we have information on how [vim modes influence the context](./vim.md#contexts) ### Actions Pretty much all of Zed's functionality is exposed as actions. Although there is no explicitly documented list, you can find most of them by searching in the command palette, by looking in the default keymaps for [MacOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json) or [Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json), or by using Zed's autocomplete in your keymap file. Most actions do not require any arguments, and so you can bind them as strings: `"ctrl-a": "language_selector::Toggle"`. Some require a single argument, and must be bound as an array: `"cmd-1": ["workspace::ActivatePane", 0]`. Some actions require multiple arguments, and are bound as an array of a string and an object: `"ctrl-a": ["pane::DeploySearch", { "replace_enabled": true }]`. ### Precedence When multiple keybindings have the same keystroke and are active at the same time, precedence is resolved in two ways: - Bindings that match on lower nodes in the context tree win. This means that if you have a binding with a context of `Editor` it will take precedence over a binding with a context of `Workspace`. Bindings with no context match at the lowest level in the tree. - If there are multiple bindings that match at the same level in the tree, then the binding defined later takes precedence. As user keybindings are loaded after system keybindings, this allows user bindings to take precedence over builtin keybindings. The other kind of conflict that arises is when you have two bindings, one of which is a prefix of the other. For example if you have `"ctrl-w":"editor::DeleteToNextWordEnd"` and `"ctrl-w left":"editor::DeleteToEndOfLine"`.

This section delves into the context-based matching of keybindings in Zed, using a tree structure with 'Workspace' as the root. It explains how to identify active contexts using the key context view and how to specify contexts with attributes (e.g., 'Editor && extension==md'). The section outlines the syntax for context expressions, including logical operators and parent-child matching. It also discusses the use of Vim mode contexts. Furthermore, the section explains that Zed's functionality is exposed as actions, detailing how to bind them with and without arguments. Finally, the document explains how Zed resolves conflicts between keybindings based on context tree level and definition order.