Breaking Keybinding Changes 2024-11-13

[notpeter]

We are making multiple changes to how keyboards work in Zed.
The first two affect all platforms, the remaining three affect only macOS.

For the thinking behind this, please see Zed Blog: macOS Keyboard Shortcut Localization.

1. Removal of alt- only key bindings.

As of Zed v0.162.x (released as Zed Preview on 2024-11-13 and Zed Stable on 2024-11-20) Zed will be removing a number of keyboard shortcuts which of the form alt-N / option-N where N is a single letter.

The purpose of this change is to better accommodate users of non-US keyboards in the default Zed configuration. On these keyboards, these default shortcuts prevented the use of non-ASCII characters required for these languages.

If you wish to continue using these, you will need to explicitly add them to your User keymap (~/.config/zed/keymap.json) which is accessible via the zed: open keymap action from the command palette or by pressing cmd-k cmd-s (Mac) or ctrl-k ctrl-s (Linux/Win).

[
  {
    "context": "Editor",
    "bindings": {
      "alt-b": "editor::MoveToPreviousWordStart",
      "alt-d": "editor::DeleteToNextWordEnd",
      "alt-f": "editor::MoveToNextWordEnd",
      "alt-h": "editor::DeleteToPreviousWordStart",
      "alt-q": "editor::Rewrap",
      "alt-v": ["editor::MovePageUp", { "center_cursor": true }]
    }
  },
  {
    "context": "Editor && mode == full",
    "bindings": {
      "alt-z": "editor::ToggleSoftWrap"
    }
  },
  {
    "context": "AssistantPanel",
    "bindings": {
      "alt-m": "assistant::ToggleModelSelector"
    }
  }
]

We appreciate your understanding an apologize for any disruption this may cause.

• PR: Stop using alt- shortcuts #20378

2. Inline Completion (Copilot, SuperMaven) Partial Completion Acceptance

On MacOS, the default keyboard shortcut bound to editor::AcceptPartialInlineCompletion
will now be ctrl-right instead of cmd-right.

On Linux, the default keyboard shortcut bound to editor::AcceptPartialInlineCompletion
will now be alt-right instead of ctrl-right.

• PRs: Use a different keybinding for editor::AcceptPartialInlineCompletion action #20419
• and Use a different keybinding for editor::AcceptPartialInlineCompletion action (Linux) #20443

3. Updated shortcuts for extended Latin keyboards

On macOS when using a keyboard that supports an extended Latin character set (e.g. French, German, ...) keyboard shortcuts are now automatically updated so that they can be typed without option. This fixes several long-standing problems where some keyboards could not type some shortcuts.

This mapping works the same way as macOS. For example on a German keyboard shortcuts like cmd-> become cmd-:, cmd-[ and cmd-] become cmd-ö and cmd-ä. This mapping happens at the time keyboard layout files are read so the new keybindings are visible in the command palette by searching for an action. To opt out of this behavior for your custom keyboard shortcuts, set "use_layout_keys": true in your binding section. For the keys affected on each layout see here.

This does not affect Vim mode, as Vim's shortcuts use layout keys to make them more compatible with Vim.

• PR: macOS: Add key equivalents for non-Latin layouts #20401

4. Updated shortcut handling for non-Latin keyboards

On macOS when using a keyboard that types a non-Latin character set (e.g. Armenian, Cyrillic), bindings bound to latin characters are more reliable. Zed will now always try to use the character from your keyboard's command layout (which is usually QWERTY) when matching bindings, instead of only doing this when the command key is held down.

This allows you to use Vim's normal mode without switching keyboard, and makes bindings like ctrl-a for select all accessible.

• PR: macOS: Allow non-cmd keyboard shortcuts to work on non-Latin layouts #20336

5. Dispatching shortcuts before IME

Keyboard shortcuts will now be dispatched before trigging the IME system. This primarily affects vim mode on keyboards with IME menus (like Japanese), where you'll now be able to use vim normal mode without switching input.

It also changes the behavior on Extended Latin keyboards with dead keys. For example ^ will go to the beginning of a line in vim mode, even if it would normally be a dead key. This is a departure from vim, where you would have to type ^ space. Note that some mappings still require the space. For example: d f ^ space is needed because you might want to do d f â instead.

• PR: macOS: Improve deadkeys #20515

[minimo-io]

Hi, spanish keyboard on Mac Mini M1 here. My lovely Zed just broke the keybindings after the last update (v0.162.3). Unfortunately now a cmd-f (buffer search) opens a new buffer panel to the right.

(edit for extra details)

Example, this will open the help menu item, despite my keymap config.

    {
        "context": "Editor",
        "bindings": {
            "cmd-/": ["editor::ToggleComments", { "advance_downwards": false }]
        }
    },

Similar problems with project search, and split right binding to cmd-f instead of search (this last one was fixable by editing my my keymap.json config)

[ConradIrwin]

@cristianorvf Sorry about this! Those bindings should be spelled shift-u and shift-k and shift-j in Zed. That said, I didn't intend to break them, and they'll be fixed in the next patch release.

[minimo-io]

Most things seems solved after the last update, with one exception: comments shortcut keep opening the "Help" menu item in spanish keyboards. So, comments are cmd-/ which in spanish keyboard results in cmd-(shift)-/. Opening the help menu item.

BTW: Is this the right place for posting this?

[ConradIrwin]

@minimo-io can you confirm which layout you're on (look in debug: Open Key Context View). For me using the Spanish ISO comments are on /, which is typed with shift+7?

[minimo-io]

debug: Open Key Context View

Sure @ConradIrwin I am using a spanish magic keyboard (apple), more details in the first screen-cap.

3 screenshots

[ConradIrwin]

@minimo-io wierd... that is acting pretty much how I expect, except that the help menu opens for you.

I notice in my settings that I have this keybinding available, but disabled. (And even if I enable it, I don't get the problem you see)

Do you have anything similar?

[minimo-io]

Do you have anything similar?

Weird indeed! I checked and had that OS option enabled, after disabling it and trying to comment again, the help menu does not open anymore but still cannot comment lines (nothing happens). To keep things usable i changed the key-binding to cmd-shift-g, I suppose i can get use to sth like that.

Let me know if I can help in any other way. I am using a Mac Mini M1 (2020), OS version 15.1.1 (Sequoia), system language is English, keyboard in Spanish, details above. Thanks!

[mdelete]

I stumbled upon this myself just now, after a lengthy phase of avoiding the sequoia update, and thanks to @ConradIrwin's comment I quickly found the reason why now suddenly the help-menu pops up. Now the weird part: I'm using the default keybindings in zed, german keyboard, which is similar to spanish with regard to cmd-shift-7 for comment lines. I'm also using Xcode, which recently shifted toggle comments to cmd-ß (should be cmd-´ in spanish) and this shortcut also works in zed without being configured.

[bakkdoor]

I am using a german keyboard layout, and cmd-/ stopped working for commenting out lines.

I noticed that it works if I press the key next to it (cmd-&) on the german keyboard even though I am using the default keybinding:

"cmd-/": ["editor::ToggleComments", { "advance_downwards": false }],

If I add a custom keybinding for it it works again with cmd-/ if I set it up with the key to the left of it via:

"cmd-&": ["editor::ToggleComments", { "advance_downwards": false }],

[notpeter]

I'd like to avoid this thread from getting too large so I'm going to hide some replies above and roll them into individual issues or notes in this comment.

Associated issues:

• Default cmd-shift-\ keybinding for MoveToEnclosingBracket does not work #20152
• Toggle comment and project search keybindings are malfunctioning #20926
• Cannot type '@' or comment out lines/blocks of code with cmd+/ with danish ISO keyboard on macOS #21049
• Chinese input method causes conflicts with Vim key bindings #21136
• cmd-. is toggling line comment not ToggleQuickAction #21155
• i have an issue that i am unable to write the backslash "\" in zed  #21175
• French keyboard key combinations interpretation differ from physical key pressed #21200
• Strange dead key behaviour on Turkish keyboard layout #21204

[injust]

ctrl-right I have bound to switching workspaces/desktops in MacOS. I thought this was standard, but I might be mistaken…?

Yeah, this is a standard macOS shortcut. I haven't tested how it interacts with Zed's new keybinding, but I imagine it could result in some funny behaviour.

[tozz]

I've been trying to get back to the "breaking change" but seems I can't. There was a time when I was in happy land with CMD-´ working just as it does on a US keyboard with me using a Swedish one. This was fantastic. It seems now that it has been reverted and is no longer possible to achieve?

[minimo-io]

I've been trying to get back to the "breaking change" but seems I can't. There was a time when I was in happy land with CMD-´ working just as it does on a US keyboard with me using a Swedish one. This was fantastic. It seems now that it has been reverted and is no longer possible to achieve?

Same here. I just ended up changing my keymap for the moment (Spanish keyboard, macOS, US system language)

[jannisborgers]

I am using a german keyboard layout, and cmd-/ stopped working for commenting out lines.

I noticed that it works if I press the key next to it (cmd-&) on the german keyboard even though I am using the default keybinding:

"cmd-/": ["editor::ToggleComments", { "advance_downwards": false }],

If I add a custom keybinding for it it works again with cmd-/ if I set it up with the key to the left of it via:

"cmd-&": ["editor::ToggleComments", { "advance_downwards": false }],

Thanks for the post, this is a workaround for the moment!

I admit the change confuses me. As far as my tests go, the update makes Zed behave different from all other text editors on macOS I have installed (German ISO QWERTZ keyboard in my case). Before the update, this important binding worked perfectly well.

• In other editors (and Zed before the update), cmd+shift+7 (equivalent to cmd+/, because / is typed with shift+7) toggles line comments.
• key_equivalents.rs maps / to ß, which is the reason cmd+ß works, as that combination now maps to the default cmd+/ keybinding.
  

  zed/crates/settings/src/key_equivalents.rs

  Lines 578 to 602 in c6932d1

  	"com.apple.keylayout.German" => &[
  	('"', '`'),
  	('#', '§'),
  	('&', '/'),
  	('(', ')'),
  	(')', '='),
  	('*', '('),
  	('/', 'ß'),
  	(':', 'Ü'),
  	(';', 'ü'),
  	('<', ';'),
  	('=', '*'),
  	('>', ':'),
  	('@', '"'),
  	('[', 'ö'),
  	('\'', '´'),
  	('\\', '#'),
  	(']', 'ä'),
  	('^', '&'),
  	('`', '<'),
  	('{', 'Ö'),
  	('|', '\''),
  	('}', 'Ä'),
  	('~', '>'),
  	],

• The file also maps & to /, which explains why @bakkdoor describes that cmd+shift+6 works. For some reason, it doesn’t work in my case.
• Adding the cmd+& keybinding above makes cmd+shift+7 work again. This fixes the problem, but is misleading because & is on the 6 key, not on the 7 key.
• The context menu always shows Toggle Line Comment ⌘ß, which adds the the confusion, because I would assume users keybindings overwrite default keybindings.

My question: Would it be possible to opt out of the key equivalents for the default keymap as well, not only for custom keybindings?

For comparison, inspecting VSCode’s key mappings shows me that every command that contains / is bound to the necessary modifiers plus meta+[Digit7], so cmd+/ (toggle line comment) is equivalent to cmd+meta+[Digit7].

PS: The docs state both use_layout_keys (last sentence of this section) and use_key_equivalents (in this section). Do these settings control different aspects of the mapping?

[ConradIrwin]

@jannisborgers The use_layout_keys is required for zed versions 0.162..0.165; I removed it and replaced it with use_key_equivalents (because people expected use_layout_keys to be the default). Sorry for messing up the docs, I'll fix those. for now you probably want use_layout_keys.

---

Where to go from here though...?

While the shipped solution works as I intended, it isn't making anyone happy.

We could support "disable_key_equivalents": true (and/or make them configurable), but I'd like to get to the point where it's not "wrong" by default. (I'd assumed that the macOS mappings would give us this, but turns out no other developer tools seem to use them :D).

I know this would be another breaking change for people, which doesn't make me thrilled, but I would like to end up at a point where it works as well as possible by default.

What if we changed the key equivalents to prioritize keeping more shortcuts unchanged?

// by default in US locale, cmd-`/cmd-~ are window switching, this moves to cmd-< and cmd-> in German.
// I think that means the following mappings from macOS make sense:
    ('`', '<'),
    ('~', '>'),
    ('<', ';'), // equivalent QWERTY position, and need to move because we're using these keys for `/~
    ('>', ':'), 
    (':', 'Ü'), // need to move, and using ü seems as good a place as any.
    (';', 'ü'),
 
// Using adjacent keys preserves things like indent/outdent feeling similar
    ('[', 'ö'),
    (']', 'ä'),
    ('{', 'Ö'),
    ('}', 'Ä'),

// The keys above cmd-shift-{3,4,5} have to stay in similar positions because they conflict
// with macOS screenshot shortcuts when cmd-shift is used
  ('#', '§'),

// And at this point we deviate from macOS
// The remaining four ASCII characters that can't be typed without option, mapped to *new* positions
    ('\\', '´'),
    ('|', '`'),
    ('@', '#'),
    ('^', 'ß'),

// We remove these key equivalents, that are superfluous because you can type these on a QWERTZ keyboard without option.
    // ('/', 'ß'),
    // ('\'', '´'),
    // ('"', '`'),
    // ('&', '/')
    // ('(', ')')
    // (')', '=')
    // ('*', '(')
    // ('=', '*')

Does that sound like a reasonable change? Would anyone like to take a pass at other layouts?

The other wrinkle that I am not sure how to solve is the window switching shortcuts (cmd-backtick and cmd-~) and the help shortcut (cmd-?). The default values seem to depend on locale, not on the keyboard layout. This means that if we remap keys, there's always a chance we hit them by mistake. I do think it's right for us to default to assuming your locale and layout match, but it'd be nice to have an answer for people who can't switch windows. One thing I'd love to know (for people using a US locale with a non-US keyboard: how you cycle windows backwards when cmd-~ can't be typed without option?

[tozz]

Personally I would love if Zed led the way and used macOS native bindings as it did for a short while. It's one of my longest standing problems with any editor that CMD-backtick doesn't comment lines and when it started doing that in Zed it was amazing (well, Zed just allowing macOS to do its thing really). Having another custom solution seems even more confusing to be honest.
One thing I'd love to know (for people using a US locale with a non-US keyboard: how you cycle windows backwards when cmd-~ can't be typed without option?
One of the first things I do on any installation is rebind it to CMD+§, I've done it for more than a decade so I don't know if I have to really, muscle memory. Obviously not something Zed can cater to, I also almost never see developers using window cycling for some reason.

[jannisborgers]

@ConradIrwin Thanks for acknowledging the issues, I’m sorry that my comment was a little strong. More thought went into this than I realized and my problem can be solved by setting up a keybinding, while the update might help those that need the other keybindings that didn’t work without the remapping.

The major point for me is the way I had to set up the shortcut. Using a character printed on the 6 key (&) to make a shortcut work for the 7 key (/) is odd.

I know this might be beyond the scope, but could a GUI ease solving the problems? Other editors let you record the desired shortcut by pressing a button, which seems to be the most direct way to make sure the right keys need to be pressed.

This would probably not solve the problem where default shortcuts don’t work with all keyboard layouts. For comparison: VSCode has a GUI for shortcuts, but also uses key mappings (use "Developer: Inspect Key Mappings" command to see), so I guess this needs to be done either way.

[hedefalk]

1. Today after an update my workaround of using cmd+´ stopped working. I've been using this as a workaround as it seems to be the standard since my normal toggle-command stopped working

2. As I entirely lost the ability to toggle comments I went back here and I can confirm that I can now use cmd-shift-7 which is cmd-/ again after adding

   "cmd-&": ["editor::ToggleComments", { "advance_downwards": false }]

which is the key left of the actual key we're talking about:

So same as reported above on german locale.

"cmd-/": ["editor::ToggleComments", { "advance_downwards": false }],

doesn't do anything.

[ConradIrwin]

@hedefalk which version of Zed are you using? in 0.165 and below you'll want to add "use_layout_keys" to your keymap (though that should not be necessary in 0.166 and above).

@jannisborgers no worries, thank you for being able to have a constructive disagreement online (it's a rare skill :D).

I hope the change to 0.166 to fix the way keymaps work for you resolves that problem.

[hedefalk]

@ConradIrwin Thanks, yes, I'm on 0.165.4 so now good with:

[
  {
    "context": "Editor",
    "use_layout_keys": true, // https://github.com/zed-industries/zed/issues/20425#issuecomment-2551584271
    "bindings": {
…
  // "cmd-&": ["editor::ToggleComments", { "advance_downwards": false }], // https://github.com/zed-industries/zed/issues/20425#issuecomment-2550705171
      "cmd-/": ["editor::ToggleComments", { "advance_downwards": false }]
    }
  },

[ghitchens]

It looks that some recent changes here changed the globe/fn-F binding to full screen on the Mac. The command palette now shows this bound to ctrl-cmd-F. While both of these keys seem to work with some mac apps, globe/fn-F seems to be the "mac standard" binding which appears in the menu for most mac apps (safari, mail, etc)

I don't know if globe/fn-F broke during these changes inadvertently or if it was intentionally rebound, but as of 0.166.1 (and likely before), globe-f no longer matches the menu shortcut. This key DID work after some of the above changes, as recently as a week ago.

[injust]

I tested ctrl-right on macOS and it seems to no-op. I'm testing this on Zed 0.166.1, with Supermaven's inline completions and a standard US keyboard.

If I have multiple macOS workspaces, it switches to the next workspace instead. Does this keybinding just get eaten by macOS?

[injust]

I tested ctrl-right on macOS and it seems to no-op. I'm testing this on Zed 0.166.1, with Supermaven's inline completions and a standard US keyboard.

If I have multiple macOS workspaces, it switches to the next workspace instead. Does this keybinding just get eaten by macOS?

Update: Accepting partial inline completion finally works in 0.170.1 (and was changed to ctrlcmd→ on macOS).