🗒 Bindkeys Map
Bindkey
The bindkey
key mappings can be very confusing to decipher. It can use multiple different notations but it's smart to use the same key notation throughout your configuration.
You can print all of your current key bindings in the current keymap with bindkey
. To print the full bindkey
command to add to your .zshrc
file use bindkey -L
.
In general you'll bind a widget so a key sequence or a key with modifier. This can be declared in caret notation using ^
, using escape sequences using \
, in octal (\NNN
), hex (\xNN
), or unicode (\uNNNN
). None of these are particularly great for people to read.
This is also tricky because it depends on your keyboard, operating system, and shell. Here are some basics
\e
,\E
, = Escape^[
= Alt key (on some keyboards this is the same as escape)^?
= Delete^X
,^
= Control
The keys that come after the modifier can add more confusion.
Delete key binding
To delete a key binding you can use bindkey -d $KEYS
.
Make sure you don't delete characters you need for typing.
The bindmap'…'
keybindings
Sometimes plugins call bindkey to assign keyboard shortcuts. This can cause problems because multiple plugins can bind the same keys.
Also, the user might want a different binding(s), which will require complicated, additional bindkey
commands in .zshrc
.
ZI provides a solution to this problem – the ability to remap the bindkeys with a short ice-modifier specification with the bindmap'…'
ice.
Examples for bindmap'…'
Map Ctrl-G instead of Ctrl-R for the history searcher.
zi bindmap'^R -> ^G' for z-shell/history-search-multi-word
Map Ctrl-Shift-Left and …-Right used by URxvt instead of the Xterms' ones. Load with the bindkey-tracking ↔ with light-loading for anything else.
Could also separate the bindmaps with a semicolon, i.e.:
bindmap'"\\e[1\;6D" -> \\e[1\;5D ; "\\e[1\;6C" -> ^[[1\;5C' \
zi wait light-mode trackbinds bindmap'"\\e[1\;6D" -> \\e[1\;5D"' \ bindmap'"\\e[1\;6C" -> ^[[1\;5C' pick'dircycle.zsh' for \ michaelxmcbride/zsh-dircycle
Map space to regular space and Ctrl-Space to the `globalias' widget, which expands the alias entered on the left, provided by OMZ globalias plugin.
zi bindmap='!" " -> magic-space; !"^ " -> globalias' nocompletions \ depth=1 pick=plugins/globalias/globalias.plugin.zsh for \ ohmyzsh/ohmyzsh
Explanation
The bindmap'…'
ice has two modes of operation: normal and exclamation-mark (bindmap'!…'
). In the first mode, the remapping is being done from-key to-key, i.e.: bindmap'fromkey -> to-key'
.
The given key is being changed to the second given key in the bindkey
command that's being issued when loading the plugin. In the second mode, the remapping is being done from-key to-widget, e.g: bindmap'!from-key -> to-widget'
.
In this mode, the given key is being mapped to the given widget instead of the widget specified in the bindkey
command e.g.:
Instead of:
bindkey "^ " magic-spacebindkey " " globalias
The actual call that'll be done will be:
bindkey "^ " globaliasbindkey " " magic-space
For the bindmap='!" " -> magic-space; !"^ " -> globalias'
ice.
Using bindmap'…'
in light mode
When the investigation mode is on i.e.:
- when the full loading mode is being used, default in the
for
syntax and whenzi load …
is used, then thebindmap'…'
ice works normally.
In the non-investigation:
- the light mode – activated when
zi light …
or thelight-mode
ice is being used – thebindmap'…'
is unavailable, unless thetrackbinds
ice is specified:
# With use of the light-mode ice and the for-syntax:zi light-mode trackbinds bindmap'^R -> ^G' for z-shell/history-search-multi-word
# With use of the classic syntax:zi trackbinds bindmap'^R -> ^G' for z-shell/history-search-multi-wordzi light z-shell/history-search-multi-word
Using the UPAR shorthands
There are four special values that can be used on the left side of the bind-map: UPAR, DOWNAR, LEFTAR, RIGHTAR. They'll match up arrow, down arrow, etc. So that it's possible to do:
zi bindmap='LEFTAR -> ^F; RIGHTAR -> ^G' …
The benefits of using the UPAR, … shorthands is that they cover multiple possible cursor-key codes for each of the cursor key, so that they'll work regardless of the terminal being used.