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