fish-common 2.4.0-1 / usr / share / fish / man / man1 / bind.1

.TH "bind" 1 "Sun Dec 11 2016" "Version 2.4.0" "fish" \" -*- nroff -*-
.ad l
.nh
.SH NAME
\fBbind\fP -- handle fish key bindings 

.PP
.SS "Synopsis"
.PP
.nf

\fBbind\fP [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE]
     [(-k | --key)] SEQUENCE COMMAND [COMMAND\&.\&.\&.]
\fBbind\fP [(-M | --mode) MODE] [(-k | --key)] SEQUENCE
\fBbind\fP (-K | --key-names) [(-a | --all)]
\fBbind\fP (-f | --function-names)
\fBbind\fP (-e | --erase) [(-M | --mode) MODE]
     (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE\&.\&.\&.])
.fi
.PP
.SS "Description"
\fCbind\fP adds a binding for the specified key sequence to the specified command\&.
.PP
SEQUENCE is the character sequence to bind to\&. These should be written as \fCfish escape sequences\fP\&. 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 \fC\\e\fP escape\&. For example, [\fBAlt\fP-\fIw\fP] can be written as \fC\\ew\fP\&. The control character can be written in much the same way using the \fC\\c\fP escape, for example [\fBControl\fP-\fIX\fP] (^X) can be written as \fC\\cx\fP\&. 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 \fCfish\fP\&.
.PP
The default key binding can be set by specifying a \fCSEQUENCE\fP of the empty string (that is, \fC''\fP )\&. It will be used whenever no other binding matches\&. For most key bindings, it makes sense to use the \fCself-insert\fP function (i\&.e\&. \fCbind '' self-insert\fP) 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\&.
.PP
If the \fC-k\fP 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 \fCterminfo(5)\fP for more information, or use \fCbind --key-names\fP for a list of all available named keys\&.)
.PP
\fCCOMMAND\fP 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 \fCbind --function-names\fP for a complete list of these input functions\&.
.PP
When \fCCOMMAND\fP is a shellscript command, it is a good practice to put the actual code into a \fCfunction\fP 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\&.
.PP
If such a script produces output, the script needs to finish by calling \fCcommandline -f repaint\fP in order to tell fish that a repaint is in order\&.
.PP
When multiple \fCCOMMAND\fPs are provided, they are all run in the specified order when the key is pressed\&.
.PP
If no \fCSEQUENCE\fP is provided, all bindings (or just the bindings in the specified \fCMODE\fP) are printed\&. If \fCSEQUENCE\fP is provided without \fCCOMMAND\fP, just the binding matching that sequence is printed\&.
.PP
Key bindings are not saved between sessions by default\&. \fBBare \fCbind\fP statements in \fCconfig\&.fish\fP won't have any effect because it is sourced before the default keybindings are setup\&.\fP To save custom keybindings, put the \fCbind\fP statements into a function called \fCfish_user_key_bindings\fP, which will be \fCautoloaded\fP\&.
.PP
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 \fC$fish_bind_mode\fP variable\&.
.PP
The following parameters are available:
.PP
.IP "\(bu" 2
\fC-k\fP or \fC--key\fP Specify a key name, such as 'left' or 'backspace' instead of a character sequence
.IP "\(bu" 2
\fC-K\fP or \fC--key-names\fP Display a list of available key names\&. Specifying \fC-a\fP or \fC--all\fP includes keys that don't have a known mapping
.IP "\(bu" 2
\fC-f\fP or \fC--function-names\fP Display a list of available input functions
.IP "\(bu" 2
\fC-M MODE\fP or \fC--mode MODE\fP Specify a bind mode that the bind is used in\&. Defaults to 'default'
.IP "\(bu" 2
\fC-m NEW_MODE\fP or \fC--sets-mode NEW_MODE\fP Change the current mode to \fCNEW_MODE\fP after this binding is executed
.IP "\(bu" 2
\fC-e\fP or \fC--erase\fP Erase the binding with the given sequence and mode instead of defining a new one\&. Multiple sequences can be specified with this flag\&. Specifying \fC-a\fP or \fC--all\fP with \fC-M\fP or \fC--mode\fP erases all binds in the given mode regardless of sequence\&. Specifying \fC-a\fP or \fC--all\fP without \fC-M\fP or \fC--mode\fP erases all binds in all modes regardless of sequence\&.
.IP "\(bu" 2
\fC-a\fP or \fC--all\fP See \fC--erase\fP and \fC--key-names\fP
.PP
.PP
The following special input functions are available:
.PP
.IP "\(bu" 2
\fCaccept-autosuggestion\fP, accept the current autosuggestion completely
.IP "\(bu" 2
\fCbackward-char\fP, moves one character to the left
.IP "\(bu" 2
\fCbackward-bigword\fP, move one whitespace-delimited word to the left
.IP "\(bu" 2
\fCbackward-delete-char\fP, deletes one character of input to the left of the cursor
.IP "\(bu" 2
\fCbackward-kill-bigword\fP, move the whitespace-delimited word to the left of the cursor to the killring
.IP "\(bu" 2
\fCbackward-kill-line\fP, move everything from the beginning of the line to the cursor to the killring
.IP "\(bu" 2
\fCbackward-kill-path-component\fP, move one path component to the left of the cursor (everything from the last '/' or whitespace exclusive) to the killring
.IP "\(bu" 2
\fCbackward-kill-word\fP, move the word to the left of the cursor to the killring
.IP "\(bu" 2
\fCbackward-word\fP, move one word to the left
.IP "\(bu" 2
\fCbeginning-of-history\fP, move to the beginning of the history
.IP "\(bu" 2
\fCbeginning-of-line\fP, move to the beginning of the line
.IP "\(bu" 2
\fCbegin-selection\fP, start selecting text
.IP "\(bu" 2
\fCcapitalize-word\fP, make the current word begin with a capital letter
.IP "\(bu" 2
\fCcomplete\fP, guess the remainder of the current token
.IP "\(bu" 2
\fCcomplete-and-search\fP, invoke the searchable pager on completion options
.IP "\(bu" 2
\fCdelete-char\fP, delete one character to the right of the cursor
.IP "\(bu" 2
\fCdowncase-word\fP, make the current word lowercase
.IP "\(bu" 2
\fCend-of-history\fP, move to the end of the history
.IP "\(bu" 2
\fCend-of-line\fP, move to the end of the line
.IP "\(bu" 2
\fCend-selection\fP, end selecting text
.IP "\(bu" 2
\fCforward-bigword\fP, move one whitespace-delimited word to the right
.IP "\(bu" 2
\fCforward-char\fP, move one character to the right
.IP "\(bu" 2
\fCforward-word\fP, move one word to the right
.IP "\(bu" 2
\fChistory-search-backward\fP, search the history for the previous match
.IP "\(bu" 2
\fChistory-search-forward\fP, search the history for the next match
.IP "\(bu" 2
\fCkill-bigword\fP, move the next whitespace-delimited word to the killring
.IP "\(bu" 2
\fCkill-line\fP, move everything from the cursor to the end of the line to the killring
.IP "\(bu" 2
\fCkill-selection\fP, move the selected text to the killring
.IP "\(bu" 2
\fCkill-whole-line\fP, move the line to the killring
.IP "\(bu" 2
\fCkill-word\fP, move the next word to the killring
.IP "\(bu" 2
\fCsuppress-autosuggestion\fP, remove the current autosuggestion
.IP "\(bu" 2
\fCswap-selection-start-stop\fP, go to the other end of the highlighted text without changing the selection
.IP "\(bu" 2
\fCtranspose-chars\fP, transpose two characters to the left of the cursor
.IP "\(bu" 2
\fCtranspose-words\fP, transpose two words to the left of the cursor
.IP "\(bu" 2
\fCupcase-word\fP, make the current word uppercase
.IP "\(bu" 2
\fCyank\fP, insert the latest entry of the killring into the buffer
.IP "\(bu" 2
\fCyank-pop\fP, rotate to the previous entry of the killring
.PP
.SS "Examples"
.PP
.nf

\fBbind\fP \\cd 'exit'
.fi
.PP
 Causes \fCfish\fP to exit when [\fBControl\fP-\fID\fP] is pressed\&.
.PP
.PP
.nf

\fBbind\fP -k ppage history-search-backward
.fi
.PP
 Performs a history search when the [\fBPage Up\fP] key is pressed\&.
.PP
.PP
.nf

\fBset\fP -g fish_key_bindings fish_vi_key_bindings
\fBbind\fP -M insert \\cc kill-whole-line force-repaint
.fi
.PP
 Turns on Vi key bindings and rebinds [\fBControl\fP-\fIC\fP] to clear the input line\&.
.SS "Special Case: The escape Character"
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings\&. Escape may also be used as a 'meta' key, to indicate the start of an escape sequence, such as function or arrow keys\&. Custom bindings can also be defined that begin with an escape character\&.
.PP
fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence\&. While waiting, additional key presses make the escape key behave as a meta key\&. If no other key presses come in, it is handled as a standalone escape\&. 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 \fCfish_escape_delay_ms\fP 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\&.
.PP
Note: fish 2\&.2\&.0 and earlier used a default of 10 milliseconds, and provided no way to configure it\&. That effectively made it impossible to use escape as a meta key\&.