1@c This is part of the Emacs manual. 2@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 3@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 4@c See file emacs.texi for copying conditions. 5@node Minibuffer, M-x, Basic, Top 6@chapter The Minibuffer 7@cindex minibuffer 8 9 The @dfn{minibuffer} is where Emacs commands read complicated 10arguments (anything more a single number). We call it the 11``minibuffer'' because it's a special-purpose buffer with a small 12amount of screen space. Minibuffer arguments can be file names, 13buffer names, Lisp function names, Emacs command names, Lisp 14expressions, and many other things---whatever the command wants to 15read. You can use the usual Emacs editing commands in the minibuffer 16to edit the argument text. 17 18@cindex prompt 19 When the minibuffer is in use, it appears in the echo area, with a 20cursor. The minibuffer display starts with a @dfn{prompt} in a 21distinct color; it says what kind of input is expected and how it will 22be used. Often the prompt is derived from the name of the command 23that is reading the argument. The prompt normally ends with a colon. 24 25@cindex default argument 26 Sometimes a @dfn{default argument} appears in the prompt, inside 27parentheses before the colon. The default will be used as the 28argument value if you just type @key{RET}. For example, commands that 29read buffer names show a buffer name as the default. You can type 30@key{RET} to operate on that default buffer. 31 32 The simplest way to enter a minibuffer argument is to type the text, 33then @key{RET} to exit the minibuffer. You can cancel the minibuffer, 34and the command that wants the argument, by typing @kbd{C-g}. 35 36 Since the minibuffer appears in the echo area, it can conflict with 37other uses of the echo area. Here is how Emacs handles such 38conflicts: 39 40@itemize @bullet 41@item 42An error occurs while the minibuffer is active. 43 44The error message hides the minibuffer for a few seconds, or until you 45type something. Then the minibuffer comes back. 46 47@item 48A command such as @kbd{C-x =} needs to display a message in the echo 49area. 50 51The message hides the minibuffer for a few seconds, or until you type 52something. Then the minibuffer comes back. 53 54@item 55Keystrokes don't echo while the minibuffer is in use. 56@end itemize 57 58@menu 59* File: Minibuffer File. Entering file names with the minibuffer. 60* Edit: Minibuffer Edit. How to edit in the minibuffer. 61* Completion:: An abbreviation facility for minibuffer input. 62* Minibuffer History:: Reusing recent minibuffer arguments. 63* Repetition:: Re-executing commands that used the minibuffer. 64@end menu 65 66@node Minibuffer File 67@section Minibuffers for File Names 68 69 When you use the minibuffer to enter a file name, it starts out with 70some initial text---the @dfn{default directory}, ending in a slash. 71The file you specify will be in this directory unless you alter or 72replace it. 73 74@c Separate paragraph to clean up ugly page break--rms 75@need 1500 76 For example, if the minibuffer starts out with these contents: 77 78@example 79Find File: /u2/emacs/src/ 80@end example 81 82@noindent 83(where @samp{Find File:@: } is the prompt), and you type 84@kbd{buffer.c} as input, that specifies the file 85@file{/u2/emacs/src/buffer.c}. You can specify the parent directory 86by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you 87will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use 88@kbd{M-@key{DEL}} to kill the directory names you don't want 89(@pxref{Words}). 90 91 You can kill the entire default with @kbd{C-a C-k}, but there's no 92need to do that. It's easier to ignore the default, and enter an 93absolute file name starting with a slash or a tilde after the default 94directory. For example, to specify @file{/etc/termcap}, just type 95that name: 96 97@example 98Find File: /u2/emacs/src//etc/termcap 99@end example 100 101@noindent 102@cindex // in file name 103@cindex double slash in file name 104@cindex slashes repeated in file name 105@findex file-name-shadow-mode 106GNU Emacs interprets a double slash (which is not normally useful in 107file names) as, ``ignore everything before the second slash in the 108pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so 109you get @file{/etc/termcap}. The ignored part of the file name is 110dimmed if the terminal allows it; to disable this dimming, turn off 111File Name Shadow mode (a minor mode) with the command 112@kbd{M-x file-name-shadow-mode}. 113 114 If the variable @code{insert-default-directory} is @code{nil}, the 115default directory is never inserted in the minibuffer---so the 116minibuffer starts out empty. Nonetheless, relative file name 117arguments are still interpreted based on the same default directory. 118 119@node Minibuffer Edit 120@section Editing in the Minibuffer 121 122 The minibuffer is an Emacs buffer (albeit a peculiar one), and the 123usual Emacs commands are available for editing the argument text. 124 125 Since @key{RET} in the minibuffer is defined to exit the minibuffer, 126you can't use it to insert a newline in the minibuffer. To do that, 127type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the 128@acronym{ASCII} character control-J.) 129 130 The minibuffer has its own window, which normally has space in the 131frame at all times, but it only acts like an Emacs window when the 132minibuffer is active. When active, this window is much like any other 133Emacs window; for instance, you can switch to another window (with 134@kbd{C-x o}), edit text there, then return to the minibuffer window to 135finish the argument. You can even kill text in another window, return 136to the minibuffer window, and then yank the text into the argument. 137@xref{Windows}. 138 139@cindex height of minibuffer 140@cindex size of minibuffer 141@cindex growing minibuffer 142@cindex resizing minibuffer 143 There are some restrictions on the minibuffer window, however: you 144cannot kill it, or split it, or switch buffers in it---the minibuffer 145and its window are permanently attached. 146 147@vindex resize-mini-windows 148 The minibuffer window expands vertically as necessary to hold the 149text that you put in the minibuffer. If @code{resize-mini-windows} is 150@code{t} (the default), the window always resizes as needed by its 151contents. If its value is the symbol @code{grow-only}, the window 152grows automatically as needed, but shrinks (back to the normal size) 153only when the minibuffer becomes inactive. If its value is 154@code{nil}, you have to adjust the height yourself. 155 156@vindex max-mini-window-height 157 The variable @code{max-mini-window-height} controls the maximum 158height for resizing the minibuffer window: a floating-point number 159specifies a fraction of the frame's height; an integer specifies the 160maximum number of lines; @code{nil} means do not resize the minibuffer 161window automatically. The default value is 0.25. 162 163 The @kbd{C-M-v} command in the minibuffer scrolls the help text from 164commands that display help text of any sort in another window. 165@kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that 166help text. This is especially useful with long lists of possible 167completions. @xref{Other Window}. 168 169@vindex enable-recursive-minibuffers 170 Emacs normally disallows most commands that use the minibuffer while 171the minibuffer is active. (Entering the minibuffer from the 172minibuffer can be confusing.) To allow such commands in the 173minibuffer, set the variable @code{enable-recursive-minibuffers} to 174@code{t}. 175 176@node Completion 177@section Completion 178@cindex completion 179 180 Some arguments allow @dfn{completion} to enter their value. This 181means that after you type part of the argument, Emacs can fill in the 182rest, or some of it, based on what you have typed so far. 183 184 When completion is available, certain keys---@key{TAB}, @key{RET}, 185and @key{SPC}---are rebound to complete the text in the minibuffer 186before point into a longer string chosen from a set of @dfn{completion 187alternatives} provided by the command that requested the argument. 188(@key{SPC} does not do completion in reading file names, because it is 189common to use spaces in file names on some systems.) @kbd{?} displays 190a list of the possible completions at any time. 191 192 For example, @kbd{M-x} uses the minibuffer to read the name of a 193command, so it provides a list of all Emacs command names for 194completion candidates. The completion keys match the minibuffer text 195against these candidates, find any additional name characters implied 196by the text already present in the minibuffer, and add those 197characters. This makes it possible to type @kbd{M-x ins @key{SPC} b 198@key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example. 199 200 Case is significant in completion when it is significant in the 201argument you are entering (buffer names, file names, command names, 202for instance). Thus, @samp{fo} does not complete to @samp{Foo}. 203Completion ignores case distinctions for certain arguments in which 204case does not matter. 205 206 Completion acts only on the text before point. If there is text in 207the minibuffer after point---i.e., if you move point backward after 208typing some text into the minibuffer---it remains unchanged. 209 210@menu 211* Example: Completion Example. Examples of using completion. 212* Commands: Completion Commands. A list of completion commands. 213* Strict Completion:: Different types of completion. 214* Options: Completion Options. Options for completion. 215@end menu 216 217@node Completion Example 218@subsection Completion Example 219 220@kindex TAB @r{(completion)} 221 A concrete example may help here. If you type @kbd{M-x au 222@key{TAB}}, the @key{TAB} looks for alternatives (in this case, 223command names) that start with @samp{au}. There are several, 224including @code{auto-fill-mode} and @code{auto-save-mode}, but they 225all begin with @code{auto-}, so the @samp{au} in the minibuffer 226completes to @samp{auto-}. 227 228 If you type @key{TAB} again immediately, it cannot determine the 229next character; it could be any of @samp{cfilrs}. So it does not add 230any characters; instead, @key{TAB} displays a list of all possible 231completions in another window. 232 233 Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The 234only command name starting with that is @code{auto-fill-mode}, so 235completion fills in the rest of that. You have been able to enter 236@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. 237 238@node Completion Commands 239@subsection Completion Commands 240 241 Here is a list of the completion commands defined in the minibuffer 242when completion is allowed. 243 244@table @kbd 245@item @key{TAB} 246@findex minibuffer-complete 247Complete the text before point in the minibuffer as much as possible 248(@code{minibuffer-complete}). 249@item @key{SPC} 250Complete up to one word from the minibuffer text before point 251(@code{minibuffer-complete-word}). @key{SPC} for completion is not 252available when entering a file name, since file names often include 253spaces. 254@item @key{RET} 255Submit the text in the minibuffer as the argument, possibly completing 256first as described 257@iftex 258in the next subsection (@code{minibuffer-complete-and-exit}). 259@end iftex 260@ifnottex 261in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict 262Completion}. 263@end ifnottex 264@item ? 265Display a list of possible completions of the text before point 266(@code{minibuffer-completion-help}). 267@end table 268 269@kindex SPC 270@findex minibuffer-complete-word 271 @key{SPC} completes like @key{TAB}, but only up to the next hyphen 272or space. If you have @samp{auto-f} in the minibuffer and type 273@key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but 274it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another 275@key{SPC} at this point completes all the way to 276@samp{auto-fill-mode}. The command that implements this behavior is 277called @code{minibuffer-complete-word}. 278 279 When you display a list of possible completions, you can choose 280one from it: 281 282@table @kbd 283@findex mouse-choose-completion 284@item Mouse-1 285@itemx Mouse-2 286Clicking mouse button 1 or 2 on a completion possibility chooses that 287completion (@code{mouse-choose-completion}). You must click in the 288list of completions, not in the minibuffer. 289 290@findex switch-to-completions 291@item @key{PRIOR} 292@itemx M-v 293Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the 294minibuffer, selects the window showing the completion list buffer 295(@code{switch-to-completions}). This paves the way for using the 296commands below. (Selecting that window in other ways has the same 297effect.) 298 299@findex choose-completion 300@item @key{RET} 301Typing @key{RET} @emph{in the completion list buffer} chooses the 302completion that point is in or next to (@code{choose-completion}). To 303use this command, you must first switch to the completion list window. 304 305@findex next-completion 306@item @key{RIGHT} 307Typing the right-arrow key @key{RIGHT} @emph{in the completion list 308buffer} moves point to the following completion possibility 309(@code{next-completion}). 310 311@findex previous-completion 312@item @key{LEFT} 313Typing the left-arrow key @key{LEFT} @emph{in the completion list 314buffer} moves point to the previous completion possibility 315(@code{previous-completion}). 316@end table 317 318@node Strict Completion 319@subsection Strict Completion 320 321 There are three different ways that @key{RET} can do completion, 322depending on how the argument will be used. 323 324@itemize @bullet 325@item 326@dfn{Strict} completion accepts only known completion candidates. For 327example, when @kbd{C-x k} reads the name of a buffer to kill, only the 328name of an existing buffer makes sense. In strict completion, 329@key{RET} refuses to exit if the text in the minibuffer does not 330complete to an exact match. 331 332@item 333@dfn{Cautious} completion is similar to strict completion, except that 334@key{RET} exits only if the text is an already exact match. 335Otherwise, @key{RET} does not exit, but it does complete the text. If 336that completes to an exact match, a second @key{RET} will exit. 337 338Cautious completion is used for reading file names for files that must 339already exist, for example. 340 341@item 342@dfn{Permissive} completion allows any input; the completion 343candidates are just suggestions. For example, when @kbd{C-x C-f} 344reads the name of a file to visit, any file name is allowed, including 345nonexistent file (in case you want to create a file). In permissive 346completion, @key{RET} does not complete, it just submits the argument 347as you have entered it. 348@end itemize 349 350 The completion commands display a list of all possible completions 351whenever they can't determine even one more character by completion. 352Also, typing @kbd{?} explicitly requests such a list. You can scroll 353the list with @kbd{C-M-v} (@pxref{Other Window}). 354 355@node Completion Options 356@subsection Completion Options 357 358@vindex completion-ignored-extensions 359@cindex ignored file names, in completion 360 When completing file names, certain file names are usually ignored. 361The variable @code{completion-ignored-extensions} contains a list of 362strings; a file name ending in any of those strings is ignored as a 363completion candidate. The standard value of this variable has several 364elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and 365@code{"~"}. The effect is that, for example, @samp{foo} can complete 366to @samp{foo.c} even though @samp{foo.o} exists as well. However, if 367@emph{all} the possible completions end in ``ignored'' strings, then 368they are not ignored. Displaying a list of possible completions 369disregards @code{completion-ignored-extensions}; it shows them all. 370 371 If an element of @code{completion-ignored-extensions} ends in a 372slash (@file{/}), it's a subdirectory name; then that directory and 373its contents are ignored. Elements of 374@code{completion-ignored-extensions} which do not end in a slash are 375ordinary file names, and do not apply to names of directories. 376 377@vindex completion-auto-help 378 If @code{completion-auto-help} is set to @code{nil}, the completion 379commands never display a list of possibilities; you must type @kbd{?} 380to display the list. 381 382@cindex Partial Completion mode 383@vindex partial-completion-mode 384@findex partial-completion-mode 385 Partial Completion mode implements a more powerful kind of 386completion that can complete multiple words in parallel. For example, 387it can complete the command name abbreviation @code{p-b} into 388@code{print-buffer} if no other command starts with two words whose 389initials are @samp{p} and @samp{b}. 390 391 To enable this mode, use @kbd{M-x partial-completion-mode}, or 392customize the variable @code{partial-completion-mode}. This mode 393binds special partial completion commands to @key{TAB}, @key{SPC}, 394@key{RET}, and @kbd{?} in the minibuffer. The usual completion 395commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}), 396@kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}. 397 398 Partial completion of directories in file names uses @samp{*} to 399indicate the places for completion; thus, @file{/u*/b*/f*} might 400complete to @file{/usr/bin/foo}. For remote files, partial completion 401enables completion of methods, user names and host names. 402@xref{Remote Files}. 403 404@vindex PC-include-file-path 405@vindex PC-disable-includes 406 Partial Completion mode also extends @code{find-file} so that 407@samp{<@var{include}>} looks for the file named @var{include} in the 408directories in the path @code{PC-include-file-path}. If you set 409@code{PC-disable-includes} to non-@code{nil}, this feature is 410disabled. 411 412@cindex Icomplete mode 413@findex icomplete-mode 414 Icomplete mode presents a constantly-updated display that tells you 415what completions are available for the text you've entered so far. The 416command to enable or disable this minor mode is @kbd{M-x 417icomplete-mode}. 418 419@node Minibuffer History 420@section Minibuffer History 421@cindex minibuffer history 422@cindex history of minibuffer input 423 424 Every argument that you enter with the minibuffer is saved on a 425@dfn{minibuffer history list} so you can easily use it again later. 426Special commands fetch the text of an earlier argument into the 427minibuffer, replacing the old minibuffer contents. You can think of 428them as moving through the history of previous arguments. 429 430@table @kbd 431@item @key{UP} 432@itemx M-p 433Move to the previous item in the minibuffer history, an earlier argument 434(@code{previous-history-element}). 435@item @key{DOWN} 436@itemx M-n 437Move to the next item in the minibuffer history 438(@code{next-history-element}). 439@item M-r @var{regexp} @key{RET} 440Move to an earlier item in the minibuffer history that 441matches @var{regexp} (@code{previous-matching-history-element}). 442@item M-s @var{regexp} @key{RET} 443Move to a later item in the minibuffer history that matches 444@var{regexp} (@code{next-matching-history-element}). 445@end table 446 447@kindex M-p @r{(minibuffer history)} 448@kindex M-n @r{(minibuffer history)} 449@findex next-history-element 450@findex previous-history-element 451 To move through the minibuffer history list one item at a time, use 452@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the 453next earlier minibuffer input, and use @kbd{M-n} or down-arrow 454(@code{next-history-element}) to fetch the next later input. These 455commands don't move the cursor, they pull different saved strings into 456the minibuffer. But you can think of them as ``moving'' through the 457history list. 458 459 The input that you fetch from the history entirely replaces the 460contents of the minibuffer. To use it again unchanged, just type 461@key{RET}. You can also edit the text before you reuse it; this does 462not change the history element that you ``moved'' to, but your new 463argument does go at the end of the history list in its own right. 464 465 For many minibuffer arguments there is a ``default'' value. You can 466insert the default value into the minibuffer as text by using 467@kbd{M-n}. You can think of this as moving ``into the future'' in the 468history. 469 470@findex previous-matching-history-element 471@findex next-matching-history-element 472@kindex M-r @r{(minibuffer history)} 473@kindex M-s @r{(minibuffer history)} 474 There are also commands to search forward or backward through the 475history; they search for history elements that match a regular 476expression. @kbd{M-r} (@code{previous-matching-history-element}) 477searches older elements in the history, while @kbd{M-s} 478(@code{next-matching-history-element}) searches newer elements. These 479commands are unusual; they use the minibuffer to read the regular 480expression even though they are invoked from the minibuffer. As with 481incremental searching, an upper-case letter in the regular expression 482makes the search case-sensitive (@pxref{Search Case}). 483 484@ignore 485 We may change the precise way these commands read their arguments. 486Perhaps they will search for a match for the string given so far in the 487minibuffer; perhaps they will search for a literal match rather than a 488regular expression match; perhaps they will only accept matches at the 489beginning of a history element; perhaps they will read the string to 490search for incrementally like @kbd{C-s}. To find out what interface is 491actually available, type @kbd{C-h f previous-matching-history-element}. 492@end ignore 493 494 All uses of the minibuffer record your input on a history list, but 495there are separate history lists for different kinds of arguments. 496For example, there is a list for file names, used by all the commands 497that read file names. (As a special feature, this history list 498records the absolute file name, even if the name you entered was not 499absolute.) 500 501 There are several other specific history lists, including one for 502buffer names, one for arguments of commands like @code{query-replace}, 503one used by @kbd{M-x} for command names, and one used by 504@code{compile} for compilation commands. Finally, there is one 505``miscellaneous'' history list that most minibuffer arguments use. 506 507@vindex history-length 508 The variable @code{history-length} specifies the maximum length of a 509minibuffer history list; adding a new element deletes the oldest 510element if the list gets too long. If the value of 511@code{history-length} is @code{t}, though, there is no maximum length. 512 513@vindex history-delete-duplicates 514 The variable @code{history-delete-duplicates} specifies whether to 515delete duplicates in history. If it is @code{t}, adding a new element 516deletes from the list all other elements that are equal to it. 517 518@node Repetition 519@section Repeating Minibuffer Commands 520@cindex command history 521@cindex history of commands 522 523 Every command that uses the minibuffer once is recorded on a special 524history list, the @dfn{command history}, together with the values of 525its arguments, so that you can repeat the entire command. In 526particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} 527uses the minibuffer to read the command name. 528 529@findex list-command-history 530@table @kbd 531@item C-x @key{ESC} @key{ESC} 532Re-execute a recent minibuffer command from the command history 533 (@code{repeat-complex-command}). 534@item M-x list-command-history 535Display the entire command history, showing all the commands 536@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. 537@end table 538 539@kindex C-x ESC ESC 540@findex repeat-complex-command 541 @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command 542that used the minibuffer. With no argument, it repeats the last such 543command. A numeric argument specifies which command to repeat; 1 544means the last one, 2 the previous, and so on. 545 546 @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command 547into a Lisp expression and then entering a minibuffer initialized with 548the text for that expression. Even if you don't understand Lisp 549syntax, it will probably be obvious which command is displayed for 550repetition. If you type just @key{RET}, that repeats the command 551unchanged. You can also change the command by editing the Lisp 552expression before you execute it. The repeated command is added to 553the front of the command history unless it is identical to the most 554recently item. 555 556 Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can 557use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, 558@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list 559of saved entire commands. After finding the desired previous command, 560you can edit its expression as usual and then repeat it by typing 561@key{RET}. 562 563@vindex isearch-resume-in-command-history 564 Incremental search does not, strictly speaking, use the minibuffer. 565Therefore, although it behaves like a complex command, it normally 566does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. 567You can make incremental search commands appear in the history by 568setting @code{isearch-resume-in-command-history} to a non-@code{nil} 569value. @xref{Incremental Search}. 570 571@vindex command-history 572 The list of previous minibuffer-using commands is stored as a Lisp 573list in the variable @code{command-history}. Each element is a Lisp 574expression which describes one command and its arguments. Lisp programs 575can re-execute a command by calling @code{eval} with the 576@code{command-history} element. 577 578@ignore 579 arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f 580@end ignore 581