Keyboard shortcuts changes

[ConradIrwin]

Hi All!

We (@ConradIrwin, @haruleekim and @JunkuiZhang) are thinking about making some (comparatively) big changes to how key bindings are matched in Zed.

(Update 2024-09-03): We are considering between two options for macOS/Linux:

1. On a non-English keyboard you access cmd-[ with cmd-"whatever you need to do to type [" (the vscode option).
2. On a non-English keyboard you access cmd-[ with cmd-"the key that we have designated as the [/{ key" (the windows option)

In either case we will also update our display of shortcuts to match what you have to type them on your current layout, and we will likely stick with "the windows option" on Windows. Also, in either case we will likely also allow extensions to provide keybindings so that active language communities can make the keyboard shortcuts easier to use.

Each approach has a downside, and I'd like to figure out which is the less bad downside.

• The downside with the vscode approach is that on layouts (like a German QWERTZ layout) that require an option- to type a [, typing cmd-option-5 is ambiguous. Did you mean cmd-option-5 or cmd-[. VScode disambiguates this by using ctrl, we could copy that, or we could use left-option vs right-option to disambiguate (like iTerm).
• The downside with the windows approach is that it's not obvious which key should be the "[/{" key; unlike Windows that has a well-established virtual key code system, macOS does not. (on German again, [ is option-5, { is option-7. For example, we could probably pick ü and ö, but the logic is confusing. That said it may not be too bad if the app tells you "indent with cmd-ü and outdent with cmd-ö).

I'd like input on which option feels more correct to you coming from other macOS/Linux apps using a non-English Latin-based keyboard.

In either case:

• The current behavior for English keyboard (qwerty, Dvorak, Colemak) would not change
• The behavior on non-Latin (e.g. Cyrillic keyboards) would be the same: ctrl-a would be accessible with the same key that cmd-a is.

---

previous post:

Today Zed uses a character-based matching system. When the binding says cmd-{ you have to type the "{" key (wherever it is on your keyboard) while holding command down. We also disable keyboard shortcuts while IME is in progress.

We are considering changing this so that we use a virtual key code based matching system. When the binding says cmd-{ you will have to type "command", "shift" and the virtual key for [/{ which will depend on your layout. We are also considering enabling shortcuts during IME.

This should have no impact on users of qwerty keyboards, but for people using non-qwerty keyboards this will change the location of shortcuts.

We intend to use virtual key codes, so that (for example) if you use a Dvorak keyboard cmd-o will be accessed with the key to the right of a (labelled o in Dvorak, but s in qwerty). This is the same as how Dvorak is handled today.

Questions I'd love answers to:

• What keyboard do you use today (and which OS), and what bindings work as you expect currently (and which don't).
• Should Vim mode's normal mappings be based on virtual key code too? (this would let you use vim normal mode on a Russian keyboard "as though" you were typing on a qwerty keyboard).
• Have you experienced problems with apps that use this system (notably VSCode and its derivatives)? What were the problems (and which keyboard/OS were you using).

The problems we expect this to solve are:

• It's not currently possible to type Zed's builtin shortcuts on a non-Latin keyboard (for example Russian or Korean).
• It's not currently possible to type some shortcuts on some Latin, but not Qwerty keyboards (e.g cmd-{ on Czech).
• (maybe) It's not currently possible to use vim's normal mode on a non-Latin keyboard (for example Russian or Korean) without switching layout.

This may cause some confusion:

• If you are on a non-qwerty keyboard you will need to translate back to the virtual key when adding bindings to your keybinding file. To support this properly we'll need to add a keymap editor that can help you with this.
• If you are on a non-qwerty keyboard, the in-app tooltips will show qwerty keys instead of what your keyboard shows. To support this we'll need to update our display of shortcuts to be aware of your current keyboard layout.

[yuxuanchen1997]

I am using Colemak on Mac/Linux/Windows and have always pressed the same letter on the colemak layout, not matter where the physical keys are located. For example, in browsers, creating a new tab usually is Ctrl-T. I also type Ctrl-(T in Colemak). (though qwerty users will see me type Ctrl-(F in qwerty))

Same is vim. hjkl is not on the same row any more but I am used to it. I'd rather still type the colemak hjkl even if they are less ergonomic than neio which is what those same physical keys map to on the Colemak layout.

When I work in the Terminal, programs like vim is oblivious of my keyboard layout. The letter it has received is the only thing mattered. I think it's in our best interest to remain this way as muscle memory is very hard to change.

[yuxuanchen1997]

I didn't understand this part:

We intend to use virtual key codes, so that (for example) if you use a Dvorak keyboard cmd-o will be accessed with the key to the right of a (labelled o in Dvorak, but s in qwerty).

Isn't this the status quo? As long as you are not asking Dvorak users hitting cmd-r on their layout (same physical location as qwerty) I think it's fine?

[ConradIrwin]

👍 Yeah, this should not change for you as proposed

macOS does have a keyboard layout "DVORAK + QWERTY" that does the opposite to this (when command is down the keys revert to qwerty), but I'm not sure it is commonly used.

[yuxuanchen1997]

👍 Yeah, this should not change for you as proposed

macOS does have a keyboard layout "DVORAK + QWERTY" that does the opposite to this (when command is down the keys revert to qwerty), but I'm not sure it is commonly used.

You may want to change the wording in the post as this seems to suggest that something is changing for Dvorak users as well?

[elsandosgrande]

How long is the feedback window? I'm indisposed for the rest of the week at least, but I should be ready to think about this in earnest and test things out on my laptop next week or the week after at the latest.

For future reference, I'm running Gentoo Linux with KDE Plasma 6 Wayland, using Fcitx for keyboard input. The weird thing about Fcitx and Plasma is that Fcitx, at least on Plasma, acts as some sort of virtual keyboard, whereas Plasma itself (as far as I can tell) uses XKB for its native keyboard handling. This means that, most of the time at least — it's weird and I've done very limited testing — what keyboard shortcuts are registered by Zed at present are solely determined by Plasma's built-in keyboard layout settings, not whatever Fcitx does.

[ConradIrwin]

As long as you need! Assuming we don't find too many contrarian opinions, we'll probably move forward regardless, but I would love more information from the linux side as we fine tune.

Are you using Wayland or X11? As ridiculous as it sounds, we need to implement the handling for the IME for both.

[elsandosgrande]

Awesome! Also, I use Plasma Wayland. Sorry for not mentioning it earlier 😅

I'll edit the reply comment to mention it.

[spartanatreyu]

In my opinion, you're definitely going to want an option to toggle shortcuts between:

• key letter
  • e.g. the letter f

and

• key position
  • e.g. left hand index finger on home row (which for most users is f but for me is t).

---

I use the colmak-dh layout to reduce hand movement.

And as most split keyboard programmers do, I also added the brackets along the middle. i.e. ({[<>]})
You can see it here: https://configure.zsa.io/moonlander/layouts/Mvngb/eOWyK/1
And you can also see the base (non-programmer) colmak-dh here: https://codepen.io/spartanatreyu/pen/XWBeyRd?editors=1100

[ConradIrwin]

The intent in this case is that the virtual key codes will be in the "expected" position for letters.

That said, would you mind if I reached out when we have something to test? I'm curious about how those extra bracket keys are received by the system.

[spartanatreyu]

As far as the computer knows, it's a regular qwerty keyboard so there is no key code vs key location remapping.

My keyboard has custom firmware that does the remapping, and also allows it to switch between colmak-dh and qwerty layouts at any time.

The brackets are received exactly the same as brackets from a normal keyboard.

I can push shift + 0 to see a (.

I can also press my dedicated ( key and the computer will see me pressing shift + 0.

[ConradIrwin]

👍 That's encouraging! I'll still let you know when we have something to test just in case, but I imagine it will work just fine for you.

[rome-user]

I use a MacBook with Japanese keyboard. Primary editor was Emacs before using Zed. I never encountered a key binding that I couldn't enter. I don't feel much inconvenience.

But some apps like Kitty have key bindings that I can't enter. For example, C-<Shift>-+. Symbols like + and * require holding the shift key.

If Zed uses these kind of key bindings, then it may become inconvenient.

[damoonrashidi]

I use a Ferris Sweep with colemak (on macOS) and if I'm understanding this correctly nothing would change since the keybinds are still using the same virtual keys, so I would continue pressing cmd-{ no matter where it is physically on the keyboard?

Since the keyboard reports whatever character is pressed and that is opaque to zed?

[isty2e]

I've recently migrated to colemak, but my 10 years of muscle memory using vim guides my fingers to the qwerty key locations, so I remapped every key to their qwerty counterparts. Especially, hjkl is simply not usable in default colemak layout. So I would strongly prefer the full virtual key option for vim mappings as well.

[ThomasAlban]

Can you share your config file? I'd also love to make this change

[isty2e]

Can you share your config file? I'd also love to make this change

It is version dependent so I'd rather share a script I used for that purpose: https://github.com/isty2e/zed-colemak-keymap, which is a fork of another repo. You'll presumably have to manually edit a few keymaps (like "shift+;").

[ThomasAlban]

I do think this should be a toggleable option at most, because otherwise in order to restore the previous behaviour, people will have to remap every key on their keyboard!

[ConradIrwin]

@ThomasAlban What keyboard layout do you use (on which platform?). The hope is that for the vast majority of people either no (or very few) keyboard shortcuts change.

[ThomasAlban]

I'm using colemak dh on macOS. I think I might have misunderstood your proposal - I thought you meant that the 'location' of the key would be preserved rather than the character pressed. If that's not the case, what exactly are 'virtual keys'?
I guess a source of confusion for this could be that there's a difference between overriding your keyboard layout on the OS level and on the hardware level. I've overridden mine on the hardware level (using a corne split keyboard) so in that case i assume nothing would change?

[ConradIrwin]

One thing missing from the discussion so far is people using non-English layouts. Is anyone using Azerty/Czech etc. who has opinions?

[elsandosgrande]

I use Bosnian. I also use other layouts, including Cyrillic ones, but those are solely through Fcitx, so they largely don't matter for shortcuts.

[probablykasper]

Tested the deindent shortcut (Cmd+]) on my Norwegian layout, that doesn't work no matter if I use the physical key (Cmd+Å) or virtual (Cmd+Shift+8). Maybe this would improve that?

[ConradIrwin]

@probablykasper Yes, this is the problem we're trying to fix!

What solution do most other apps do on a Norwegian layout? i.e. Safari has forward/back bound to cmd-[/cmd-] in a US layout; how do you go forward/back on a Norwegian layout? Similarly next/prev tab is cmd-}/cmd-{ on a US layout. How do you do that?

I think we roughly have the two options you outlined: keep the shortcuts in roughly the same place on the keyboard, or keep the shortcuts accessed at the same "character" position. Do you have a sense of which approach would work better?

[probablykasper]

@ConradIrwin Back/forward is Cmd+Ø/Cmd+Æ, which physically is Cmd+;/Cmd+' on US qwerty. So it's completely different keys, not matching either the physical or virtual keys. Maybe that's something like KeyEquivalent at work? Edit: probably KeyboardShortcut.Localization

This issue and it's PR may be helpful to look at too: tauri-apps/tao#227

[ConradIrwin]

Thanks for the reference to KeyboardShortcut.Localization! That seems to implement exactly what we want.

The only downside is I can't figure out a reasonable to query it: I can render a SwiftUIMenuItem and then read .keyEquivalent off it; but that seems... not great. If I instantiate an NSMenuItem with a key equivalent and read it off, then it doesn't seem to localize, and I can't find a way to instantiate a SwiftUIMenuItem without rendering it.

Does anyone know of an API (even if it's private) we could call to do the same transformation? (The AI systems get stuck on UCKeyTranslate which does scan-code to key mapping; not localizing keyboard shortcuts).

[ionescu77]

Romania, EU here.
I use Macbook with US physical keyboard (I had EN Intl in the past) and switch between layouts US, RO (Romanian) & DE (German Qwertz) when I type messages.

[ConradIrwin]

@ionescu77 Great!

How do other apps handle the Romanian layout for shortcuts? i.e. Safari has forward/back bound to cmd-[/cmd-] in a US layout; how do you go forward/back on a Romanian layout? Similarly next/prev tab is cmd-}/cmd-{ on a US layout. How do you do that?

I think we roughly have the two options to make these work in Zed. Either keep the shortcuts in roughly the same place on the keyboard, or keep the shortcuts accessed at the same "character" position. Do you have a sense of which approach would work better?

[ionescu77]

Thanks for asking.
I use option + cmd + left/right arrows to switch tabs in Chrome and Safari.

I never tried to really use Romanian layout when coding, as I spend my time mostly in terminal/vim & IDEs. And noticed for Software Development the US layout is the most practical for keyboard shortcuts.

At this point in time I am happy about Zed existence. I really missed Atom, personally I find VSCode ugly.
Also Atom had a very beautiful UI for git actions (highlighting diffs, the commit message entry form, etc.)

[gtnebel]

I use German QWERTZ Layout both on Mac and Linux.

[ConradIrwin]

@gtnebel I'm curious what keys you press to access the forward and back shortcuts in Safari. (They are labelled as cmd-[ and cmd-] for a US keyboard)? Similarly for go to next/previous tab (labeled as cmd-{ and cmd-} on a US keyboard)?

I know that in VSCode, indent and outdent (also cmd-[ and cmd-] on a US keyboard) become cmd-option-ctrl-5 and cmd-option-ctrl-6) on a QWERTZ layout.

As we build out more support for international keyboards with zed, I'd like to try and make things work as well as possible out of the box; but it's still unclear to me what the right approach is.

[gtnebel]

Safari

The keyboard shortcuts for forward and back navigation are cmd-Ö and cmd-Ä on QWERTZ keyboard.

VSCode

indent and outdent are on cmd-option-ctrl-5 and cmd-option-ctrl-6. I would type option-5 to get a [ symbol, so the shortcuts have an additional ctrl key to the QWERTY version.

Zed

cmd-[ and cmd-] for indent and outdent in Zed are not working (I would type cmd-option-5 and cmd-option-6). Also the cycling through the inline assistant suggestions with Option-[ and Option-] is not working.

[probablykasper]

I use Colemak-DH on macOS. Doesn't this affect qwerty too? On my Norwegian ISO keyboard you press Shift+8 to write [

[jchatard]

I use the Optimot layout (small French community layout) on macOS.

Every Apple built-in app seems to respond to Virtual keys. Like, VSCode works perfetly, Obsidain as well, that's perfect.

But PHPStorm / WebStorm don't play nice. I need to trick the shortcuts mapping to do what I want.

And Zed is in a strange zone, making it almost unusable (copy/paste not working, etc.)

The real tricky part is that there are some variants of Optimot which change some letters placement when cmd is hold, to have Cut/Copy/Paste on the left hand for example.

I attach a screenshot of my very own to show you.

[ConradIrwin]

I think the most important thing is that zed (in the new world) is consistent with other apps you use.

That said, I'd expect on a layout like this a couple of rough edges. What keys do you type to go forward/back/zoom in/zoom out in Safari (cmd-[/cmd-]/cmd-+/cmd-- on a US qwerty)

[jchatard]

I totally expect some rough edges with such a custom layout :-)

• Zoom in/out: cmd+{ & cmd+} (because on cmd layer { & } are replaced by + & -)
• Forward/back: cmd+left and cmd+right (never knew I could do with [], because I’m french and in Azerty [] is only accessible by alt+shift+( & alt+shift+) so it's not really doable).

[jchatard]

In fact it's a bit like Dvorak - QWERTY ⌘

[Hasnep]

I'm typing on a Taiwanese Zhuyin keyboard, pressing the [ button when in Chinese mode types a 【 (LEFT BLACK LENTICULAR BRACKET), but I'd expect to be able to still use the same shortcuts in Chinese mode. To be honest, I don't even know how to type [ in Chinese mode 😅

[thynson]

AFAIK, what you concerns about is just an IME issue. Shortcut handling should have higher priority than IME in typical environment.

[ConradIrwin]

Today we send keystrokes to the IME first; but we're thinking about changing it around.

The main downside of shifting it is that layouts with deadkeys get a bit more complicated. Today in Brazillian you can "delete to ä" with df"a and delete to a quote with df"<space> because that's how you type ä and ". Today you also can "delete within quotes" with di"<space>, but if we don't invoke the IME on shortcut handling this will become di" with no space.

By itself that's not a huge problem, but it does mean you can't bind to any keys that require a deadkey in your settings as easily (if you want to bind to ä you have to bind to "a).

[rcarlier]

I'm using a French Keyboard on mac, (see #17057 for details) and can't do \ in terminal (nor [ but ]...).
Not "like in Visual Studio Code", but just like in... the system Terminal.app application (or any other application as far as I know).

Option+Shift+/ or Alt+Shift+/ execute an ls in Zed Terminal... but write a correct \ in Zed Editor...

It would seem logical that we have the same behavior in the Zed Terminal and the Zed Editor... (like any other app'...)

[Tobbe]

@rcarlier You can set this to make those characters work in your terminal:

{
  "terminal": {
    "option_as_meta": false
  }
}

[ConradIrwin]

I think the option_as_meta will fix this for you in the terminal (at the expense of not being able to use option-X to trigger escape codes).

This comes up in a related context for shortcuts. Some of zed's shortcuts require typing option-X, but that key combination is required to type a character. This is rarely a problem in English on a qwerty layout because the option-X characters are not commonly used in a programing context; BUT it is a problem for Azerty layouts. I have a few possible solutions to how this might work; and I'm curious if any feel right to you. Let's use the [ based shortcuts as an example:

Today Zed defines cmd-[ to be outdent; option-[ to be prev inline completion; option-cmd-[ to be editor::UnfoldLines; and (in vim mode) [c to go to previous diff. Today you can type the vim shortcuts (with option-shift-( c) but none of the editor shortcuts.

Different apps take different approaches to solving this problem. In Safari (and macOS apps that use the OS keyboard shortcut localization) cmd-[ is "back" and it is mapped to cmd-^ on Azerty (conveniently the same physical key, though this is not true for all layouts). cmd-shift-[ is "previous tab", but this shortcut is not mapped on an azerty keyboard. In VSCode cmd-[ is outdent, and it is mapped to cmd-control-option-shift-( on an azerty layout. They also define option-[ and option-cmd-[, but neither are available on an AZERTY layout.

For Zed, I'd like to ensure that every keyboard can type every binding; without making it feel too bizarre.

1. The first option is to copy the system default behavior (but go further), so that during shortcut handling we use the mapped keys from the system along with the modifiers you type. This means that cmd-^ becomes outdent, option-cmd-^ becomes editor::UnfoldLines, option-^ becomes previous inline completion, and in vim normal mode you would type ^c for the git diff.
2. The second option is to try and avoid moving keys around, but handle the option conflict by splitting the two option keys such that the one of the left means "option-" and the one of the right is used to select the key. In this case to type cmd-[ you'd type cmd-right_option-shift-(, option-[ would become left_option-right_option-shift-( and cmd-option-[ would be cmd-left_option-right_option-[. In vim normal mode you'd type right_option-shift-[ c.
3. A compromise between the two: cmd-^ becomes outdent, option-cmd-^ becomes editor::UnfoldLines, option-^ becomes previous inline completion, and in vim normal mode you would type option-shift-( c for the git diff. This only works because option-% is not bound to anything. If option-% were to be bound to something then left_option-shift-( would trigger option-% and right_option-shift-( would trigger [. (Similarly in the terminal you could trigger zsh's repeat 5 times with left_option-( and type a { with right_option-().

Do any of those sound like they'd work for you?

[rcarlier]

The technical aspects escape me a little I admit...

But the option_as_meta setting seems to work in any (of my) case!!!

{
  "terminal": {
    "option_as_meta": false
  }
}

Thanks ;-)

[dragnev-dev]

Being unable to use the QWERTY shortcuts in Bulgarian layout is below my usability threshold. It's a behavior I haven't encountered in any other app. I have to switch to US just to copy/paste/save and then switch back to continue my work.

[JunkuiZhang]

For me that's exactly where I'd expect the quit shortcut would be. Because that's standard standard behavior in other apps and having it in Zed would have me not to think about it.

That's good, we do want to match your preference.

[ConradIrwin]

If we use char-based matching here, Bulgarian and Russian layouts users may be unable to use h j k l commands for vim mode.

@JunkuiZhang I think we need to do both. In this case when you type the key with no modifiers you either get KeyEvent { key: 'h', modifiers: None, alt_key: Some('г')} or KeyEvent { key: 'г', modifiers: None, alt_key: Some('h')}. But we probably need to try and implement it before getting too concrete.

The other thing I've found while doing some work on mapping the keyboards is that many keyboards do not set up cmd-shift characters "correctly". I.e. on a Norwegian keyboard, cmd+shift+3 reports "3" as .characters. I think we probably do need to do something more virtual-key/shift aware to make the long tail of keyboards work as we want.

[JunkuiZhang]

@ConradIrwin Makes sense. I will try to implement a demo tomorrow, it's 1am in China, so, good night!

[JunkuiZhang]

@dragnev-dev How would you prefer the shortcuts to be displayed? On my mac, when I switch to the Bulgarian layout, the Quit action in Xcode still shows as cmd-q, even though on the keyboard it’s actually cmd-,.

[dragnev-dev]

By displayed you mean how it is shown in the button in the cascade menus? Honestly I haven't thought about it. Both vscode and webstorm show ctrl-q. I think I'm aligned to stick to that design, though honestly I don't care.

[ConradIrwin]

Thanks for all the input here!

I now am confident about what we should do for macOS, and think that it will generalize to Linux.

The goals again are:

• To make it possible for everyone to type all of Zed's builtin keybindings by default.
• To make common keyboard shortcuts feel the same as they do in other macOS apps.
• To keep it reasonably easy to create your own custom mappings.

There are three kinds of keyboard layout to consider:

1. ANSI layouts (with 104 keys) that are "ASCII" (e.g. QWERTY, Dvorak, Colemak)
2. ANSI layouts that are non-ASCII (e.g. Bulgarian, Japanese)
3. ISO layouts (with 105 keys) that are extended-ASCII (e.g. QWERTZ, AZERTY, Czech)

If you have a keyboard in group 1, then nothing will change. If you see cmd-[ in the shortcuts file, you will see cmd-[ in the UI and trigger the shortcut by typing the key that produces [ and the command modifier.

If you have a keyboard in group 2, then you will gain the ability to type Zed shortcuts using the QWERTY equivalent key positions (this does not work today). As far as I can tell, macOS prints a qwerty layout on these keyboards, and so we will continue to render cmd-[ in the UI and you will trigger the shortcut by typing the key labelled with [ and the command modifier.

If you have a keyboard in group 3, more work is needed. We will solve this by configuring a remapping for each layout that moves the shortcuts around. For example on a QWERTZ keyboard if cmd-[ is listed in the shortcut file we will show cmd-ö in the UI and you will hit the shortcut by typing the ö key with the cmd modifier. This mapping is defined so that shortcuts which can be typed don't move (cmd-a on an Azerty layout requires typing the same key as a), the numbers and their shift characters remain in the same physical location (cmd-^ will still be typed with cmd + shift + the key in the 6 position, but would be displayed in the UI as cmd-shift-ž on a Czech keyboard).

Zed will ship with builtin mappings for the macOS builtin remappings so that shortcuts remain the same between apps, and we'll let you configure the map in your settings. On Linux we'll do the same as macOS, though I'm less sure if we can provide the default mappings. On Windows, the operating system already provides the mapping layer for us, and so we will use the windows virtual key code system (in common with other apps).

And then...

There are three other pieces to the puzzle I'd like to support:

• In vim mode, typing a $ goes to the end of the line. On some keyboards $ requires the option- modifier. This means that you wouldn't be able to use vim.
• In your custom keybinding file, it's nice to be able to type the "right" key for you, and have zed know what that means.

In both cases we need to know "what character does the key actually correspond to". In most cases this is unambiguous (we don't have anything bound to option-4 and so on a Czech layout in vim normal mode that can type $).

For the cases where there are conflicts (this happens today with shortcuts that only require option- on Mac, on keyboard layouts where option-X is a commonly used character you want to type), I'd like to add a setting (like option_as_meta in the terminal) that allows you to change the precedence. For example if you have option_as_meta: "left" then you can use your left-option key to type option-4 and your right option key to type $. As today, if there is no ambiguity you can use either option key as you wish.

Please let me know if there's anything there which you think is not going to work for you!