The minibuffer is the facility used by Emacs commands to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. You can use the usual Emacs editing commands in the minibuffer to edit the argument text.
When the minibuffer is in use, it appears in the echo area, and the terminal's cursor moves there. The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used. Often this prompt is derived from the name of the command that the argument is for. The prompt normally ends with a colon.
Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt. The default will be used as the argument value if you enter an empty argument (e.g., just type RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.
The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.
Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:
Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This is to inform you which directory the file will be found in if you do not specify a directory.
For example, the minibuffer might start out with these contents:
Find File: /u2/emacs/src/
where Find File: is the prompt. Typing buffer.c specifies the file /u2/emacs/src/buffer.c. To find files in nearby directories, use ..; thus, if you type ../lisp/simple.el, you will get the file named /u2/emacs/lisp/simple.el. Alternatively, you can kill with M-DEL the directory names you don't want (see section Words).
If you don't want any of the default, you can kill it with C-a C-k. But you don't need to kill the default; you can simply ignore it. Insert an absolute file name, one starting with a slash or a tilde, after the default directory. For example, to specify the file /etc/termcap, just insert that name, giving these minibuffer contents:
Find File: /u2/emacs/src//etc/termcap
Two slashes in a row are not normally meaningful in a file name, but they are allowed in GNU Emacs. They mean, ``ignore everything before the second slash in the pair.'' Thus, /u2/emacs/src/ is ignored in the example above, and you get the file /etc/termcap.
If you set
Since RET in the minibuffer is defined to exit the minibuffer, you can't use it to insert a newline in the minibuffer. To do that, type C-o or C-q LFD. (Recall that a newline is really the LFD character.)
The minibuffer has its own window which always has space on the screen but acts as if it were not there when the minibuffer is not in use. When the minibuffer is in use, its window is just like the others; you can switch to another window with C-x o, edit text in other windows and perhaps even visit more files, before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. See section Multiple Windows.
There are some restrictions on the use of the minibuffer window, however. You cannot switch buffers in it---the minibuffer and its window are permanently attached. Also, you cannot split or kill the minibuffer window. But you can make it taller in the normal fashion with C-x ^. If you enable Resize-Minibuffer mode, then the minibuffer window expands vertically as necessary to hold the text that you put in the minibuffer. Use M-x resize-minibuffer-mode to enable or disable this minor mode (see section Minor Modes).
If while in the minibuffer you issue a command that displays help text of any sort in another window, you can use the C-M-v command while in the minibuffer to scroll the help text. This lasts until you exit the minibuffer. This feature is especially useful if a completing minibuffer gives you a list of possible completions. See section Using Other Windows.
Emacs normally disallows most commands that use the minibuffer
while the minibuffer is selected. This rule is to
prevent recursive minibuffers from confusing novice users. If you want to be able to use
such commands in the minibuffer, set the variable
For certain kinds of arguments, you can use completion to enter the argument value. Completion means that you type part of the argument, then Emacs visibly fills in the rest, or as much as can be determined from the part you have typed.
When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.
For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given. This is what makes it possible to type M-x ins SPC b RET instead of M-x insert-buffer RET (for example).
Case is normally significant in completion, because it is significant in most of the names that you can complete (buffer names, file names and command names). Thus, fo does not complete to Foo. Completion does ignore case distinctions for certain arguments in which case does not matter.
A concrete example may help here. If you type M-x au TAB, the TAB
looks for alternatives (in this case, command names)
that start with au. There are only two:
If you type TAB again immediately, there are multiple possibilities for the very next character---it could be s or f---so no more characters are added; instead, TAB displays a list of all possible completions in another window.
If you go on to type f TAB, this TAB sees auto-f.
The only command name starting this way is
SPC completes much like TAB, but never goes beyond the next
hyphen or space. If you have auto-f in the minibuffer
and type SPC, it finds that the completion
is auto-fill-mode, but it stops completing after fill-. This
gives auto-fill-. Another SPC at this point completes all the way to auto-fill-mode.
SPC in the minibuffer when completion is available runs the command
There are three different ways that RET can work in completing minibuffers, depending on how the argument will be used.
The completion commands display a list of all possible completions in a window whenever there is more than one possibility for the very next character. Also, typing ? explicitly requests such a list. If the list of completions is long, you can scroll it with C-M-v (see section Using Other Windows).
When completion is done on file names, certain file
names are usually ignored. The variable
Normally, a completion command that finds the next character
is undetermined automatically displays a list of all
possible completions. If the variable
Icomplete mode presents a constantly-updated display that tells you what completions are available for the text you've entered so far. The command to enable or disable this minor mode is M-x icomplete-mode.
Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument. Special commands load the text of an earlier argument in the minibuffer. They discard the old minibuffer contents, so you can think of them as moving through the history of previous arguments.
The simplest way to reuse the saved arguments in the history list is to move through the history list one element at a time. While in the minibuffer, type M-p (
The previous input that you fetch from the history entirely replaces the contents of the minibuffer. To use it as the argument, exit the minibuffer as usual with RET. You can also edit the text before you reuse it; this does not change the history element that you ``moved'' to, but your new argument does go at the end of the history list in its own right.
There are also commands to search forward or backward through the history. As of this
writing, they search for history elements that match a regular expression that you specify
with the minibuffer. M-r (
All uses of the minibuffer record your input on a
history list, but there are separate history lists for
different kinds of arguments. For example, there is a list
for file names, used by all the commands that read file names. There is a list for arguments of commands like
Every command that uses the minibuffer at least once is recorded on a special history list, together with the values of its arguments, so that you can repeat the entire command. In particular, every use of M-x is recorded there, since M-x uses the minibuffer to read the command name.
C-x ESC ESC is used to re-execute a recent minibuffer-using command. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; one means the last one, and larger numbers specify earlier ones.
C-x ESC ESC works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. If you type just RET, the command is repeated as before. You can also change the command by editing the Lisp expression. Whatever expression you finally submit is what will be executed. The repeated command is added to the front of the command history unless it is identical to the most recently executed command already there.
Once inside the minibuffer for C-x ESC ESC, you can use the minibuffer history commands (M-p, M-n, M-r, M-s; see section Minibuffer History) to move through the history list of saved entire commands. After finding the desired previous command, you can edit its expression as usual and then resubmit it by typing RET as usual.
The list of previous minibuffer-using
commands is stored as a Lisp list in the variable
Email addresses listed on this site may NOT be used for unsolicited commercial email.
Portions (c)Copyright, 1996-2005 by