fish-shell/doc_src/bind.txt

\section bind bind - handle fish key bindings

\subsection bind-synopsis Synopsis
\fish{synopsis}
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE]
     [(-k | --key)] SEQUENCE COMMAND [COMMAND...]
bind [(-M | --mode) MODE] [(-k | --key)] SEQUENCE
bind (-K | --key-names) [(-a | --all)]
bind (-f | --function-names)
bind (-e | --erase) [(-M | --mode) MODE]
     (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])
\endfish

\subsection bind-description Description

`bind` adds a binding for the specified key sequence to the specified command.

SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{Control,X} (^X) can be written as `\cx`. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not `fish`.

The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.

If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `terminfo(5)` for more information, or use `bind --key-names` for a list of all available named keys.)

`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions.

When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.

If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order.

When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed.

If no `SEQUENCE` is provided, all bindings (or just the bindings in the specified `MODE`) are printed. If `SEQUENCE` is provided without `COMMAND`, just the binding matching that sequence is printed.

Key bindings are not saved between sessions by default. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements.

Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the `$fish_bind_mode` variable.

The following parameters are available:

- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence

- `-K` or `--key-names` Display a list of available key names. Specifying `-a` or `--all` includes keys that don't have a known mapping

- `-f` or `--function-names` Display a list of available input functions

- `-M MODE` or `--mode MODE` Specify a bind mode that the bind is used in. Defaults to "default"

- `-m NEW_MODE` or `--sets-mode NEW_MODE` Change the current mode to `NEW_MODE` after this binding is executed

- `-e` or `--erase` Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying `-a` or `--all` with `-M` or `--mode` erases all binds in the given mode regardless of sequence. Specifying `-a` or `--all` without `-M` or `--mode` erases all binds in all modes regardless of sequence.

- `-a` or `--all` See `--erase` and `--key-names`

The following special input functions are available:

- `backward-char`, moves one character to the left

- `backward-bigword`, move one whitespace-delimited word to the left

- `backward-delete-char`, deletes one character of input to the left of the cursor

- `backward-kill-bigword`, move the whitespace-delimited word to the left of the cursor to the killring

- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring

- `backward-kill-word`, move the word to the left of the cursor to the killring

- `backward-word`, move one word to the left

- `beginning-of-history`, move to the beginning of the history

- `beginning-of-line`, move to the beginning of the line

- `capitalize-word`, make the current word begin with a capital letter

- `complete`, guess the remainder of the current token

- `delete-char`, delete one character to the right of the cursor

- `delete-line`, delete the entire line

- `downcase-word`, make the current word lowercase

- `dump-functions`, print a list of all key-bindings

- `end-of-history`, move to the end of the history

- `end-of-line`, move to the end of the line

- `explain`, print a description of possible problems with the current command

- `forward-bigword`, move one whitespace-delimited word to the right

- `forward-char`, move one character to the right

- `forward-word`, move one word to the right

- `history-search-backward`, search the history for the previous match

- `history-search-forward`, search the history for the next match

- `kill-bigword`, move the next whitespace-delimited word to the killring

- `kill-line`, move everything from the cursor to the end of the line to the killring

- `kill-whole-line`, move the line to the killring

- `kill-word`, move the next word to the killring

- `upcase-word`, make the current word uppercase

- `yank`, insert the latest entry of the killring into the buffer

- `yank-pop`, rotate to the previous entry of the killring


\subsection bind-example Examples

\fish
bind \cd 'exit'
\endfish
Causes `fish` to exit when @key{Control,D} is pressed.

\fish
bind -k ppage history-search-backward
\endfish
Performs a history search when the @key{Page Up} key is pressed.

\fish
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \cc kill-whole-line force-repaint
\endfish
Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.


\subsection special-case-escape Special Case: The escape Character

Since the escape key (or character) plays two distinct roles it poses a special challenge for fish. In its first role it stands by itself. In Vi mode, for example, escape is used to switch from insert to normal (aka command) mode. In its second role escape is used as a <a href="https://en.wikipedia.org/wiki/Meta_key">"meta" key</a> where it is only the beginning of some longer character sequence. Coming back to the Vi mode example, sometimes fish is expected to realize that the escape key should be regarded as a meta key, meaning that the escape character is part of a multi-char sequence. Function keys (e.g., F1, F2, etc...) and arrow keys are common cases of multi-char sequences that begin with the escape character. Custom bindings can also be defined that begin with an escape character. Obviously, fish is not supposed to exit insert mode when the escape is part of a longer character sequence.

To be able distinguish between these two roles fish has to wait after it sees an escape character. In this waiting period any additional key presses make the escape key behave as a meta key. Otherwise, it remains an isolated escape key press. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the `fish_escape_delay_ms` variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.

Note: fish versions up thru 2.2.0 used a default of 10 ms and provided no way to configure it. That effectively made it impossible to use escape as a meta key.