1@comment %**start of header (This is for running Texinfo on a region.) 2@setfilename rluser.info 3@comment %**end of header (This is for running Texinfo on a region.) 4 5@ignore 6This file documents the end user interface to the GNU command line 7editing features. It is to be an appendix to manuals for programs which 8use these features. There is a document entitled "readline.texinfo" 9which contains both end-user and programmer documentation for the 10GNU Readline Library. 11 12Copyright (C) 1988--2020 Free Software Foundation, Inc. 13 14Authored by Brian Fox and Chet Ramey. 15 16Permission is granted to process this file through Tex and print the 17results, provided the printed document carries copying permission notice 18identical to this one except for the removal of this paragraph (this 19paragraph not being relevant to the printed manual). 20 21Permission is granted to make and distribute verbatim copies of this manual 22provided the copyright notice and this permission notice are preserved on 23all copies. 24 25Permission is granted to copy and distribute modified versions of this 26manual under the conditions for verbatim copying, provided also that the 27GNU Copyright statement is available to the distributee, and provided that 28the entire resulting derived work is distributed under the terms of a 29permission notice identical to this one. 30 31Permission is granted to copy and distribute translations of this manual 32into another language, under the above conditions for modified versions. 33@end ignore 34 35@comment If you are including this manual as an appendix, then set the 36@comment variable readline-appendix. 37 38@ifclear BashFeatures 39@defcodeindex bt 40@end ifclear 41 42@node Command Line Editing 43@chapter Command Line Editing 44 45This chapter describes the basic features of the @sc{gnu} 46command line editing interface. 47@ifset BashFeatures 48Command line editing is provided by the Readline library, which is 49used by several different programs, including Bash. 50Command line editing is enabled by default when using an interactive shell, 51unless the @option{--noediting} option is supplied at shell invocation. 52Line editing is also used when using the @option{-e} option to the 53@code{read} builtin command (@pxref{Bash Builtins}). 54By default, the line editing commands are similar to those of Emacs. 55A vi-style line editing interface is also available. 56Line editing can be enabled at any time using the @option{-o emacs} or 57@option{-o vi} options to the @code{set} builtin command 58(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or 59@option{+o vi} options to @code{set}. 60@end ifset 61 62@menu 63* Introduction and Notation:: Notation used in this text. 64* Readline Interaction:: The minimum set of commands for editing a line. 65* Readline Init File:: Customizing Readline from a user's view. 66* Bindable Readline Commands:: A description of most of the Readline commands 67 available for binding 68* Readline vi Mode:: A short description of how to make Readline 69 behave like the vi editor. 70@ifset BashFeatures 71* Programmable Completion:: How to specify the possible completions for 72 a specific command. 73* Programmable Completion Builtins:: Builtin commands to specify how to 74 complete arguments for a particular command. 75* A Programmable Completion Example:: An example shell function for 76 generating possible completions. 77@end ifset 78@end menu 79 80@node Introduction and Notation 81@section Introduction to Line Editing 82 83The following paragraphs describe the notation used to represent 84keystrokes. 85 86The text @kbd{C-k} is read as `Control-K' and describes the character 87produced when the @key{k} key is pressed while the Control key 88is depressed. 89 90The text @kbd{M-k} is read as `Meta-K' and describes the character 91produced when the Meta key (if you have one) is depressed, and the @key{k} 92key is pressed. 93The Meta key is labeled @key{ALT} on many keyboards. 94On keyboards with two keys labeled @key{ALT} (usually to either side of 95the space bar), the @key{ALT} on the left side is generally set to 96work as a Meta key. 97The @key{ALT} key on the right may also be configured to work as a 98Meta key or may be configured as some other modifier, such as a 99Compose key for typing accented characters. 100 101If you do not have a Meta or @key{ALT} key, or another key working as 102a Meta key, the identical keystroke can be generated by typing @key{ESC} 103@emph{first}, and then typing @key{k}. 104Either process is known as @dfn{metafying} the @key{k} key. 105 106The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the 107character produced by @dfn{metafying} @kbd{C-k}. 108 109In addition, several keys have their own names. Specifically, 110@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all 111stand for themselves when seen in this text, or in an init file 112(@pxref{Readline Init File}). 113If your keyboard lacks a @key{LFD} key, typing @key{C-j} will 114produce the desired character. 115The @key{RET} key may be labeled @key{Return} or @key{Enter} on 116some keyboards. 117 118@node Readline Interaction 119@section Readline Interaction 120@cindex interaction, readline 121 122Often during an interactive session you type in a long line of text, 123only to notice that the first word on the line is misspelled. The 124Readline library gives you a set of commands for manipulating the text 125as you type it in, allowing you to just fix your typo, and not forcing 126you to retype the majority of the line. Using these editing commands, 127you move the cursor to the place that needs correction, and delete or 128insert the text of the corrections. Then, when you are satisfied with 129the line, you simply press @key{RET}. You do not have to be at the 130end of the line to press @key{RET}; the entire line is accepted 131regardless of the location of the cursor within the line. 132 133@menu 134* Readline Bare Essentials:: The least you need to know about Readline. 135* Readline Movement Commands:: Moving about the input line. 136* Readline Killing Commands:: How to delete text, and how to get it back! 137* Readline Arguments:: Giving numeric arguments to commands. 138* Searching:: Searching through previous lines. 139@end menu 140 141@node Readline Bare Essentials 142@subsection Readline Bare Essentials 143@cindex notation, readline 144@cindex command editing 145@cindex editing command lines 146 147In order to enter characters into the line, simply type them. The typed 148character appears where the cursor was, and then the cursor moves one 149space to the right. If you mistype a character, you can use your 150erase character to back up and delete the mistyped character. 151 152Sometimes you may mistype a character, and 153not notice the error until you have typed several other characters. In 154that case, you can type @kbd{C-b} to move the cursor to the left, and then 155correct your mistake. Afterwards, you can move the cursor to the right 156with @kbd{C-f}. 157 158When you add text in the middle of a line, you will notice that characters 159to the right of the cursor are `pushed over' to make room for the text 160that you have inserted. Likewise, when you delete text behind the cursor, 161characters to the right of the cursor are `pulled back' to fill in the 162blank space created by the removal of the text. A list of the bare 163essentials for editing the text of an input line follows. 164 165@table @asis 166@item @kbd{C-b} 167Move back one character. 168@item @kbd{C-f} 169Move forward one character. 170@item @key{DEL} or @key{Backspace} 171Delete the character to the left of the cursor. 172@item @kbd{C-d} 173Delete the character underneath the cursor. 174@item @w{Printing characters} 175Insert the character into the line at the cursor. 176@item @kbd{C-_} or @kbd{C-x C-u} 177Undo the last editing command. You can undo all the way back to an 178empty line. 179@end table 180 181@noindent 182(Depending on your configuration, the @key{Backspace} key be set to 183delete the character to the left of the cursor and the @key{DEL} key set 184to delete the character underneath the cursor, like @kbd{C-d}, rather 185than the character to the left of the cursor.) 186 187@node Readline Movement Commands 188@subsection Readline Movement Commands 189 190 191The above table describes the most basic keystrokes that you need 192in order to do editing of the input line. For your convenience, many 193other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, 194@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly 195about the line. 196 197@table @kbd 198@item C-a 199Move to the start of the line. 200@item C-e 201Move to the end of the line. 202@item M-f 203Move forward a word, where a word is composed of letters and digits. 204@item M-b 205Move backward a word. 206@item C-l 207Clear the screen, reprinting the current line at the top. 208@end table 209 210Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves 211forward a word. It is a loose convention that control keystrokes 212operate on characters while meta keystrokes operate on words. 213 214@node Readline Killing Commands 215@subsection Readline Killing Commands 216 217@cindex killing text 218@cindex yanking text 219 220@dfn{Killing} text means to delete the text from the line, but to save 221it away for later use, usually by @dfn{yanking} (re-inserting) 222it back into the line. 223(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) 224 225If the description for a command says that it `kills' text, then you can 226be sure that you can get the text back in a different (or the same) 227place later. 228 229When you use a kill command, the text is saved in a @dfn{kill-ring}. 230Any number of consecutive kills save all of the killed text together, so 231that when you yank it back, you get it all. The kill 232ring is not line specific; the text that you killed on a previously 233typed line is available to be yanked back later, when you are typing 234another line. 235@cindex kill ring 236 237Here is the list of commands for killing text. 238 239@table @kbd 240@item C-k 241Kill the text from the current cursor position to the end of the line. 242 243@item M-d 244Kill from the cursor to the end of the current word, or, if between 245words, to the end of the next word. 246Word boundaries are the same as those used by @kbd{M-f}. 247 248@item M-@key{DEL} 249Kill from the cursor the start of the current word, or, if between 250words, to the start of the previous word. 251Word boundaries are the same as those used by @kbd{M-b}. 252 253@item C-w 254Kill from the cursor to the previous whitespace. This is different than 255@kbd{M-@key{DEL}} because the word boundaries differ. 256 257@end table 258 259Here is how to @dfn{yank} the text back into the line. Yanking 260means to copy the most-recently-killed text from the kill buffer. 261 262@table @kbd 263@item C-y 264Yank the most recently killed text back into the buffer at the cursor. 265 266@item M-y 267Rotate the kill-ring, and yank the new top. You can only do this if 268the prior command is @kbd{C-y} or @kbd{M-y}. 269@end table 270 271@node Readline Arguments 272@subsection Readline Arguments 273 274You can pass numeric arguments to Readline commands. Sometimes the 275argument acts as a repeat count, other times it is the @i{sign} of the 276argument that is significant. If you pass a negative argument to a 277command which normally acts in a forward direction, that command will 278act in a backward direction. For example, to kill text back to the 279start of the line, you might type @samp{M-- C-k}. 280 281The general way to pass numeric arguments to a command is to type meta 282digits before the command. If the first `digit' typed is a minus 283sign (@samp{-}), then the sign of the argument will be negative. Once 284you have typed one meta digit to get the argument started, you can type 285the remainder of the digits, and then the command. For example, to give 286the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}, 287which will delete the next ten characters on the input line. 288 289@node Searching 290@subsection Searching for Commands in the History 291 292Readline provides commands for searching through the command history 293@ifset BashFeatures 294(@pxref{Bash History Facilities}) 295@end ifset 296for lines containing a specified string. 297There are two search modes: @dfn{incremental} and @dfn{non-incremental}. 298 299Incremental searches begin before the user has finished typing the 300search string. 301As each character of the search string is typed, Readline displays 302the next entry from the history matching the string typed so far. 303An incremental search requires only as many characters as needed to 304find the desired history entry. 305To search backward in the history for a particular string, type 306@kbd{C-r}. Typing @kbd{C-s} searches forward through the history. 307The characters present in the value of the @code{isearch-terminators} variable 308are used to terminate an incremental search. 309If that variable has not been assigned a value, the @key{ESC} and 310@kbd{C-J} characters will terminate an incremental search. 311@kbd{C-g} will abort an incremental search and restore the original line. 312When the search is terminated, the history entry containing the 313search string becomes the current line. 314 315To find other matching entries in the history list, type @kbd{C-r} or 316@kbd{C-s} as appropriate. 317This will search backward or forward in the history for the next 318entry matching the search string typed so far. 319Any other key sequence bound to a Readline command will terminate 320the search and execute that command. 321For instance, a @key{RET} will terminate the search and accept 322the line, thereby executing the command from the history list. 323A movement command will terminate the search, make the last line found 324the current line, and begin editing. 325 326Readline remembers the last incremental search string. If two 327@kbd{C-r}s are typed without any intervening characters defining a new 328search string, any remembered search string is used. 329 330Non-incremental searches read the entire search string before starting 331to search for matching history lines. The search string may be 332typed by the user or be part of the contents of the current line. 333 334@node Readline Init File 335@section Readline Init File 336@cindex initialization file, readline 337 338Although the Readline library comes with a set of Emacs-like 339keybindings installed by default, it is possible to use a different set 340of keybindings. 341Any user can customize programs that use Readline by putting 342commands in an @dfn{inputrc} file, conventionally in his home directory. 343The name of this 344@ifset BashFeatures 345file is taken from the value of the shell variable @env{INPUTRC}. If 346@end ifset 347@ifclear BashFeatures 348file is taken from the value of the environment variable @env{INPUTRC}. If 349@end ifclear 350that variable is unset, the default is @file{~/.inputrc}. If that 351file does not exist or cannot be read, the ultimate default is 352@file{/etc/inputrc}. 353@ifset BashFeatures 354The @w{@code{bind}} builtin command can also be used to set Readline 355keybindings and variables. 356@xref{Bash Builtins}. 357@end ifset 358 359When a program which uses the Readline library starts up, the 360init file is read, and the key bindings are set. 361 362In addition, the @code{C-x C-r} command re-reads this init file, thus 363incorporating any changes that you might have made to it. 364 365@menu 366* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 367 368* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 369 370* Sample Init File:: An example inputrc file. 371@end menu 372 373@node Readline Init File Syntax 374@subsection Readline Init File Syntax 375 376There are only a few basic constructs allowed in the 377Readline init file. Blank lines are ignored. 378Lines beginning with a @samp{#} are comments. 379Lines beginning with a @samp{$} indicate conditional 380constructs (@pxref{Conditional Init Constructs}). Other lines 381denote variable settings and key bindings. 382 383@table @asis 384@item Variable Settings 385You can modify the run-time behavior of Readline by 386altering the values of variables in Readline 387using the @code{set} command within the init file. 388The syntax is simple: 389 390@example 391set @var{variable} @var{value} 392@end example 393 394@noindent 395Here, for example, is how to 396change from the default Emacs-like key binding to use 397@code{vi} line editing commands: 398 399@example 400set editing-mode vi 401@end example 402 403Variable names and values, where appropriate, are recognized without regard 404to case. Unrecognized variable names are ignored. 405 406Boolean variables (those that can be set to on or off) are set to on if 407the value is null or empty, @var{on} (case-insensitive), or 1. Any other 408value results in the variable being set to off. 409 410@ifset BashFeatures 411The @w{@code{bind -V}} command lists the current Readline variable names 412and values. @xref{Bash Builtins}. 413@end ifset 414 415A great deal of run-time behavior is changeable with the following 416variables. 417 418@cindex variables, readline 419@table @code 420 421@item bell-style 422@vindex bell-style 423Controls what happens when Readline wants to ring the terminal bell. 424If set to @samp{none}, Readline never rings the bell. If set to 425@samp{visible}, Readline uses a visible bell if one is available. 426If set to @samp{audible} (the default), Readline attempts to ring 427the terminal's bell. 428 429@item bind-tty-special-chars 430@vindex bind-tty-special-chars 431If set to @samp{on} (the default), Readline attempts to bind the control 432characters treated specially by the kernel's terminal driver to their 433Readline equivalents. 434 435@item blink-matching-paren 436@vindex blink-matching-paren 437If set to @samp{on}, Readline attempts to briefly move the cursor to an 438opening parenthesis when a closing parenthesis is inserted. The default 439is @samp{off}. 440 441@item colored-completion-prefix 442@vindex colored-completion-prefix 443If set to @samp{on}, when listing completions, Readline displays the 444common prefix of the set of possible completions using a different color. 445The color definitions are taken from the value of the @env{LS_COLORS} 446environment variable. 447The default is @samp{off}. 448 449@item colored-stats 450@vindex colored-stats 451If set to @samp{on}, Readline displays possible completions using different 452colors to indicate their file type. 453The color definitions are taken from the value of the @env{LS_COLORS} 454environment variable. 455The default is @samp{off}. 456 457@item comment-begin 458@vindex comment-begin 459The string to insert at the beginning of the line when the 460@code{insert-comment} command is executed. The default value 461is @code{"#"}. 462 463@item completion-display-width 464@vindex completion-display-width 465The number of screen columns used to display possible matches 466when performing completion. 467The value is ignored if it is less than 0 or greater than the terminal 468screen width. 469A value of 0 will cause matches to be displayed one per line. 470The default value is -1. 471 472@item completion-ignore-case 473@vindex completion-ignore-case 474If set to @samp{on}, Readline performs filename matching and completion 475in a case-insensitive fashion. 476The default value is @samp{off}. 477 478@item completion-map-case 479@vindex completion-map-case 480If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline 481treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when 482performing case-insensitive filename matching and completion. 483The default value is @samp{off}. 484 485@item completion-prefix-display-length 486@vindex completion-prefix-display-length 487The length in characters of the common prefix of a list of possible 488completions that is displayed without modification. When set to a 489value greater than zero, common prefixes longer than this value are 490replaced with an ellipsis when displaying possible completions. 491 492@item completion-query-items 493@vindex completion-query-items 494The number of possible completions that determines when the user is 495asked whether the list of possibilities should be displayed. 496If the number of possible completions is greater than or equal to this value, 497Readline will ask whether or not the user wishes to view them; 498otherwise, they are simply listed. 499This variable must be set to an integer value greater than or equal to 0. 500A negative value means Readline should never ask. 501The default limit is @code{100}. 502 503@item convert-meta 504@vindex convert-meta 505If set to @samp{on}, Readline will convert characters with the 506eighth bit set to an @sc{ascii} key sequence by stripping the eighth 507bit and prefixing an @key{ESC} character, converting them to a 508meta-prefixed key sequence. The default value is @samp{on}, but 509will be set to @samp{off} if the locale is one that contains 510eight-bit characters. 511 512@item disable-completion 513@vindex disable-completion 514If set to @samp{On}, Readline will inhibit word completion. 515Completion characters will be inserted into the line as if they had 516been mapped to @code{self-insert}. The default is @samp{off}. 517 518@item echo-control-characters 519@vindex echo-control-characters 520When set to @samp{on}, on operating systems that indicate they support it, 521readline echoes a character corresponding to a signal generated from the 522keyboard. The default is @samp{on}. 523 524@item editing-mode 525@vindex editing-mode 526The @code{editing-mode} variable controls which default set of 527key bindings is used. By default, Readline starts up in Emacs editing 528mode, where the keystrokes are most similar to Emacs. This variable can be 529set to either @samp{emacs} or @samp{vi}. 530 531@item emacs-mode-string 532@vindex emacs-mode-string 533If the @var{show-mode-in-prompt} variable is enabled, 534this string is displayed immediately before the last line of the primary 535prompt when emacs editing mode is active. The value is expanded like a 536key binding, so the standard set of meta- and control prefixes and 537backslash escape sequences is available. 538Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of 539non-printing characters, which can be used to embed a terminal control 540sequence into the mode string. 541The default is @samp{@@}. 542 543@item enable-bracketed-paste 544@vindex enable-bracketed-paste 545When set to @samp{On}, Readline will configure the terminal in a way 546that will enable it to insert each paste into the editing buffer as a 547single string of characters, instead of treating each character as if 548it had been read from the keyboard. This can prevent pasted characters 549from being interpreted as editing commands. The default is @samp{On}. 550 551@item enable-keypad 552@vindex enable-keypad 553When set to @samp{on}, Readline will try to enable the application 554keypad when it is called. Some systems need this to enable the 555arrow keys. The default is @samp{off}. 556 557@item enable-meta-key 558When set to @samp{on}, Readline will try to enable any meta modifier 559key the terminal claims to support when it is called. On many terminals, 560the meta key is used to send eight-bit characters. 561The default is @samp{on}. 562 563@item expand-tilde 564@vindex expand-tilde 565If set to @samp{on}, tilde expansion is performed when Readline 566attempts word completion. The default is @samp{off}. 567 568@item history-preserve-point 569@vindex history-preserve-point 570If set to @samp{on}, the history code attempts to place the point (the 571current cursor position) at the 572same location on each history line retrieved with @code{previous-history} 573or @code{next-history}. The default is @samp{off}. 574 575@item history-size 576@vindex history-size 577Set the maximum number of history entries saved in the history list. 578If set to zero, any existing history entries are deleted and no new entries 579are saved. 580If set to a value less than zero, the number of history entries is not 581limited. 582By default, the number of history entries is not limited. 583If an attempt is made to set @var{history-size} to a non-numeric value, 584the maximum number of history entries will be set to 500. 585 586@item horizontal-scroll-mode 587@vindex horizontal-scroll-mode 588This variable can be set to either @samp{on} or @samp{off}. Setting it 589to @samp{on} means that the text of the lines being edited will scroll 590horizontally on a single screen line when they are longer than the width 591of the screen, instead of wrapping onto a new screen line. 592This variable is automatically set to @samp{on} for terminals of height 1. 593By default, this variable is set to @samp{off}. 594 595@item input-meta 596@vindex input-meta 597@vindex meta-flag 598If set to @samp{on}, Readline will enable eight-bit input (it 599will not clear the eighth bit in the characters it reads), 600regardless of what the terminal claims it can support. The 601default value is @samp{off}, but Readline will set it to @samp{on} if the 602locale contains eight-bit characters. 603The name @code{meta-flag} is a synonym for this variable. 604 605@item isearch-terminators 606@vindex isearch-terminators 607The string of characters that should terminate an incremental search without 608subsequently executing the character as a command (@pxref{Searching}). 609If this variable has not been given a value, the characters @key{ESC} and 610@kbd{C-J} will terminate an incremental search. 611 612@item keymap 613@vindex keymap 614Sets Readline's idea of the current keymap for key binding commands. 615Built-in @code{keymap} names are 616@code{emacs}, 617@code{emacs-standard}, 618@code{emacs-meta}, 619@code{emacs-ctlx}, 620@code{vi}, 621@code{vi-move}, 622@code{vi-command}, and 623@code{vi-insert}. 624@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a 625synonym); @code{emacs} is equivalent to @code{emacs-standard}. 626Applications may add additional names. 627The default value is @code{emacs}. 628The value of the @code{editing-mode} variable also affects the 629default keymap. 630 631@item keyseq-timeout 632Specifies the duration Readline will wait for a character when reading an 633ambiguous key sequence (one that can form a complete key sequence using 634the input read so far, or can take additional input to complete a longer 635key sequence). 636If no input is received within the timeout, Readline will use the shorter 637but complete key sequence. 638Readline uses this value to determine whether or not input is 639available on the current input source (@code{rl_instream} by default). 640The value is specified in milliseconds, so a value of 1000 means that 641Readline will wait one second for additional input. 642If this variable is set to a value less than or equal to zero, or to a 643non-numeric value, Readline will wait until another key is pressed to 644decide which key sequence to complete. 645The default value is @code{500}. 646 647@item mark-directories 648If set to @samp{on}, completed directory names have a slash 649appended. The default is @samp{on}. 650 651@item mark-modified-lines 652@vindex mark-modified-lines 653This variable, when set to @samp{on}, causes Readline to display an 654asterisk (@samp{*}) at the start of history lines which have been modified. 655This variable is @samp{off} by default. 656 657@item mark-symlinked-directories 658@vindex mark-symlinked-directories 659If set to @samp{on}, completed names which are symbolic links 660to directories have a slash appended (subject to the value of 661@code{mark-directories}). 662The default is @samp{off}. 663 664@item match-hidden-files 665@vindex match-hidden-files 666This variable, when set to @samp{on}, causes Readline to match files whose 667names begin with a @samp{.} (hidden files) when performing filename 668completion. 669If set to @samp{off}, the leading @samp{.} must be 670supplied by the user in the filename to be completed. 671This variable is @samp{on} by default. 672 673@item menu-complete-display-prefix 674@vindex menu-complete-display-prefix 675If set to @samp{on}, menu completion displays the common prefix of the 676list of possible completions (which may be empty) before cycling through 677the list. The default is @samp{off}. 678 679@item output-meta 680@vindex output-meta 681If set to @samp{on}, Readline will display characters with the 682eighth bit set directly rather than as a meta-prefixed escape 683sequence. 684The default is @samp{off}, but Readline will set it to @samp{on} if the 685locale contains eight-bit characters. 686 687@item page-completions 688@vindex page-completions 689If set to @samp{on}, Readline uses an internal @code{more}-like pager 690to display a screenful of possible completions at a time. 691This variable is @samp{on} by default. 692 693@item print-completions-horizontally 694If set to @samp{on}, Readline will display completions with matches 695sorted horizontally in alphabetical order, rather than down the screen. 696The default is @samp{off}. 697 698@item revert-all-at-newline 699@vindex revert-all-at-newline 700If set to @samp{on}, Readline will undo all changes to history lines 701before returning when @code{accept-line} is executed. By default, 702history lines may be modified and retain individual undo lists across 703calls to @code{readline}. The default is @samp{off}. 704 705@item show-all-if-ambiguous 706@vindex show-all-if-ambiguous 707This alters the default behavior of the completion functions. If 708set to @samp{on}, 709words which have more than one possible completion cause the 710matches to be listed immediately instead of ringing the bell. 711The default value is @samp{off}. 712 713@item show-all-if-unmodified 714@vindex show-all-if-unmodified 715This alters the default behavior of the completion functions in 716a fashion similar to @var{show-all-if-ambiguous}. 717If set to @samp{on}, 718words which have more than one possible completion without any 719possible partial completion (the possible completions don't share 720a common prefix) cause the matches to be listed immediately instead 721of ringing the bell. 722The default value is @samp{off}. 723 724@item show-mode-in-prompt 725@vindex show-mode-in-prompt 726If set to @samp{on}, add a string to the beginning of the prompt 727indicating the editing mode: emacs, vi command, or vi insertion. 728The mode strings are user-settable (e.g., @var{emacs-mode-string}). 729The default value is @samp{off}. 730 731@item skip-completed-text 732@vindex skip-completed-text 733If set to @samp{on}, this alters the default completion behavior when 734inserting a single match into the line. It's only active when 735performing completion in the middle of a word. If enabled, readline 736does not insert characters from the completion that match characters 737after point in the word being completed, so portions of the word 738following the cursor are not duplicated. 739For instance, if this is enabled, attempting completion when the cursor 740is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile} 741rather than @samp{Makefilefile}, assuming there is a single possible 742completion. 743The default value is @samp{off}. 744 745@item vi-cmd-mode-string 746@vindex vi-cmd-mode-string 747If the @var{show-mode-in-prompt} variable is enabled, 748this string is displayed immediately before the last line of the primary 749prompt when vi editing mode is active and in command mode. 750The value is expanded like a 751key binding, so the standard set of meta- and control prefixes and 752backslash escape sequences is available. 753Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of 754non-printing characters, which can be used to embed a terminal control 755sequence into the mode string. 756The default is @samp{(cmd)}. 757 758@item vi-ins-mode-string 759@vindex vi-ins-mode-string 760If the @var{show-mode-in-prompt} variable is enabled, 761this string is displayed immediately before the last line of the primary 762prompt when vi editing mode is active and in insertion mode. 763The value is expanded like a 764key binding, so the standard set of meta- and control prefixes and 765backslash escape sequences is available. 766Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of 767non-printing characters, which can be used to embed a terminal control 768sequence into the mode string. 769The default is @samp{(ins)}. 770 771@item visible-stats 772@vindex visible-stats 773If set to @samp{on}, a character denoting a file's type 774is appended to the filename when listing possible 775completions. The default is @samp{off}. 776 777@end table 778 779@item Key Bindings 780The syntax for controlling key bindings in the init file is 781simple. First you need to find the name of the command that you 782want to change. The following sections contain tables of the command 783name, the default keybinding, if any, and a short description of what 784the command does. 785 786Once you know the name of the command, simply place on a line 787in the init file the name of the key 788you wish to bind the command to, a colon, and then the name of the 789command. 790There can be no space between the key name and the colon -- that will be 791interpreted as part of the key name. 792The name of the key can be expressed in different ways, depending on 793what you find most comfortable. 794 795In addition to command names, readline allows keys to be bound 796to a string that is inserted when the key is pressed (a @var{macro}). 797 798@ifset BashFeatures 799The @w{@code{bind -p}} command displays Readline function names and 800bindings in a format that can put directly into an initialization file. 801@xref{Bash Builtins}. 802@end ifset 803 804@table @asis 805@item @w{@var{keyname}: @var{function-name} or @var{macro}} 806@var{keyname} is the name of a key spelled out in English. For example: 807@example 808Control-u: universal-argument 809Meta-Rubout: backward-kill-word 810Control-o: "> output" 811@end example 812 813In the example above, @kbd{C-u} is bound to the function 814@code{universal-argument}, 815@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and 816@kbd{C-o} is bound to run the macro 817expressed on the right hand side (that is, to insert the text 818@samp{> output} into the line). 819 820A number of symbolic character names are recognized while 821processing this key binding syntax: 822@var{DEL}, 823@var{ESC}, 824@var{ESCAPE}, 825@var{LFD}, 826@var{NEWLINE}, 827@var{RET}, 828@var{RETURN}, 829@var{RUBOUT}, 830@var{SPACE}, 831@var{SPC}, 832and 833@var{TAB}. 834 835@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} 836@var{keyseq} differs from @var{keyname} above in that strings 837denoting an entire key sequence can be specified, by placing 838the key sequence in double quotes. Some @sc{gnu} Emacs style key 839escapes can be used, as in the following example, but the 840special character names are not recognized. 841 842@example 843"\C-u": universal-argument 844"\C-x\C-r": re-read-init-file 845"\e[11~": "Function Key 1" 846@end example 847 848In the above example, @kbd{C-u} is again bound to the function 849@code{universal-argument} (just as it was in the first example), 850@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file}, 851and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert 852the text @samp{Function Key 1}. 853 854@end table 855 856The following @sc{gnu} Emacs style escape sequences are available when 857specifying key sequences: 858 859@table @code 860@item @kbd{\C-} 861control prefix 862@item @kbd{\M-} 863meta prefix 864@item @kbd{\e} 865an escape character 866@item @kbd{\\} 867backslash 868@item @kbd{\"} 869@key{"}, a double quotation mark 870@item @kbd{\'} 871@key{'}, a single quote or apostrophe 872@end table 873 874In addition to the @sc{gnu} Emacs style escape sequences, a second 875set of backslash escapes is available: 876 877@table @code 878@item \a 879alert (bell) 880@item \b 881backspace 882@item \d 883delete 884@item \f 885form feed 886@item \n 887newline 888@item \r 889carriage return 890@item \t 891horizontal tab 892@item \v 893vertical tab 894@item \@var{nnn} 895the eight-bit character whose value is the octal value @var{nnn} 896(one to three digits) 897@item \x@var{HH} 898the eight-bit character whose value is the hexadecimal value @var{HH} 899(one or two hex digits) 900@end table 901 902When entering the text of a macro, single or double quotes must 903be used to indicate a macro definition. 904Unquoted text is assumed to be a function name. 905In the macro body, the backslash escapes described above are expanded. 906Backslash will quote any other character in the macro text, 907including @samp{"} and @samp{'}. 908For example, the following binding will make @samp{@kbd{C-x} \} 909insert a single @samp{\} into the line: 910@example 911"\C-x\\": "\\" 912@end example 913 914@end table 915 916@node Conditional Init Constructs 917@subsection Conditional Init Constructs 918 919Readline implements a facility similar in spirit to the conditional 920compilation features of the C preprocessor which allows key 921bindings and variable settings to be performed as the result 922of tests. There are four parser directives used. 923 924@table @code 925@item $if 926The @code{$if} construct allows bindings to be made based on the 927editing mode, the terminal being used, or the application using 928Readline. The text of the test, after any comparison operator, 929extends to the end of the line; 930unless otherwise noted, no characters are required to isolate it. 931 932@table @code 933@item mode 934The @code{mode=} form of the @code{$if} directive is used to test 935whether Readline is in @code{emacs} or @code{vi} mode. 936This may be used in conjunction 937with the @samp{set keymap} command, for instance, to set bindings in 938the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if 939Readline is starting out in @code{emacs} mode. 940 941@item term 942The @code{term=} form may be used to include terminal-specific 943key bindings, perhaps to bind the key sequences output by the 944terminal's function keys. The word on the right side of the 945@samp{=} is tested against both the full name of the terminal and 946the portion of the terminal name before the first @samp{-}. This 947allows @code{sun} to match both @code{sun} and @code{sun-cmd}, 948for instance. 949 950@item version 951The @code{version} test may be used to perform comparisons against 952specific Readline versions. 953The @code{version} expands to the current Readline version. 954The set of comparison operators includes 955@samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<}, 956and @samp{>}. 957The version number supplied on the right side of the operator consists 958of a major version number, an optional decimal point, and an optional 959minor version (e.g., @samp{7.1}). If the minor version is omitted, it 960is assumed to be @samp{0}. 961The operator may be separated from the string @code{version} and 962from the version number argument by whitespace. 963The following example sets a variable if the Readline version being used 964is 7.0 or newer: 965@example 966$if version >= 7.0 967set show-mode-in-prompt on 968$endif 969@end example 970 971@item application 972The @var{application} construct is used to include 973application-specific settings. Each program using the Readline 974library sets the @var{application name}, and you can test for 975a particular value. 976This could be used to bind key sequences to functions useful for 977a specific program. For instance, the following command adds a 978key sequence that quotes the current or previous word in Bash: 979@example 980$if Bash 981# Quote the current or previous word 982"\C-xq": "\eb\"\ef\"" 983$endif 984@end example 985 986@item variable 987The @var{variable} construct provides simple equality tests for Readline 988variables and values. 989The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}. 990The variable name must be separated from the comparison operator by 991whitespace; the operator may be separated from the value on the right hand 992side by whitespace. 993Both string and boolean variables may be tested. Boolean variables must be 994tested against the values @var{on} and @var{off}. 995The following example is equivalent to the @code{mode=emacs} test described 996above: 997@example 998$if editing-mode == emacs 999set show-mode-in-prompt on 1000$endif 1001@end example 1002@end table 1003 1004@item $endif 1005This command, as seen in the previous example, terminates an 1006@code{$if} command. 1007 1008@item $else 1009Commands in this branch of the @code{$if} directive are executed if 1010the test fails. 1011 1012@item $include 1013This directive takes a single filename as an argument and reads commands 1014and bindings from that file. 1015For example, the following directive reads from @file{/etc/inputrc}: 1016@example 1017$include /etc/inputrc 1018@end example 1019@end table 1020 1021@node Sample Init File 1022@subsection Sample Init File 1023 1024Here is an example of an @var{inputrc} file. This illustrates key 1025binding, variable assignment, and conditional syntax. 1026 1027@example 1028@page 1029# This file controls the behaviour of line input editing for 1030# programs that use the GNU Readline library. Existing 1031# programs include FTP, Bash, and GDB. 1032# 1033# You can re-read the inputrc file with C-x C-r. 1034# Lines beginning with '#' are comments. 1035# 1036# First, include any system-wide bindings and variable 1037# assignments from /etc/Inputrc 1038$include /etc/Inputrc 1039 1040# 1041# Set various bindings for emacs mode. 1042 1043set editing-mode emacs 1044 1045$if mode=emacs 1046 1047Meta-Control-h: backward-kill-word Text after the function name is ignored 1048 1049# 1050# Arrow keys in keypad mode 1051# 1052#"\M-OD": backward-char 1053#"\M-OC": forward-char 1054#"\M-OA": previous-history 1055#"\M-OB": next-history 1056# 1057# Arrow keys in ANSI mode 1058# 1059"\M-[D": backward-char 1060"\M-[C": forward-char 1061"\M-[A": previous-history 1062"\M-[B": next-history 1063# 1064# Arrow keys in 8 bit keypad mode 1065# 1066#"\M-\C-OD": backward-char 1067#"\M-\C-OC": forward-char 1068#"\M-\C-OA": previous-history 1069#"\M-\C-OB": next-history 1070# 1071# Arrow keys in 8 bit ANSI mode 1072# 1073#"\M-\C-[D": backward-char 1074#"\M-\C-[C": forward-char 1075#"\M-\C-[A": previous-history 1076#"\M-\C-[B": next-history 1077 1078C-q: quoted-insert 1079 1080$endif 1081 1082# An old-style binding. This happens to be the default. 1083TAB: complete 1084 1085# Macros that are convenient for shell interaction 1086$if Bash 1087# edit the path 1088"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f" 1089# prepare to type a quoted word -- 1090# insert open and close double quotes 1091# and move to just after the open quote 1092"\C-x\"": "\"\"\C-b" 1093# insert a backslash (testing backslash escapes 1094# in sequences and macros) 1095"\C-x\\": "\\" 1096# Quote the current or previous word 1097"\C-xq": "\eb\"\ef\"" 1098# Add a binding to refresh the line, which is unbound 1099"\C-xr": redraw-current-line 1100# Edit variable on current line. 1101"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 1102$endif 1103 1104# use a visible bell if one is available 1105set bell-style visible 1106 1107# don't strip characters to 7 bits when reading 1108set input-meta on 1109 1110# allow iso-latin1 characters to be inserted rather 1111# than converted to prefix-meta sequences 1112set convert-meta off 1113 1114# display characters with the eighth bit set directly 1115# rather than as meta-prefixed characters 1116set output-meta on 1117 1118# if there are 150 or more possible completions for a word, 1119# ask whether or not the user wants to see all of them 1120set completion-query-items 150 1121 1122# For FTP 1123$if Ftp 1124"\C-xg": "get \M-?" 1125"\C-xt": "put \M-?" 1126"\M-.": yank-last-arg 1127$endif 1128@end example 1129 1130@node Bindable Readline Commands 1131@section Bindable Readline Commands 1132 1133@menu 1134* Commands For Moving:: Moving about the line. 1135* Commands For History:: Getting at previous lines. 1136* Commands For Text:: Commands for changing text. 1137* Commands For Killing:: Commands for killing and yanking. 1138* Numeric Arguments:: Specifying numeric arguments, repeat counts. 1139* Commands For Completion:: Getting Readline to do the typing for you. 1140* Keyboard Macros:: Saving and re-executing typed characters 1141* Miscellaneous Commands:: Other miscellaneous commands. 1142@end menu 1143 1144This section describes Readline commands that may be bound to key 1145sequences. 1146@ifset BashFeatures 1147You can list your key bindings by executing 1148@w{@code{bind -P}} or, for a more terse format, suitable for an 1149@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.) 1150@end ifset 1151Command names without an accompanying key sequence are unbound by default. 1152 1153In the following descriptions, @dfn{point} refers to the current cursor 1154position, and @dfn{mark} refers to a cursor position saved by the 1155@code{set-mark} command. 1156The text between the point and mark is referred to as the @dfn{region}. 1157 1158@node Commands For Moving 1159@subsection Commands For Moving 1160@ftable @code 1161@item beginning-of-line (C-a) 1162Move to the start of the current line. 1163 1164@item end-of-line (C-e) 1165Move to the end of the line. 1166 1167@item forward-char (C-f) 1168Move forward a character. 1169 1170@item backward-char (C-b) 1171Move back a character. 1172 1173@item forward-word (M-f) 1174Move forward to the end of the next word. 1175Words are composed of letters and digits. 1176 1177@item backward-word (M-b) 1178Move back to the start of the current or previous word. 1179Words are composed of letters and digits. 1180 1181@ifset BashFeatures 1182@item shell-forward-word (M-C-f) 1183Move forward to the end of the next word. 1184Words are delimited by non-quoted shell metacharacters. 1185 1186@item shell-backward-word (M-C-b) 1187Move back to the start of the current or previous word. 1188Words are delimited by non-quoted shell metacharacters. 1189@end ifset 1190 1191@item previous-screen-line () 1192Attempt to move point to the same physical screen column on the previous 1193physical screen line. This will not have the desired effect if the current 1194Readline line does not take up more than one physical line or if point is not 1195greater than the length of the prompt plus the screen width. 1196 1197@item next-screen-line () 1198Attempt to move point to the same physical screen column on the next 1199physical screen line. This will not have the desired effect if the current 1200Readline line does not take up more than one physical line or if the length 1201of the current Readline line is not greater than the length of the prompt 1202plus the screen width. 1203 1204@item clear-display (M-C-l) 1205Clear the screen and, if possible, the terminal's scrollback buffer, 1206then redraw the current line, 1207leaving the current line at the top of the screen. 1208 1209@item clear-screen (C-l) 1210Clear the screen, 1211then redraw the current line, 1212leaving the current line at the top of the screen. 1213 1214@item redraw-current-line () 1215Refresh the current line. By default, this is unbound. 1216 1217@end ftable 1218 1219@node Commands For History 1220@subsection Commands For Manipulating The History 1221 1222@ftable @code 1223@item accept-line (Newline or Return) 1224@ifset BashFeatures 1225Accept the line regardless of where the cursor is. 1226If this line is 1227non-empty, add it to the history list according to the setting of 1228the @env{HISTCONTROL} and @env{HISTIGNORE} variables. 1229If this line is a modified history line, then restore the history line 1230to its original state. 1231@end ifset 1232@ifclear BashFeatures 1233Accept the line regardless of where the cursor is. 1234If this line is 1235non-empty, it may be added to the history list for future recall with 1236@code{add_history()}. 1237If this line is a modified history line, the history line is restored 1238to its original state. 1239@end ifclear 1240 1241@item previous-history (C-p) 1242Move `back' through the history list, fetching the previous command. 1243 1244@item next-history (C-n) 1245Move `forward' through the history list, fetching the next command. 1246 1247@item beginning-of-history (M-<) 1248Move to the first line in the history. 1249 1250@item end-of-history (M->) 1251Move to the end of the input history, i.e., the line currently 1252being entered. 1253 1254@item reverse-search-history (C-r) 1255Search backward starting at the current line and moving `up' through 1256the history as necessary. This is an incremental search. 1257This command sets the region to the matched text and activates the mark. 1258 1259@item forward-search-history (C-s) 1260Search forward starting at the current line and moving `down' through 1261the history as necessary. This is an incremental search. 1262This command sets the region to the matched text and activates the mark. 1263 1264@item non-incremental-reverse-search-history (M-p) 1265Search backward starting at the current line and moving `up' 1266through the history as necessary using a non-incremental search 1267for a string supplied by the user. 1268The search string may match anywhere in a history line. 1269 1270@item non-incremental-forward-search-history (M-n) 1271Search forward starting at the current line and moving `down' 1272through the history as necessary using a non-incremental search 1273for a string supplied by the user. 1274The search string may match anywhere in a history line. 1275 1276@item history-search-forward () 1277Search forward through the history for the string of characters 1278between the start of the current line and the point. 1279The search string must match at the beginning of a history line. 1280This is a non-incremental search. 1281By default, this command is unbound. 1282 1283@item history-search-backward () 1284Search backward through the history for the string of characters 1285between the start of the current line and the point. 1286The search string must match at the beginning of a history line. 1287This is a non-incremental search. 1288By default, this command is unbound. 1289 1290@item history-substring-search-forward () 1291Search forward through the history for the string of characters 1292between the start of the current line and the point. 1293The search string may match anywhere in a history line. 1294This is a non-incremental search. 1295By default, this command is unbound. 1296 1297@item history-substring-search-backward () 1298Search backward through the history for the string of characters 1299between the start of the current line and the point. 1300The search string may match anywhere in a history line. 1301This is a non-incremental search. 1302By default, this command is unbound. 1303 1304@item yank-nth-arg (M-C-y) 1305Insert the first argument to the previous command (usually 1306the second word on the previous line) at point. 1307With an argument @var{n}, 1308insert the @var{n}th word from the previous command (the words 1309in the previous command begin with word 0). A negative argument 1310inserts the @var{n}th word from the end of the previous command. 1311Once the argument @var{n} is computed, the argument is extracted 1312as if the @samp{!@var{n}} history expansion had been specified. 1313 1314@item yank-last-arg (M-. or M-_) 1315Insert last argument to the previous command (the last word of the 1316previous history entry). 1317With a numeric argument, behave exactly like @code{yank-nth-arg}. 1318Successive calls to @code{yank-last-arg} move back through the history 1319list, inserting the last word (or the word specified by the argument to 1320the first call) of each line in turn. 1321Any numeric argument supplied to these successive calls determines 1322the direction to move through the history. A negative argument switches 1323the direction through the history (back or forward). 1324The history expansion facilities are used to extract the last argument, 1325as if the @samp{!$} history expansion had been specified. 1326 1327@item operate-and-get-next (C-o) 1328Accept the current line for return to the calling application as if a 1329newline had been entered, 1330and fetch the next line relative to the current line from the history 1331for editing. 1332A numeric argument, if supplied, specifies the history entry to use instead 1333of the current line. 1334 1335@end ftable 1336 1337@node Commands For Text 1338@subsection Commands For Changing Text 1339 1340@ftable @code 1341 1342@item @i{end-of-file} (usually C-d) 1343The character indicating end-of-file as set, for example, by 1344@code{stty}. If this character is read when there are no characters 1345on the line, and point is at the beginning of the line, Readline 1346interprets it as the end of input and returns @sc{eof}. 1347 1348@item delete-char (C-d) 1349Delete the character at point. If this function is bound to the 1350same character as the tty @sc{eof} character, as @kbd{C-d} 1351commonly is, see above for the effects. 1352 1353@item backward-delete-char (Rubout) 1354Delete the character behind the cursor. A numeric argument means 1355to kill the characters instead of deleting them. 1356 1357@item forward-backward-delete-char () 1358Delete the character under the cursor, unless the cursor is at the 1359end of the line, in which case the character behind the cursor is 1360deleted. By default, this is not bound to a key. 1361 1362@item quoted-insert (C-q or C-v) 1363Add the next character typed to the line verbatim. This is 1364how to insert key sequences like @kbd{C-q}, for example. 1365 1366@ifclear BashFeatures 1367@item tab-insert (M-@key{TAB}) 1368Insert a tab character. 1369@end ifclear 1370 1371@item self-insert (a, b, A, 1, !, @dots{}) 1372Insert yourself. 1373 1374@item bracketed-paste-begin () 1375This function is intended to be bound to the "bracketed paste" escape 1376sequence sent by some terminals, and such a binding is assigned by default. 1377It allows Readline to insert the pasted text as a single unit without treating 1378each character as if it had been read from the keyboard. The characters 1379are inserted as if each one was bound to @code{self-insert} instead of 1380executing any editing commands. 1381 1382Bracketed paste sets the region (the characters between point and the mark) 1383to the inserted text. It uses the concept of an @emph{active mark}: when the 1384mark is active, Readline redisplay uses the terminal's standout mode to 1385denote the region. 1386 1387@item transpose-chars (C-t) 1388Drag the character before the cursor forward over 1389the character at the cursor, moving the 1390cursor forward as well. If the insertion point 1391is at the end of the line, then this 1392transposes the last two characters of the line. 1393Negative arguments have no effect. 1394 1395@item transpose-words (M-t) 1396Drag the word before point past the word after point, 1397moving point past that word as well. 1398If the insertion point is at the end of the line, this transposes 1399the last two words on the line. 1400 1401@item upcase-word (M-u) 1402Uppercase the current (or following) word. With a negative argument, 1403uppercase the previous word, but do not move the cursor. 1404 1405@item downcase-word (M-l) 1406Lowercase the current (or following) word. With a negative argument, 1407lowercase the previous word, but do not move the cursor. 1408 1409@item capitalize-word (M-c) 1410Capitalize the current (or following) word. With a negative argument, 1411capitalize the previous word, but do not move the cursor. 1412 1413@item overwrite-mode () 1414Toggle overwrite mode. With an explicit positive numeric argument, 1415switches to overwrite mode. With an explicit non-positive numeric 1416argument, switches to insert mode. This command affects only 1417@code{emacs} mode; @code{vi} mode does overwrite differently. 1418Each call to @code{readline()} starts in insert mode. 1419 1420In overwrite mode, characters bound to @code{self-insert} replace 1421the text at point rather than pushing the text to the right. 1422Characters bound to @code{backward-delete-char} replace the character 1423before point with a space. 1424 1425By default, this command is unbound. 1426 1427@end ftable 1428 1429@node Commands For Killing 1430@subsection Killing And Yanking 1431 1432@ftable @code 1433 1434@item kill-line (C-k) 1435Kill the text from point to the end of the line. 1436With a negative numeric argument, kill backward from the cursor to the 1437beginning of the current line. 1438 1439@item backward-kill-line (C-x Rubout) 1440Kill backward from the cursor to the beginning of the current line. 1441With a negative numeric argument, kill forward from the cursor to the 1442end of the current line. 1443 1444@item unix-line-discard (C-u) 1445Kill backward from the cursor to the beginning of the current line. 1446 1447@item kill-whole-line () 1448Kill all characters on the current line, no matter where point is. 1449By default, this is unbound. 1450 1451@item kill-word (M-d) 1452Kill from point to the end of the current word, or if between 1453words, to the end of the next word. 1454Word boundaries are the same as @code{forward-word}. 1455 1456@item backward-kill-word (M-@key{DEL}) 1457Kill the word behind point. 1458Word boundaries are the same as @code{backward-word}. 1459 1460@ifset BashFeatures 1461@item shell-kill-word (M-C-d) 1462Kill from point to the end of the current word, or if between 1463words, to the end of the next word. 1464Word boundaries are the same as @code{shell-forward-word}. 1465 1466@item shell-backward-kill-word () 1467Kill the word behind point. 1468Word boundaries are the same as @code{shell-backward-word}. 1469@end ifset 1470 1471@item shell-transpose-words (M-C-t) 1472Drag the word before point past the word after point, 1473moving point past that word as well. 1474If the insertion point is at the end of the line, this transposes 1475the last two words on the line. 1476Word boundaries are the same as @code{shell-forward-word} and 1477@code{shell-backward-word}. 1478 1479@item unix-word-rubout (C-w) 1480Kill the word behind point, using white space as a word boundary. 1481The killed text is saved on the kill-ring. 1482 1483@item unix-filename-rubout () 1484Kill the word behind point, using white space and the slash character 1485as the word boundaries. 1486The killed text is saved on the kill-ring. 1487 1488@item delete-horizontal-space () 1489Delete all spaces and tabs around point. By default, this is unbound. 1490 1491@item kill-region () 1492Kill the text in the current region. 1493By default, this command is unbound. 1494 1495@item copy-region-as-kill () 1496Copy the text in the region to the kill buffer, so it can be yanked 1497right away. By default, this command is unbound. 1498 1499@item copy-backward-word () 1500Copy the word before point to the kill buffer. 1501The word boundaries are the same as @code{backward-word}. 1502By default, this command is unbound. 1503 1504@item copy-forward-word () 1505Copy the word following point to the kill buffer. 1506The word boundaries are the same as @code{forward-word}. 1507By default, this command is unbound. 1508 1509@item yank (C-y) 1510Yank the top of the kill ring into the buffer at point. 1511 1512@item yank-pop (M-y) 1513Rotate the kill-ring, and yank the new top. You can only do this if 1514the prior command is @code{yank} or @code{yank-pop}. 1515@end ftable 1516 1517@node Numeric Arguments 1518@subsection Specifying Numeric Arguments 1519@ftable @code 1520 1521@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--}) 1522Add this digit to the argument already accumulating, or start a new 1523argument. @kbd{M--} starts a negative argument. 1524 1525@item universal-argument () 1526This is another way to specify an argument. 1527If this command is followed by one or more digits, optionally with a 1528leading minus sign, those digits define the argument. 1529If the command is followed by digits, executing @code{universal-argument} 1530again ends the numeric argument, but is otherwise ignored. 1531As a special case, if this command is immediately followed by a 1532character that is neither a digit nor minus sign, the argument count 1533for the next command is multiplied by four. 1534The argument count is initially one, so executing this function the 1535first time makes the argument count four, a second time makes the 1536argument count sixteen, and so on. 1537By default, this is not bound to a key. 1538@end ftable 1539 1540@node Commands For Completion 1541@subsection Letting Readline Type For You 1542 1543@ftable @code 1544@item complete (@key{TAB}) 1545Attempt to perform completion on the text before point. 1546The actual completion performed is application-specific. 1547@ifset BashFeatures 1548Bash attempts completion treating the text as a variable (if the 1549text begins with @samp{$}), username (if the text begins with 1550@samp{~}), hostname (if the text begins with @samp{@@}), or 1551command (including aliases and functions) in turn. If none 1552of these produces a match, filename completion is attempted. 1553@end ifset 1554@ifclear BashFeatures 1555The default is filename completion. 1556@end ifclear 1557 1558@item possible-completions (M-?) 1559List the possible completions of the text before point. 1560When displaying completions, Readline sets the number of columns used 1561for display to the value of @code{completion-display-width}, the value of 1562the environment variable @env{COLUMNS}, or the screen width, in that order. 1563 1564@item insert-completions (M-*) 1565Insert all completions of the text before point that would have 1566been generated by @code{possible-completions}. 1567 1568@item menu-complete () 1569Similar to @code{complete}, but replaces the word to be completed 1570with a single match from the list of possible completions. 1571Repeated execution of @code{menu-complete} steps through the list 1572of possible completions, inserting each match in turn. 1573At the end of the list of completions, the bell is rung 1574(subject to the setting of @code{bell-style}) 1575and the original text is restored. 1576An argument of @var{n} moves @var{n} positions forward in the list 1577of matches; a negative argument may be used to move backward 1578through the list. 1579This command is intended to be bound to @key{TAB}, but is unbound 1580by default. 1581 1582@item menu-complete-backward () 1583Identical to @code{menu-complete}, but moves backward through the list 1584of possible completions, as if @code{menu-complete} had been given a 1585negative argument. 1586 1587@item delete-char-or-list () 1588Deletes the character under the cursor if not at the beginning or 1589end of the line (like @code{delete-char}). 1590If at the end of the line, behaves identically to 1591@code{possible-completions}. 1592This command is unbound by default. 1593 1594@ifset BashFeatures 1595@item complete-filename (M-/) 1596Attempt filename completion on the text before point. 1597 1598@item possible-filename-completions (C-x /) 1599List the possible completions of the text before point, 1600treating it as a filename. 1601 1602@item complete-username (M-~) 1603Attempt completion on the text before point, treating 1604it as a username. 1605 1606@item possible-username-completions (C-x ~) 1607List the possible completions of the text before point, 1608treating it as a username. 1609 1610@item complete-variable (M-$) 1611Attempt completion on the text before point, treating 1612it as a shell variable. 1613 1614@item possible-variable-completions (C-x $) 1615List the possible completions of the text before point, 1616treating it as a shell variable. 1617 1618@item complete-hostname (M-@@) 1619Attempt completion on the text before point, treating 1620it as a hostname. 1621 1622@item possible-hostname-completions (C-x @@) 1623List the possible completions of the text before point, 1624treating it as a hostname. 1625 1626@item complete-command (M-!) 1627Attempt completion on the text before point, treating 1628it as a command name. Command completion attempts to 1629match the text against aliases, reserved words, shell 1630functions, shell builtins, and finally executable filenames, 1631in that order. 1632 1633@item possible-command-completions (C-x !) 1634List the possible completions of the text before point, 1635treating it as a command name. 1636 1637@item dynamic-complete-history (M-@key{TAB}) 1638Attempt completion on the text before point, comparing 1639the text against lines from the history list for possible 1640completion matches. 1641 1642@item dabbrev-expand () 1643Attempt menu completion on the text before point, comparing 1644the text against lines from the history list for possible 1645completion matches. 1646 1647@item complete-into-braces (M-@{) 1648Perform filename completion and insert the list of possible completions 1649enclosed within braces so the list is available to the shell 1650(@pxref{Brace Expansion}). 1651 1652@end ifset 1653@end ftable 1654 1655@node Keyboard Macros 1656@subsection Keyboard Macros 1657@ftable @code 1658 1659@item start-kbd-macro (C-x () 1660Begin saving the characters typed into the current keyboard macro. 1661 1662@item end-kbd-macro (C-x )) 1663Stop saving the characters typed into the current keyboard macro 1664and save the definition. 1665 1666@item call-last-kbd-macro (C-x e) 1667Re-execute the last keyboard macro defined, by making the characters 1668in the macro appear as if typed at the keyboard. 1669 1670@item print-last-kbd-macro () 1671Print the last keboard macro defined in a format suitable for the 1672@var{inputrc} file. 1673 1674@end ftable 1675 1676@node Miscellaneous Commands 1677@subsection Some Miscellaneous Commands 1678@ftable @code 1679 1680@item re-read-init-file (C-x C-r) 1681Read in the contents of the @var{inputrc} file, and incorporate 1682any bindings or variable assignments found there. 1683 1684@item abort (C-g) 1685Abort the current editing command and 1686ring the terminal's bell (subject to the setting of 1687@code{bell-style}). 1688 1689@item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{}) 1690If the metafied character @var{x} is upper case, run the command 1691that is bound to the corresponding metafied lower case character. 1692The behavior is undefined if @var{x} is already lower case. 1693 1694@item prefix-meta (@key{ESC}) 1695Metafy the next character typed. This is for keyboards 1696without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing 1697@kbd{M-f}. 1698 1699@item undo (C-_ or C-x C-u) 1700Incremental undo, separately remembered for each line. 1701 1702@item revert-line (M-r) 1703Undo all changes made to this line. This is like executing the @code{undo} 1704command enough times to get back to the beginning. 1705 1706@ifset BashFeatures 1707@item tilde-expand (M-&) 1708@end ifset 1709@ifclear BashFeatures 1710@item tilde-expand (M-~) 1711@end ifclear 1712Perform tilde expansion on the current word. 1713 1714@item set-mark (C-@@) 1715Set the mark to the point. If a 1716numeric argument is supplied, the mark is set to that position. 1717 1718@item exchange-point-and-mark (C-x C-x) 1719Swap the point with the mark. The current cursor position is set to 1720the saved position, and the old cursor position is saved as the mark. 1721 1722@item character-search (C-]) 1723A character is read and point is moved to the next occurrence of that 1724character. A negative count searches for previous occurrences. 1725 1726@item character-search-backward (M-C-]) 1727A character is read and point is moved to the previous occurrence 1728of that character. A negative count searches for subsequent 1729occurrences. 1730 1731@item skip-csi-sequence () 1732Read enough characters to consume a multi-key sequence such as those 1733defined for keys like Home and End. Such sequences begin with a 1734Control Sequence Indicator (CSI), usually ESC-[. If this sequence is 1735bound to "\e[", keys producing such sequences will have no effect 1736unless explicitly bound to a readline command, instead of inserting 1737stray characters into the editing buffer. This is unbound by default, 1738but usually bound to ESC-[. 1739 1740@item insert-comment (M-#) 1741Without a numeric argument, the value of the @code{comment-begin} 1742variable is inserted at the beginning of the current line. 1743If a numeric argument is supplied, this command acts as a toggle: if 1744the characters at the beginning of the line do not match the value 1745of @code{comment-begin}, the value is inserted, otherwise 1746the characters in @code{comment-begin} are deleted from the beginning of 1747the line. 1748In either case, the line is accepted as if a newline had been typed. 1749@ifset BashFeatures 1750The default value of @code{comment-begin} causes this command 1751to make the current line a shell comment. 1752If a numeric argument causes the comment character to be removed, the line 1753will be executed by the shell. 1754@end ifset 1755 1756@item dump-functions () 1757Print all of the functions and their key bindings to the 1758Readline output stream. If a numeric argument is supplied, 1759the output is formatted in such a way that it can be made part 1760of an @var{inputrc} file. This command is unbound by default. 1761 1762@item dump-variables () 1763Print all of the settable variables and their values to the 1764Readline output stream. If a numeric argument is supplied, 1765the output is formatted in such a way that it can be made part 1766of an @var{inputrc} file. This command is unbound by default. 1767 1768@item dump-macros () 1769Print all of the Readline key sequences bound to macros and the 1770strings they output. If a numeric argument is supplied, 1771the output is formatted in such a way that it can be made part 1772of an @var{inputrc} file. This command is unbound by default. 1773 1774@ifset BashFeatures 1775@item glob-complete-word (M-g) 1776The word before point is treated as a pattern for pathname expansion, 1777with an asterisk implicitly appended. This pattern is used to 1778generate a list of matching file names for possible completions. 1779 1780@item glob-expand-word (C-x *) 1781The word before point is treated as a pattern for pathname expansion, 1782and the list of matching file names is inserted, replacing the word. 1783If a numeric argument is supplied, a @samp{*} is appended before 1784pathname expansion. 1785 1786@item glob-list-expansions (C-x g) 1787The list of expansions that would have been generated by 1788@code{glob-expand-word} is displayed, and the line is redrawn. 1789If a numeric argument is supplied, a @samp{*} is appended before 1790pathname expansion. 1791 1792@item display-shell-version (C-x C-v) 1793Display version information about the current instance of Bash. 1794 1795@item shell-expand-line (M-C-e) 1796Expand the line as the shell does. 1797This performs alias and history expansion as well as all of the shell 1798word expansions (@pxref{Shell Expansions}). 1799 1800@item history-expand-line (M-^) 1801Perform history expansion on the current line. 1802 1803@item magic-space () 1804Perform history expansion on the current line and insert a space 1805(@pxref{History Interaction}). 1806 1807@item alias-expand-line () 1808Perform alias expansion on the current line (@pxref{Aliases}). 1809 1810@item history-and-alias-expand-line () 1811Perform history and alias expansion on the current line. 1812 1813@item insert-last-argument (M-. or M-_) 1814A synonym for @code{yank-last-arg}. 1815 1816@item edit-and-execute-command (C-x C-e) 1817Invoke an editor on the current command line, and execute the result as shell 1818commands. 1819Bash attempts to invoke 1820@code{$VISUAL}, @code{$EDITOR}, and @code{emacs} 1821as the editor, in that order. 1822 1823@end ifset 1824 1825@ifclear BashFeatures 1826@item emacs-editing-mode (C-e) 1827When in @code{vi} command mode, this causes a switch to @code{emacs} 1828editing mode. 1829 1830@item vi-editing-mode (M-C-j) 1831When in @code{emacs} editing mode, this causes a switch to @code{vi} 1832editing mode. 1833 1834@end ifclear 1835 1836@end ftable 1837 1838@node Readline vi Mode 1839@section Readline vi Mode 1840 1841While the Readline library does not have a full set of @code{vi} 1842editing functions, it does contain enough to allow simple editing 1843of the line. The Readline @code{vi} mode behaves as specified in 1844the @sc{posix} standard. 1845 1846@ifset BashFeatures 1847In order to switch interactively between @code{emacs} and @code{vi} 1848editing modes, use the @samp{set -o emacs} and @samp{set -o vi} 1849commands (@pxref{The Set Builtin}). 1850@end ifset 1851@ifclear BashFeatures 1852In order to switch interactively between @code{emacs} and @code{vi} 1853editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode 1854when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode). 1855@end ifclear 1856The Readline default is @code{emacs} mode. 1857 1858When you enter a line in @code{vi} mode, you are already placed in 1859`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC} 1860switches you into `command' mode, where you can edit the text of the 1861line with the standard @code{vi} movement keys, move to previous 1862history lines with @samp{k} and subsequent lines with @samp{j}, and 1863so forth. 1864 1865@ifset BashFeatures 1866@node Programmable Completion 1867@section Programmable Completion 1868@cindex programmable completion 1869 1870When word completion is attempted for an argument to a command for 1871which a completion specification (a @var{compspec}) has been defined 1872using the @code{complete} builtin (@pxref{Programmable Completion Builtins}), 1873the programmable completion facilities are invoked. 1874 1875First, the command name is identified. 1876If a compspec has been defined for that command, the 1877compspec is used to generate the list of possible completions for the word. 1878If the command word is the empty string (completion attempted at the 1879beginning of an empty line), any compspec defined with 1880the @option{-E} option to @code{complete} is used. 1881If the command word is a full pathname, a compspec for the full 1882pathname is searched for first. 1883If no compspec is found for the full pathname, an attempt is made to 1884find a compspec for the portion following the final slash. 1885If those searches do not result in a compspec, any compspec defined with 1886the @option{-D} option to @code{complete} is used as the default. 1887If there is no default compspec, Bash attempts alias expansion 1888on the command word as a final resort, and attempts to find a compspec 1889for the command word from any successful expansion 1890 1891Once a compspec has been found, it is used to generate the list of 1892matching words. 1893If a compspec is not found, the default Bash completion 1894described above (@pxref{Commands For Completion}) is performed. 1895 1896First, the actions specified by the compspec are used. 1897Only matches which are prefixed by the word being completed are 1898returned. 1899When the @option{-f} or @option{-d} option is used for filename or 1900directory name completion, the shell variable @env{FIGNORE} is 1901used to filter the matches. 1902@xref{Bash Variables}, for a description of @env{FIGNORE}. 1903 1904Any completions specified by a filename expansion pattern to the 1905@option{-G} option are generated next. 1906The words generated by the pattern need not match the word being completed. 1907The @env{GLOBIGNORE} shell variable is not used to filter the matches, 1908but the @env{FIGNORE} shell variable is used. 1909 1910Next, the string specified as the argument to the @option{-W} option 1911is considered. 1912The string is first split using the characters in the @env{IFS} 1913special variable as delimiters. 1914Shell quoting is honored within the string, in order to provide a 1915mechanism for the words to contain shell metacharacters or characters 1916in the value of @env{IFS}. 1917Each word is then expanded using 1918brace expansion, tilde expansion, parameter and variable expansion, 1919command substitution, and arithmetic expansion, 1920as described above (@pxref{Shell Expansions}). 1921The results are split using the rules described above 1922(@pxref{Word Splitting}). 1923The results of the expansion are prefix-matched against the word being 1924completed, and the matching words become the possible completions. 1925 1926After these matches have been generated, any shell function or command 1927specified with the @option{-F} and @option{-C} options is invoked. 1928When the command or function is invoked, the @env{COMP_LINE}, 1929@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are 1930assigned values as described above (@pxref{Bash Variables}). 1931If a shell function is being invoked, the @env{COMP_WORDS} and 1932@env{COMP_CWORD} variables are also set. 1933When the function or command is invoked, the first argument ($1) is the 1934name of the command whose arguments are being completed, the 1935second argument ($2) is the word being completed, and the third argument 1936($3) is the word preceding the word being completed on the current command 1937line. 1938No filtering of the generated completions against the word being completed 1939is performed; the function or command has complete freedom in generating 1940the matches. 1941 1942Any function specified with @option{-F} is invoked first. 1943The function may use any of the shell facilities, including the 1944@code{compgen} and @code{compopt} builtins described below 1945(@pxref{Programmable Completion Builtins}), to generate the matches. 1946It must put the possible completions in the @env{COMPREPLY} array 1947variable, one per array element. 1948 1949Next, any command specified with the @option{-C} option is invoked 1950in an environment equivalent to command substitution. 1951It should print a list of completions, one per line, to 1952the standard output. 1953Backslash may be used to escape a newline, if necessary. 1954 1955After all of the possible completions are generated, any filter 1956specified with the @option{-X} option is applied to the list. 1957The filter is a pattern as used for pathname expansion; a @samp{&} 1958in the pattern is replaced with the text of the word being completed. 1959A literal @samp{&} may be escaped with a backslash; the backslash 1960is removed before attempting a match. 1961Any completion that matches the pattern will be removed from the list. 1962A leading @samp{!} negates the pattern; in this case any completion 1963not matching the pattern will be removed. 1964If the @code{nocasematch} shell option 1965(see the description of @code{shopt} in @ref{The Shopt Builtin}) 1966is enabled, the match is performed without regard to the case 1967of alphabetic characters. 1968 1969Finally, any prefix and suffix specified with the @option{-P} and @option{-S} 1970options are added to each member of the completion list, and the result is 1971returned to the Readline completion code as the list of possible 1972completions. 1973 1974If the previously-applied actions do not generate any matches, and the 1975@option{-o dirnames} option was supplied to @code{complete} when the 1976compspec was defined, directory name completion is attempted. 1977 1978If the @option{-o plusdirs} option was supplied to @code{complete} when 1979the compspec was defined, directory name completion is attempted and any 1980matches are added to the results of the other actions. 1981 1982By default, if a compspec is found, whatever it generates is returned to 1983the completion code as the full set of possible completions. 1984The default Bash completions are not attempted, and the Readline default 1985of filename completion is disabled. 1986If the @option{-o bashdefault} option was supplied to @code{complete} when 1987the compspec was defined, the default Bash completions are attempted 1988if the compspec generates no matches. 1989If the @option{-o default} option was supplied to @code{complete} when the 1990compspec was defined, Readline's default completion will be performed 1991if the compspec (and, if attempted, the default Bash completions) 1992generate no matches. 1993 1994When a compspec indicates that directory name completion is desired, 1995the programmable completion functions force Readline to append a slash 1996to completed names which are symbolic links to directories, subject to 1997the value of the @var{mark-directories} Readline variable, regardless 1998of the setting of the @var{mark-symlinked-directories} Readline variable. 1999 2000There is some support for dynamically modifying completions. This is 2001most useful when used in combination with a default completion specified 2002with @option{-D}. It's possible for shell functions executed as completion 2003handlers to indicate that completion should be retried by returning an 2004exit status of 124. If a shell function returns 124, and changes 2005the compspec associated with the command on which completion is being 2006attempted (supplied as the first argument when the function is executed), 2007programmable completion restarts from the beginning, with an 2008attempt to find a new compspec for that command. This allows a set of 2009completions to be built dynamically as completion is attempted, rather than 2010being loaded all at once. 2011 2012For instance, assuming that there is a library of compspecs, each kept in a 2013file corresponding to the name of the command, the following default 2014completion function would load completions dynamically: 2015 2016@example 2017_completion_loader() 2018@{ 2019 . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 2020@} 2021complete -D -F _completion_loader -o bashdefault -o default 2022@end example 2023 2024@node Programmable Completion Builtins 2025@section Programmable Completion Builtins 2026@cindex completion builtins 2027 2028Three builtin commands are available to manipulate the programmable completion 2029facilities: one to specify how the arguments to a particular command are to 2030be completed, and two to modify the completion as it is happening. 2031 2032@table @code 2033@item compgen 2034@btindex compgen 2035@example 2036@code{compgen [@var{option}] [@var{word}]} 2037@end example 2038 2039Generate possible completion matches for @var{word} according to 2040the @var{option}s, which may be any option accepted by the 2041@code{complete} 2042builtin with the exception of @option{-p} and @option{-r}, and write 2043the matches to the standard output. 2044When using the @option{-F} or @option{-C} options, the various shell variables 2045set by the programmable completion facilities, while available, will not 2046have useful values. 2047 2048The matches will be generated in the same way as if the programmable 2049completion code had generated them directly from a completion specification 2050with the same flags. 2051If @var{word} is specified, only those completions matching @var{word} 2052will be displayed. 2053 2054The return value is true unless an invalid option is supplied, or no 2055matches were generated. 2056 2057@item complete 2058@btindex complete 2059@example 2060@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-A @var{action}] [-G @var{globpat}] 2061[-W @var{wordlist}] [-F @var{function}] [-C @var{command}] [-X @var{filterpat}] 2062[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]} 2063@code{complete -pr [-DEI] [@var{name} @dots{}]} 2064@end example 2065 2066Specify how arguments to each @var{name} should be completed. 2067If the @option{-p} option is supplied, or if no options are supplied, existing 2068completion specifications are printed in a way that allows them to be 2069reused as input. 2070The @option{-r} option removes a completion specification for 2071each @var{name}, or, if no @var{name}s are supplied, all 2072completion specifications. 2073The @option{-D} option indicates that other supplied options and actions should 2074apply to the ``default'' command completion; that is, completion attempted 2075on a command for which no completion has previously been defined. 2076The @option{-E} option indicates that other supplied options and actions should 2077apply to ``empty'' command completion; that is, completion attempted on a 2078blank line. 2079The @option{-I} option indicates that other supplied options and actions should 2080apply to completion on the initial non-assignment word on the line, or after a 2081command delimiter such as @samp{;} or @samp{|}, which is usually command 2082name completion. 2083If multiple options are supplied, the @option{-D} option takes precedence 2084over @option{-E}, and both take precedence over @option{-I}. 2085If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other 2086@var{name} arguments are ignored; these completions only apply to the case 2087specified by the option. 2088 2089The process of applying these completion specifications when word completion 2090is attempted is described above (@pxref{Programmable Completion}). 2091 2092Other options, if specified, have the following meanings. 2093The arguments to the @option{-G}, @option{-W}, and @option{-X} options 2094(and, if necessary, the @option{-P} and @option{-S} options) 2095should be quoted to protect them from expansion before the 2096@code{complete} builtin is invoked. 2097 2098 2099@table @code 2100@item -o @var{comp-option} 2101The @var{comp-option} controls several aspects of the compspec's behavior 2102beyond the simple generation of completions. 2103@var{comp-option} may be one of: 2104 2105@table @code 2106 2107@item bashdefault 2108Perform the rest of the default Bash completions if the compspec 2109generates no matches. 2110 2111@item default 2112Use Readline's default filename completion if the compspec generates 2113no matches. 2114 2115@item dirnames 2116Perform directory name completion if the compspec generates no matches. 2117 2118@item filenames 2119Tell Readline that the compspec generates filenames, so it can perform any 2120filename-specific processing (like adding a slash to directory names, 2121quoting special characters, or suppressing trailing spaces). 2122This option is intended to be used with shell functions specified 2123with @option{-F}. 2124 2125@item noquote 2126Tell Readline not to quote the completed words if they are filenames 2127(quoting filenames is the default). 2128 2129@item nosort 2130Tell Readline not to sort the list of possible completions alphabetically. 2131 2132@item nospace 2133Tell Readline not to append a space (the default) to words completed at 2134the end of the line. 2135 2136@item plusdirs 2137After any matches defined by the compspec are generated, 2138directory name completion is attempted and any 2139matches are added to the results of the other actions. 2140 2141@end table 2142 2143@item -A @var{action} 2144The @var{action} may be one of the following to generate a list of possible 2145completions: 2146 2147@table @code 2148@item alias 2149Alias names. May also be specified as @option{-a}. 2150 2151@item arrayvar 2152Array variable names. 2153 2154@item binding 2155Readline key binding names (@pxref{Bindable Readline Commands}). 2156 2157@item builtin 2158Names of shell builtin commands. May also be specified as @option{-b}. 2159 2160@item command 2161Command names. May also be specified as @option{-c}. 2162 2163@item directory 2164Directory names. May also be specified as @option{-d}. 2165 2166@item disabled 2167Names of disabled shell builtins. 2168 2169@item enabled 2170Names of enabled shell builtins. 2171 2172@item export 2173Names of exported shell variables. May also be specified as @option{-e}. 2174 2175@item file 2176File names. May also be specified as @option{-f}. 2177 2178@item function 2179Names of shell functions. 2180 2181@item group 2182Group names. May also be specified as @option{-g}. 2183 2184@item helptopic 2185Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}). 2186 2187@item hostname 2188Hostnames, as taken from the file specified by the 2189@env{HOSTFILE} shell variable (@pxref{Bash Variables}). 2190 2191@item job 2192Job names, if job control is active. May also be specified as @option{-j}. 2193 2194@item keyword 2195Shell reserved words. May also be specified as @option{-k}. 2196 2197@item running 2198Names of running jobs, if job control is active. 2199 2200@item service 2201Service names. May also be specified as @option{-s}. 2202 2203@item setopt 2204Valid arguments for the @option{-o} option to the @code{set} builtin 2205(@pxref{The Set Builtin}). 2206 2207@item shopt 2208Shell option names as accepted by the @code{shopt} builtin 2209(@pxref{Bash Builtins}). 2210 2211@item signal 2212Signal names. 2213 2214@item stopped 2215Names of stopped jobs, if job control is active. 2216 2217@item user 2218User names. May also be specified as @option{-u}. 2219 2220@item variable 2221Names of all shell variables. May also be specified as @option{-v}. 2222@end table 2223 2224@item -C @var{command} 2225@var{command} is executed in a subshell environment, and its output is 2226used as the possible completions. 2227 2228@item -F @var{function} 2229The shell function @var{function} is executed in the current shell 2230environment. 2231When it is executed, $1 is the name of the command whose arguments are 2232being completed, $2 is the word being completed, and $3 is the word 2233preceding the word being completed, as described above 2234(@pxref{Programmable Completion}). 2235When it finishes, the possible completions are retrieved from the value 2236of the @env{COMPREPLY} array variable. 2237 2238@item -G @var{globpat} 2239The filename expansion pattern @var{globpat} is expanded to generate 2240the possible completions. 2241 2242@item -P @var{prefix} 2243@var{prefix} is added at the beginning of each possible completion 2244after all other options have been applied. 2245 2246@item -S @var{suffix} 2247@var{suffix} is appended to each possible completion 2248after all other options have been applied. 2249 2250@item -W @var{wordlist} 2251The @var{wordlist} is split using the characters in the 2252@env{IFS} special variable as delimiters, and each resultant word 2253is expanded. 2254The possible completions are the members of the resultant list which 2255match the word being completed. 2256 2257@item -X @var{filterpat} 2258@var{filterpat} is a pattern as used for filename expansion. 2259It is applied to the list of possible completions generated by the 2260preceding options and arguments, and each completion matching 2261@var{filterpat} is removed from the list. 2262A leading @samp{!} in @var{filterpat} negates the pattern; in this 2263case, any completion not matching @var{filterpat} is removed. 2264@end table 2265 2266The return value is true unless an invalid option is supplied, an option 2267other than @option{-p} or @option{-r} is supplied without a @var{name} 2268argument, an attempt is made to remove a completion specification for 2269a @var{name} for which no specification exists, or 2270an error occurs adding a completion specification. 2271 2272@item compopt 2273@btindex compopt 2274@example 2275@code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}] 2276@end example 2277Modify completion options for each @var{name} according to the 2278@var{option}s, or for the currently-executing completion if no @var{name}s 2279are supplied. 2280If no @var{option}s are given, display the completion options for each 2281@var{name} or the current completion. 2282The possible values of @var{option} are those valid for the @code{complete} 2283builtin described above. 2284The @option{-D} option indicates that other supplied options should 2285apply to the ``default'' command completion; that is, completion attempted 2286on a command for which no completion has previously been defined. 2287The @option{-E} option indicates that other supplied options should 2288apply to ``empty'' command completion; that is, completion attempted on a 2289blank line. 2290The @option{-I} option indicates that other supplied options should 2291apply to completion on the initial non-assignment word on the line, or after a 2292command delimiter such as @samp{;} or @samp{|}, which is usually command 2293name completion. 2294 2295If multiple options are supplied, the @option{-D} option takes precedence 2296over @option{-E}, and both take precedence over @option{-I} 2297 2298The return value is true unless an invalid option is supplied, an attempt 2299is made to modify the options for a @var{name} for which no completion 2300specification exists, or an output error occurs. 2301 2302@end table 2303 2304@node A Programmable Completion Example 2305@section A Programmable Completion Example 2306 2307The most common way to obtain additional completion functionality beyond 2308the default actions @code{complete} and @code{compgen} provide is to use 2309a shell function and bind it to a particular command using @code{complete -F}. 2310 2311The following function provides completions for the @code{cd} builtin. 2312It is a reasonably good example of what shell functions must do when 2313used for completion. This function uses the word passed as @code{$2} 2314to determine the directory name to complete. You can also use the 2315@code{COMP_WORDS} array variable; the current word is indexed by the 2316@code{COMP_CWORD} variable. 2317 2318The function relies on the @code{complete} and @code{compgen} builtins 2319to do much of the work, adding only the things that the Bash @code{cd} 2320does beyond accepting basic directory names: 2321tilde expansion (@pxref{Tilde Expansion}), 2322searching directories in @var{$CDPATH}, which is described above 2323(@pxref{Bourne Shell Builtins}), 2324and basic support for the @code{cdable_vars} shell option 2325(@pxref{The Shopt Builtin}). 2326@code{_comp_cd} modifies the value of @var{IFS} so that it contains only 2327a newline to accommodate file names containing spaces and tabs -- 2328@code{compgen} prints the possible completions it generates one per line. 2329 2330Possible completions go into the @var{COMPREPLY} array variable, one 2331completion per array element. The programmable completion system retrieves 2332the completions from there when the function returns. 2333 2334@example 2335# A completion function for the cd builtin 2336# based on the cd completion function from the bash_completion package 2337_comp_cd() 2338@{ 2339 local IFS=$' \t\n' # normalize IFS 2340 local cur _skipdot _cdpath 2341 local i j k 2342 2343 # Tilde expansion, which also expands tilde to full pathname 2344 case "$2" in 2345 \~*) eval cur="$2" ;; 2346 *) cur=$2 ;; 2347 esac 2348 2349 # no cdpath or absolute pathname -- straight directory completion 2350 if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then 2351 # compgen prints paths one per line; could also use while loop 2352 IFS=$'\n' 2353 COMPREPLY=( $(compgen -d -- "$cur") ) 2354 IFS=$' \t\n' 2355 # CDPATH+directories in the current directory if not in CDPATH 2356 else 2357 IFS=$'\n' 2358 _skipdot=false 2359 # preprocess CDPATH to convert null directory names to . 2360 _cdpath=$@{CDPATH/#:/.:@} 2361 _cdpath=$@{_cdpath//::/:.:@} 2362 _cdpath=$@{_cdpath/%:/:.@} 2363 for i in $@{_cdpath//:/$'\n'@}; do 2364 if [[ $i -ef . ]]; then _skipdot=true; fi 2365 k="$@{#COMPREPLY[@@]@}" 2366 for j in $( compgen -d -- "$i/$cur" ); do 2367 COMPREPLY[k++]=$@{j#$i/@} # cut off directory 2368 done 2369 done 2370 $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) 2371 IFS=$' \t\n' 2372 fi 2373 2374 # variable names if appropriate shell option set and no completions 2375 if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then 2376 COMPREPLY=( $(compgen -v -- "$cur") ) 2377 fi 2378 2379 return 0 2380@} 2381@end example 2382 2383We install the completion function using the @option{-F} option to 2384@code{complete}: 2385 2386@example 2387# Tell readline to quote appropriate and append slashes to directories; 2388# use the bash default completion for other arguments 2389complete -o filenames -o nospace -o bashdefault -F _comp_cd cd 2390@end example 2391 2392@noindent 2393Since we'd like Bash and Readline to take care of some 2394of the other details for us, we use several other options to tell Bash 2395and Readline what to do. The @option{-o filenames} option tells Readline 2396that the possible completions should be treated as filenames, and quoted 2397appropriately. That option will also cause Readline to append a slash to 2398filenames it can determine are directories (which is why we might want to 2399extend @code{_comp_cd} to append a slash if we're using directories found 2400via @var{CDPATH}: Readline can't tell those completions are directories). 2401The @option{-o nospace} option tells Readline to not append a space 2402character to the directory name, in case we want to append to it. 2403The @option{-o bashdefault} option brings in the rest of the "Bash default" 2404completions -- possible completion that Bash adds to the default Readline 2405set. These include things like command name completion, variable completion 2406for words beginning with @samp{$} or @samp{$@{}, completions containing pathname 2407expansion patterns (@pxref{Filename Expansion}), and so on. 2408 2409Once installed using @code{complete}, @code{_comp_cd} will be called every 2410time we attempt word completion for a @code{cd} command. 2411 2412Many more examples -- an extensive collection of completions for most of 2413the common GNU, Unix, and Linux commands -- are available as part of the 2414bash_completion project. This is installed by default on many GNU/Linux 2415distributions. Originally written by Ian Macdonald, the project now lives 2416at @url{https://github.com/scop/bash-completion/}. There are ports for 2417other systems such as Solaris and Mac OS X. 2418 2419An older version of the bash_completion package is distributed with bash 2420in the @file{examples/complete} subdirectory. 2421 2422@end ifset 2423