Override of keybinds in every release

[FransHk]

Summary

I use Zed as my go-to editor and love many of its features. However, every update, certain keybinds I override break because the default keymap changes in some other place. It has now gotten to the point that I want to quit using Zed.

Description

Using my own custom keybinds for various shortcuts such as assistant functionality, I have come to fear every incoming update for Zed. What typically happens is that some new function is introduced to Zed that is shipped with a new default keybind. Because Zed has a great many context types, typically, at least one of my custom keykinds for a specific context breaks as a result.

For example, as of this latest release, my custom keybind ctrl-a, that quotes my selected text to the assistant, no longer works.

{
   "context": "Editor && vim_mode == visual",
   "bindings": {
     "ctrl-a": "assistant::QuoteSelection",
     "ctrl-i": "assistant::InlineAssist"
   }
 },

Similarly, last week, the ctrl-enter combination broke because of a keymap change, and I have to go and patch it up like so

  {
    "context": "Editor && mode == full",
    "bindings": {
      "ctrl-enter": "assistant::Assist"
    }
  },

because my original keybind did not include mode == full and some newly introduced keybind overwrote that specific combination.

Do not get me wrong, I know why it breaks (the key is overriden in a more specific context in the default keymap that is introduced in a release), it's just that every time this happens, I have to go into the default keymap, find what overrides it, and patch it up in my custom keymap so that it starts working again. As you can imagine, this is very tiresome.

Ideally, I would like a function that very explicitly states (or even better; asks) whether a new keybind introduced in a release to accommodate a new feature is allowed to be added if it touches one of my custom overrides. That said, how am I supposed to deal with this issue? Are there ways to prevent this from happening almost every single release?

My full keymap: GitHub

</details>
-->


### Zed Version and System Specs

Zed: v0.185.13 (Zed) 
OS: Linux Wayland ubuntu 24.04
Memory: 14.9 GiB
Architecture: x86_64
GPU: AMD Radeon Graphics (RADV GFX1103_R1) || radv || Mesa 24.0.9-0ubuntu0.1

[lowdewijk]

This is a show stopper for me. When I fire up my editor I want to go go go.

[notpeter]

Thanks for this feedback. We as a team discussed this and some related keymap improvements we've put on our roadmap. Specifically we'll be seeking to improve the experience of unbinding/rebinding keys in user keymaps, which currently requires perfectly matching the context in the zed base keymap (which may change).

[gwk]

I am a longtime VSCode user and went to great lengths wrestling with their keybindings. Just yesterday I took the plunge and began customizing Zed with the intent of using it full time. Perhaps my experience with both could inform your roadmap somehow.

TLDR

• Please think of keybindings as a thing that the user has to maintain over time in the face of changes to the application.
• Zed currently has an option for no default bindings. Please keep it that way! Default keybindings are a pain to undo as more get added in. I don't want keybindings showing up unannounced that I don't know about.
• Zed may end up with thousands of bindable commands. More than I can proofread manually.
• JSON dictionaries of bindings are problematic for detecting duplicate bindings. Consider lists of lists instead.
• command : key may be a superior format than key : command because it sorts more meaningfully and allows you to specify no binding.
• I like how much simpler the Zed contexts are compared to the VSCode "when" clauses, which are like a whole undocumented mini-language.

VSCode

I started using VSCode in 2016 or 2017. Back then they changed a lot. There were so many keybindings for things that I did not care about. Occasionally I would accidentally hit them and not know what had happened. Furthermore, the defaults seemed like Windows conventions that I knew nothing about. I resolved to clear them all out and then explicitly set the bindings I wanted.

I pasted the default keybindings into a json file. I wrote a script to extract all valid keybindings and "when" clauses (context expressions) from the defaults. I then created a very simple syntax for defining key bindings as lines in a text file. The script consumed and validated the key binding lines, and output the VSCode bindings JSON.

This might sound like overkill but it was a process that I found I could maintain over time. As of now VSCode has 2,972 bindable commands. That is a lot! More than I can proofread manually. Many commands have come and gone, changed names, changed contexts, etc. Recently there has been a lot more churn as they add all of the AI features.

By writing bindings out as " <key?> <when?>" a line at a time, I have a complete, sorted list of commands, including the ones I did not want bound. I run the script, paste in the list of new/missing bindings that it generates for me (defaulting to no binding) and tell VSCode to sort the lines.

The script prints a clickable error message with line number for nonexistent or otherwise invalid bindings. I fix them one at a time which is a pain but goes quickly. Perhaps I could have made fix-ups more automatic but it worked well enough for 8 years.

I put the defaults, the custom bindings, and the script in version control which makes it easier to see what has changed. I go through this process every once in a while, usually when I realize that a binding has broken with a new release or I want to change something. Sometimes it is easy, and sometimes not. It looks like I made 30 commits in 8 years.

Here are links to the system. I'm sharing this as an example of what I hope Zed users never have to resort to!

• The custom bindings: https://github.com/gwk/gloss/blob/1b4420b9697c31db8a5da8a5b6e73a7a730b5452/vscode/keys.txt
• The crazy script: https://github.com/gwk/gloss/blob/63ff851a0588b3f6a38bed3cf2dd748a394277e6/vscode/keybindings.py

Zed

Perhaps pessimistically I started to take a similar approach to Zed yesterday. I only went as far as writing a python script to digest the default mac keybindings json. I was pleasantly surprised. It is simpler than VSCode, and for now I have decided to write out my keybindings by hand in the zed format.

If there is one design principle I hope Zed will adhere to it is to start with absolutely no keybindings. Having to manually undo defaults is a huge pain that is easily avoided. If you need a means to help users update their keybindings to keep up with changes to the defaults, then please create an interactive mechanism that actually does that. It's so hard to tell what is going on when there are implicit defaults.

Zed's format is dictionaries of binding : command. This is not great because a duplicate key bindings will go undetected. Perhaps Zed does something custom to find them, but many JSON standard parsers will simply overwrite an earlier binding with a later one. In contrast, VSCode uses a list of binding objects.

The format I settled on put the command first. That way when you sort all of the bindings, any duplicates end up next to each other, and similarly named commands get grouped by prefix. This is helpful for maintaining the bindings and making sure that related command sets that I do care about are fully set up.

Over time, I saw what looked like a lot of kludges in the VS Code binding. Sometimes the "when" clauses would get very complicated, and then in a later release they would get simplified into a new condition name. As a user but not a developer of the editor, I found that I didn't know how these context clauses interacted and resorted to a validation check that each binding had the same context as the default binding. This was necessitated by the fact that they would change over time and my context clauses would suddenly break. For what it's worth I don't think the MS devs understand how bad it is to deal with this when you don't know how the internals work.

Zed's contexts look simple now, but already there are signs of similar problems. There is this comment at the top:

  // Moved before Standard macOS bindings so that `cmd-w` is not the last binding for `workspace::CloseWindow` and displayed/intercepted by macOS.

I'm sympathetic to the realities of dealing with macOS. But as a user who tried and failed to understand what this particular warning means, I encourage you to make your system robust enough that you don't need comments or hacks in user configuration files.

That's enough... thanks for reading!

[gwk]

Also, consider requiring and managing a version number in the keymap file. Then Zed can detect when a user's bindings are using out-of-date command names. The number would increase with every breaking change, which might happen a lot, but the editor could help the user fix things up quickly.

[notpeter]

Zed currently has an option for no default bindings. Please keep it that way! Default keybindings are a pain to undo as more get added in. I don't want keybindings showing up unannounced that I don't know about.

We have no plans to remove support for "base_keymap": "none", but we also expect this function will only be appealing to a small minority of users (well less than <1%)

JSON dictionaries of bindings are problematic for detecting duplicate bindings. Consider lists of lists instead.

Yes, there are issues with duplicates but I don't see how LOLs changes this. ctrl-shift-e and shift-ctrl-e will always need to be handled application side.

command : key may be a superior format than key : command because it sorts more meaningfully and allows you to specify no binding.

Except actions can be arrays, e.g. "cmd-w": ["pane::CloseActiveItem", { "close_pinned": false }], so they can't be on the left side, unless it's all arrays:

[["pane::CloseActiveItem", { "close_pinned": false }], "cmd-w"]

And the sorting is clearly personal preference. I don't think sorting by keys or by actions is ideal -- there is non-zero benefit of being able to put "cmd-z": "editor::Undo", and "cmd-shift-z": "editor::Redo" on successive lines.

I like how much simpler the Zed contexts are compared to the VSCode "when" clauses, which are like a whole undocumented mini-language.

We are working to improve this even further so that most users will see/use simplified contexts the majority of the time. (e.g. switch from Editor && mode == full, Editor && mode == auto_height, Editor && mode == single_line to Editor / MultiLineEditor / LineEditor or something similar.

Also, consider requiring and managing a version number in the keymap file. Then Zed can detect when a user's bindings are using out-of-date command names. The number would increase with every breaking change, which might happen a lot, but the editor could help the user fix things up quickly.

I think explicit versions may cause more harm than good at this stage. We already detect old invalid action names and will migrate them accordingly. Additionally, versioning would necessitates us switching to a top-level map for keybinds which is a massive breaking change which requires re-creating all user and Zed keybinds.

[gwk]

Yes, there are issues with duplicates but I don't see how LOLs changes this. ctrl-shift-e and shift-ctrl-e will always need to be handled application side.

Your example is two different key strings that have the same meaning. I'm talking about an identical key string written twice in the dictionary. Many JSON parsers will silently overwrite previous entries. This is tough to catch unless you have a JSON parser that warns about duplicate entries.

Except actions can be arrays...

I was thinking of each binding as a triple of (key, action, arguments). Perhaps the args dictionary does not have to be grouped with the action name?

I don't mean to quibble. My goal is not to get Zed to do it "my way." Rather, I'm trying to illustrate that the status quo (i.e. VS Code) is really far from ideal. You have this completely customizable system, but it can be hard to change without breaking things.

You are probably right that I'm in the <1% of people who want to fully control the keybindings, but only because historically it's such a pain. I've given up on this front many more times than I've succeeded. I'm hopeful that Zed will be a better quality tool where customization is worth the trouble. To a large extent my goal is just to make key parts like cursor movement and find/replace behave more like the legacy tools I'm stuck with (macOS, Terminal.app, etc).

Stepping back, the reason I'm printing out all the default bindings sorted both ways is that I'm trying to see what is going on, and guess at how the system works. This is the kind of system that is supposed to be simple, and probably seems simple to the developers. But to the new user it is large and full of keywords with meanings that I need to understand to make anything work.

In any case, thanks for considering all of this. It seems to me that Zed is already above average in this department!

[ackmanx]

You are probably right that I'm in the <1% of people who want to fully control the keybindings, but only because historically it's such a pain. I've given up on this front many more times than I've succeeded.

I am now too (thanks for pointing out the None option) because I can't for the life of me figure out why default bindings take precedence over mine when the docs seem to imply that shouldn't happen. I think it is just easier to start with nothing and copy over the ones I need.

[JonGretar]

I am now too (thanks for pointing out the None option) because I can't for the life of me figure out why default bindings take precedence over mine when the docs seem to imply that shouldn't happen. I think it is just easier to start with nothing and copy over the ones I need.

Usually because of context priority. Which could be explained a bit more detailed in the docs.