bindkey
Configure keyboard shortcuts in zsh
TLDR
Bind a hotkey to a specific command
Bind a hotkey to a specific key [s]equence
[l]ist keymaps
View the hotkey in a key[M]ap
SYNOPSIS
bindkey [options] [key-sequence [widget-or-string]]
Examples:
bindkey
bindkey "^X^X" "transpose-chars"
bindkey -s "^K" "echo Hello\n"
bindkey -r "^D"
bindkey -m vicmd "j" "down-line"
PARAMETERS
-e
Sets the active keymap to the default emacs editing mode.
-v
Sets the active keymap to the default vi editing mode, starting in insert mode (viins).
-a
Applies the specified binding to all keymaps. This is useful for global bindings.
-m keymap
Specifies the keymap to which the binding operation will apply. Common keymaps include emacs, viins (vi insert mode), and vicmd (vi command mode).
-r key-sequence
Removes the binding for the specified key-sequence in the current or specified keymap.
-s key-sequence string
Binds the key-sequence to output a literal string (a macro). The string will be inserted into the buffer as if typed.
-L
Lists all keymaps and their bindings in a format suitable for inclusion in a .zshrc configuration file.
-l
Lists all available ZLE widgets (editor functions) that can be bound to key sequences.
key-sequence
The sequence of keystrokes to be bound. Can be literal characters, control characters (e.g., ^X or \C-X), meta characters (e.g., \M-X or \eX), or hexadecimal codes (\xHH).
widget-or-string
The ZLE widget name (e.g., accept-line, forward-char) or a literal string (when used with -s) that the key-sequence will execute or insert.
DESCRIPTION
bindkey is a fundamental builtin command in the Zsh shell, designed to manage and display key bindings for the Zsh Line Editor (ZLE). ZLE is the powerful interactive editor used by Zsh for command-line input. Through bindkey, users can extensively customize their command-line editing experience by associating specific sequences of keystrokes (key sequences) with predefined ZLE widgets (editor functions) or custom macros (arbitrary strings to be inserted or executed).
This command supports a wide array of key notations, including control characters (e.g., ^X), meta keys (M-x), and function keys, providing granular control over how the shell responds to user input. It also allows for the display of current key bindings, which is invaluable for understanding the editor's default behavior or debugging custom configurations. bindkey operates within different keymaps (such as emacs, viins, and vicmd), enabling context-specific bindings that change based on the editor's mode. It is an essential tool for anyone looking to personalize and optimize their Zsh interactive environment.
CAVEATS
bindkey is a Zsh-specific command and is not available in other shells like Bash, which uses the bind command for similar functionality based on the readline library.
Defining complex key sequences, especially those involving escape characters or terminal-specific codes, can sometimes be challenging.
Effective use often requires familiarity with ZLE widgets and their functions.
The order of bindings in configuration files matters, as later definitions for the same key sequence will override earlier ones.
KEYMAPS EXPLAINED
Keymaps in ZLE define sets of key bindings. Zsh comes with several standard keymaps, most notably emacs (default for Emacs-like editing) and viins (vi insert mode) and vicmd (vi command mode) for vi-like editing. Users can also create custom keymaps using zle -N and bindkey -N for highly specialized workflows or context-dependent behaviors.
WIDGET VS. STRING BINDING
When using bindkey without -s, a key-sequence is bound to a ZLE widget. Widgets are predefined C functions within ZLE that perform specific editor actions (e.g., moving the cursor, deleting text, completing commands). When using -s (for string binding), the key-sequence inserts a literal string into the command buffer, acting as a macro. This distinction is crucial for understanding whether you're triggering an editor function or simply inserting text.
KEY SEQUENCE NOTATION
bindkey accepts various notations for key sequences. Common examples include:
- Literal characters: "a"
- Control characters: "^A" or "\C-a"
- Meta/Alt characters: "\M-a" or "\ea" (where \e is the escape character)
- Function keys and special keys: often represented by escape sequences, e.g., "\e[A" for Up Arrow (though bindkey -L typically shows canonical forms for these).
- Hexadecimal byte values: "\x1b" for Escape.
HISTORY
The bindkey command is an intrinsic part of the Zsh shell, evolving with it to provide sophisticated line editing capabilities. While its functionality is conceptually similar to the bind command found in shells like Bash (which rely on the GNU readline library), bindkey is specific to Zsh's proprietary Zsh Line Editor (ZLE). Its development reflects Zsh's commitment to highly customizable and powerful interactive shell environments, allowing users to tailor keyboard shortcuts and macros to an unprecedented degree for enhanced productivity.