bash: Readline Init File Syntax
1
1 8.3.1 Readline Init File Syntax
1 -------------------------------
1
1 There are only a few basic constructs allowed in the Readline init file.
1 Blank lines are ignored. Lines beginning with a '#' are comments.
11 Lines beginning with a '$' indicate conditional constructs (⇒
Conditional Init Constructs). Other lines denote variable settings
1 and key bindings.
1
1 Variable Settings
1 You can modify the run-time behavior of Readline by altering the
1 values of variables in Readline using the 'set' command within the
1 init file. The syntax is simple:
1
1 set VARIABLE VALUE
1
1 Here, for example, is how to change from the default Emacs-like key
1 binding to use 'vi' line editing commands:
1
1 set editing-mode vi
1
1 Variable names and values, where appropriate, are recognized
1 without regard to case. Unrecognized variable names are ignored.
1
1 Boolean variables (those that can be set to on or off) are set to
1 on if the value is null or empty, ON (case-insensitive), or 1. Any
1 other value results in the variable being set to off.
1
1 The 'bind -V' command lists the current Readline variable names and
1 values. ⇒Bash Builtins.
1
1 A great deal of run-time behavior is changeable with the following
1 variables.
1
1 'bell-style'
1 Controls what happens when Readline wants to ring the terminal
1 bell. If set to 'none', Readline never rings the bell. If
1 set to 'visible', Readline uses a visible bell if one is
1 available. If set to 'audible' (the default), Readline
1 attempts to ring the terminal's bell.
1
1 'bind-tty-special-chars'
1 If set to 'on' (the default), Readline attempts to bind the
1 control characters treated specially by the kernel's terminal
1 driver to their Readline equivalents.
1
1 'blink-matching-paren'
1 If set to 'on', Readline attempts to briefly move the cursor
1 to an opening parenthesis when a closing parenthesis is
1 inserted. The default is 'off'.
1
1 'colored-completion-prefix'
1 If set to 'on', when listing completions, Readline displays
1 the common prefix of the set of possible completions using a
1 different color. The color definitions are taken from the
1 value of the 'LS_COLORS' environment variable. The default is
1 'off'.
1
1 'colored-stats'
1 If set to 'on', Readline displays possible completions using
1 different colors to indicate their file type. The color
1 definitions are taken from the value of the 'LS_COLORS'
1 environment variable. The default is 'off'.
1
1 'comment-begin'
1 The string to insert at the beginning of the line when the
1 'insert-comment' command is executed. The default value is
1 '"#"'.
1
1 'completion-display-width'
1 The number of screen columns used to display possible matches
1 when performing completion. The value is ignored if it is
1 less than 0 or greater than the terminal screen width. A
1 value of 0 will cause matches to be displayed one per line.
1 The default value is -1.
1
1 'completion-ignore-case'
1 If set to 'on', Readline performs filename matching and
1 completion in a case-insensitive fashion. The default value
1 is 'off'.
1
1 'completion-map-case'
1 If set to 'on', and COMPLETION-IGNORE-CASE is enabled,
1 Readline treats hyphens ('-') and underscores ('_') as
1 equivalent when performing case-insensitive filename matching
1 and completion.
1
1 'completion-prefix-display-length'
1 The length in characters of the common prefix of a list of
1 possible completions that is displayed without modification.
1 When set to a value greater than zero, common prefixes longer
1 than this value are replaced with an ellipsis when displaying
1 possible completions.
1
1 'completion-query-items'
1 The number of possible completions that determines when the
1 user is asked whether the list of possibilities should be
1 displayed. If the number of possible completions is greater
1 than this value, Readline will ask the user whether or not he
1 wishes to view them; otherwise, they are simply listed. This
1 variable must be set to an integer value greater than or equal
1 to 0. A negative value means Readline should never ask. The
1 default limit is '100'.
1
1 'convert-meta'
1 If set to 'on', Readline will convert characters with the
1 eighth bit set to an ASCII key sequence by stripping the
1 eighth bit and prefixing an <ESC> character, converting them
1 to a meta-prefixed key sequence. The default value is 'on',
1 but will be set to 'off' if the locale is one that contains
1 eight-bit characters.
1
1 'disable-completion'
1 If set to 'On', Readline will inhibit word completion.
1 Completion characters will be inserted into the line as if
1 they had been mapped to 'self-insert'. The default is 'off'.
1
1 'echo-control-characters'
1 When set to 'on', on operating systems that indicate they
1 support it, readline echoes a character corresponding to a
1 signal generated from the keyboard. The default is 'on'.
1
1 'editing-mode'
1 The 'editing-mode' variable controls which default set of key
1 bindings is used. By default, Readline starts up in Emacs
1 editing mode, where the keystrokes are most similar to Emacs.
1 This variable can be set to either 'emacs' or 'vi'.
1
1 'emacs-mode-string'
1 This string is displayed immediately before the last line of
1 the primary prompt when emacs editing mode is active. The
1 value is expanded like a key binding, so the standard set of
1 meta- and control prefixes and backslash escape sequences is
1 available. Use the '\1' and '\2' escapes to begin and end
1 sequences of non-printing characters, which can be used to
1 embed a terminal control sequence into the mode string. The
1 default is '@'.
1
1 'enable-bracketed-paste'
1 When set to 'On', Readline will configure the terminal in a
1 way that will enable it to insert each paste into the editing
1 buffer as a single string of characters, instead of treating
1 each character as if it had been read from the keyboard. This
1 can prevent pasted characters from being interpreted as
1 editing commands. The default is 'off'.
1
1 'enable-keypad'
1 When set to 'on', Readline will try to enable the application
1 keypad when it is called. Some systems need this to enable
1 the arrow keys. The default is 'off'.
1
1 'enable-meta-key'
1 When set to 'on', Readline will try to enable any meta
1 modifier key the terminal claims to support when it is called.
1 On many terminals, the meta key is used to send eight-bit
1 characters. The default is 'on'.
1
1 'expand-tilde'
1 If set to 'on', tilde expansion is performed when Readline
1 attempts word completion. The default is 'off'.
1
1 'history-preserve-point'
1 If set to 'on', the history code attempts to place the point
1 (the current cursor position) at the same location on each
1 history line retrieved with 'previous-history' or
1 'next-history'. The default is 'off'.
1
1 'history-size'
1 Set the maximum number of history entries saved in the history
1 list. If set to zero, any existing history entries are
1 deleted and no new entries are saved. If set to a value less
1 than zero, the number of history entries is not limited. By
1 default, the number of history entries is not limited. If an
1 attempt is made to set HISTORY-SIZE to a non-numeric value,
1 the maximum number of history entries will be set to 500.
1
1 'horizontal-scroll-mode'
1 This variable can be set to either 'on' or 'off'. Setting it
1 to 'on' means that the text of the lines being edited will
1 scroll horizontally on a single screen line when they are
1 longer than the width of the screen, instead of wrapping onto
1 a new screen line. By default, this variable is set to 'off'.
1
1 'input-meta'
1 If set to 'on', Readline will enable eight-bit input (it will
1 not clear the eighth bit in the characters it reads),
1 regardless of what the terminal claims it can support. The
1 default value is 'off', but Readline will set it to 'on' if
1 the locale contains eight-bit characters. The name
1 'meta-flag' is a synonym for this variable.
1
1 'isearch-terminators'
1 The string of characters that should terminate an incremental
1 search without subsequently executing the character as a
1 command (⇒Searching). If this variable has not been
1 given a value, the characters <ESC> and 'C-J' will terminate
1 an incremental search.
1
1 'keymap'
1 Sets Readline's idea of the current keymap for key binding
1 commands. Acceptable 'keymap' names are 'emacs',
1 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
1 'vi-command', and 'vi-insert'. 'vi' is equivalent to
1 'vi-command' ('vi-move' is also a synonym); 'emacs' is
1 equivalent to 'emacs-standard'. The default value is 'emacs'.
1 The value of the 'editing-mode' variable also affects the
1 default keymap.
1
1 'keyseq-timeout'
1 Specifies the duration Readline will wait for a character when
1 reading an ambiguous key sequence (one that can form a
1 complete key sequence using the input read so far, or can take
1 additional input to complete a longer key sequence). If no
1 input is received within the timeout, Readline will use the
1 shorter but complete key sequence. Readline uses this value
1 to determine whether or not input is available on the current
1 input source ('rl_instream' by default). The value is
1 specified in milliseconds, so a value of 1000 means that
1 Readline will wait one second for additional input. If this
1 variable is set to a value less than or equal to zero, or to a
1 non-numeric value, Readline will wait until another key is
1 pressed to decide which key sequence to complete. The default
1 value is '500'.
1
1 'mark-directories'
1 If set to 'on', completed directory names have a slash
1 appended. The default is 'on'.
1
1 'mark-modified-lines'
1 This variable, when set to 'on', causes Readline to display an
1 asterisk ('*') at the start of history lines which have been
1 modified. This variable is 'off' by default.
1
1 'mark-symlinked-directories'
1 If set to 'on', completed names which are symbolic links to
1 directories have a slash appended (subject to the value of
1 'mark-directories'). The default is 'off'.
1
1 'match-hidden-files'
1 This variable, when set to 'on', causes Readline to match
1 files whose names begin with a '.' (hidden files) when
1 performing filename completion. If set to 'off', the leading
1 '.' must be supplied by the user in the filename to be
1 completed. This variable is 'on' by default.
1
1 'menu-complete-display-prefix'
1 If set to 'on', menu completion displays the common prefix of
1 the list of possible completions (which may be empty) before
1 cycling through the list. The default is 'off'.
1
1 'output-meta'
1 If set to 'on', Readline will display characters with the
1 eighth bit set directly rather than as a meta-prefixed escape
1 sequence. The default is 'off', but Readline will set it to
1 'on' if the locale contains eight-bit characters.
1
1 'page-completions'
1 If set to 'on', Readline uses an internal 'more'-like pager to
1 display a screenful of possible completions at a time. This
1 variable is 'on' by default.
1
1 'print-completions-horizontally'
1 If set to 'on', Readline will display completions with matches
1 sorted horizontally in alphabetical order, rather than down
1 the screen. The default is 'off'.
1
1 'revert-all-at-newline'
1 If set to 'on', Readline will undo all changes to history
1 lines before returning when 'accept-line' is executed. By
1 default, history lines may be modified and retain individual
1 undo lists across calls to 'readline'. The default is 'off'.
1
1 'show-all-if-ambiguous'
1 This alters the default behavior of the completion functions.
1 If set to 'on', words which have more than one possible
1 completion cause the matches to be listed immediately instead
1 of ringing the bell. The default value is 'off'.
1
1 'show-all-if-unmodified'
1 This alters the default behavior of the completion functions
1 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
1 'on', words which have more than one possible completion
1 without any possible partial completion (the possible
1 completions don't share a common prefix) cause the matches to
1 be listed immediately instead of ringing the bell. The
1 default value is 'off'.
1
1 'show-mode-in-prompt'
1 If set to 'on', add a character to the beginning of the prompt
1 indicating the editing mode: emacs, vi command, or vi
1 insertion. The mode strings are user-settable. The default
1 value is 'off'.
1
1 'skip-completed-text'
1 If set to 'on', this alters the default completion behavior
1 when inserting a single match into the line. It's only active
1 when performing completion in the middle of a word. If
1 enabled, readline does not insert characters from the
1 completion that match characters after point in the word being
1 completed, so portions of the word following the cursor are
1 not duplicated. For instance, if this is enabled, attempting
1 completion when the cursor is after the 'e' in 'Makefile' will
1 result in 'Makefile' rather than 'Makefilefile', assuming
1 there is a single possible completion. The default value is
1 'off'.
1
1 'vi-cmd-mode-string'
1 This string is displayed immediately before the last line of
1 the primary prompt when vi editing mode is active and in
1 command mode. The value is expanded like a key binding, so
1 the standard set of meta- and control prefixes and backslash
1 escape sequences is available. Use the '\1' and '\2' escapes
1 to begin and end sequences of non-printing characters, which
1 can be used to embed a terminal control sequence into the mode
1 string. The default is '(cmd)'.
1
1 'vi-ins-mode-string'
1 This string is displayed immediately before the last line of
1 the primary prompt when vi editing mode is active and in
1 insertion mode. The value is expanded like a key binding, so
1 the standard set of meta- and control prefixes and backslash
1 escape sequences is available. Use the '\1' and '\2' escapes
1 to begin and end sequences of non-printing characters, which
1 can be used to embed a terminal control sequence into the mode
1 string. The default is '(ins)'.
1
1 'visible-stats'
1 If set to 'on', a character denoting a file's type is appended
1 to the filename when listing possible completions. The
1 default is 'off'.
1
1 Key Bindings
1 The syntax for controlling key bindings in the init file is simple.
1 First you need to find the name of the command that you want to
1 change. The following sections contain tables of the command name,
1 the default keybinding, if any, and a short description of what the
1 command does.
1
1 Once you know the name of the command, simply place on a line in
1 the init file the name of the key you wish to bind the command to,
1 a colon, and then the name of the command. There can be no space
1 between the key name and the colon - that will be interpreted as
1 part of the key name. The name of the key can be expressed in
1 different ways, depending on what you find most comfortable.
1
1 In addition to command names, readline allows keys to be bound to a
1 string that is inserted when the key is pressed (a MACRO).
1
1 The 'bind -p' command displays Readline function names and bindings
1 in a format that can put directly into an initialization file.
1 ⇒Bash Builtins.
1
1 KEYNAME: FUNCTION-NAME or MACRO
1 KEYNAME is the name of a key spelled out in English. For
1 example:
1 Control-u: universal-argument
1 Meta-Rubout: backward-kill-word
1 Control-o: "> output"
1
1 In the above example, 'C-u' is bound to the function
1 'universal-argument', 'M-DEL' is bound to the function
1 'backward-kill-word', and 'C-o' is bound to run the macro
1 expressed on the right hand side (that is, to insert the text
1 '> output' into the line).
1
1 A number of symbolic character names are recognized while
1 processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
1 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
1
1 "KEYSEQ": FUNCTION-NAME or MACRO
1 KEYSEQ differs from KEYNAME above in that strings denoting an
1 entire key sequence can be specified, by placing the key
1 sequence in double quotes. Some GNU Emacs style key escapes
1 can be used, as in the following example, but the special
1 character names are not recognized.
1
1 "\C-u": universal-argument
1 "\C-x\C-r": re-read-init-file
1 "\e[11~": "Function Key 1"
1
1 In the above example, 'C-u' is again bound to the function
1 'universal-argument' (just as it was in the first example),
1 ''C-x' 'C-r'' is bound to the function 're-read-init-file',
1 and '<ESC> <[> <1> <1> <~>' is bound to insert the text
1 'Function Key 1'.
1
1 The following GNU Emacs style escape sequences are available when
1 specifying key sequences:
1
1 '\C-'
1 control prefix
1 '\M-'
1 meta prefix
1 '\e'
1 an escape character
1 '\\'
1 backslash
1 '\"'
1 <">, a double quotation mark
1 '\''
1 <'>, a single quote or apostrophe
1
1 In addition to the GNU Emacs style escape sequences, a second set
1 of backslash escapes is available:
1
1 '\a'
1 alert (bell)
1 '\b'
1 backspace
1 '\d'
1 delete
1 '\f'
1 form feed
1 '\n'
1 newline
1 '\r'
1 carriage return
1 '\t'
1 horizontal tab
1 '\v'
1 vertical tab
1 '\NNN'
1 the eight-bit character whose value is the octal value NNN
1 (one to three digits)
1 '\xHH'
1 the eight-bit character whose value is the hexadecimal value
1 HH (one or two hex digits)
1
1 When entering the text of a macro, single or double quotes must be
1 used to indicate a macro definition. Unquoted text is assumed to
1 be a function name. In the macro body, the backslash escapes
1 described above are expanded. Backslash will quote any other
1 character in the macro text, including '"' and '''. For example,
1 the following binding will make ''C-x' \' insert a single '\' into
1 the line:
1 "\C-x\\": "\\"
1