Go to the previous, next section.
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. The usual Emacs editing commands can be used in the minibuffer to edit the argument.
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 give a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can get out of the minibuffer, canceling the command that it was for, 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
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, the file that you visit will be the one named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with M-DEL the directory names you don't want (see section Words).
You can also type an absolute file name, one starting with a slash or a tilde, ignoring the default directory. For example, to find the file `/etc/termcap', just type the name, giving
Find File: /u2/emacs/src//etc/termcap
Two slashes in a row are not normally meaningful in Unix file names, but they are allowed in GNU Emacs. They mean, "ignore everything before the second slash in the pair." Thus, `/u2/emacs/src/' is ignored, and you get the file `/etc/termcap'.
If you set insert-default-directory to nil, the default directory
is not inserted in the minibuffer. This way, the minibuffer starts out
empty. But the name you type, if relative, is still interpreted with
respect to the same default directory.
The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.
Since RET in the minibuffer is defined to exit the minibuffer, inserting a newline into the minibuffer must be done with C-o or with 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 ^ (see section Deleting and Rearranging Windows).
If while in the minibuffer you issue a command that displays help text of any sort in another window, then that window is identified as the one to scroll if you type C-M-v while in the minibuffer. This lasts until you exit the minibuffer. This feature comes into play if a completing minibuffer gives you a list of possible completions.
Recursive use of the minibuffer is supported by Emacs. However, it is easy to do this by accident (because of autorepeating keyboards, for example) and get confused. Therefore, most Emacs commands that use the minibuffer refuse to operate if the minibuffer window is selected. If the minibuffer is active but you have switched to a different window, recursive use of the minibuffer is allowed--if you know enough to try to do this, you probably will not get confused.
If you set the variable enable-recursive-minibuffers to be
non-nil, recursive use of the minibuffer is always allowed.
When appropriate, the minibuffer provides a completion facility. This means that you type enough of the argument to determine the rest, based on Emacs's knowledge of which arguments make sense, and 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 redefined to complete an abbreviation 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 the minibuffer is being used by Meta-x to read the name of a command, it is given 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 characters of the name that are implied by the ones already present in the minibuffer, and add those characters to the ones you have given.
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' will not complete to `Foo'. When you are completing a name in which case does not matter, case may be ignored for completion's sake if the program said to do so.
A concrete example may help here. If you type Meta-x au TAB,
the TAB looks for alternatives (in this case, command names) that
start with `au'. There are only two: auto-fill-mode and
auto-save-mode. These are the same as far as auto-, so the
`au' in the minibuffer changes to `auto-'.
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; but a list of all possible completions is displayed in another window.
If you go on to type f TAB, this TAB sees
`auto-f'. The only command name starting this way is
auto-fill-mode, so completion inserts the rest of that. You
now have `auto-fill-mode' in the minibuffer after typing just au
TAB f TAB. Note that TAB has this effect because in the
minibuffer it is bound to the function minibuffer-complete when
completion is supposed to be done.
Here is a list of all the completion commands, defined in the minibuffer when completion is available.
minibuffer-complete).
minibuffer-complete-word).
minibuffer-complete-and-exit).
minibuffer-list-completions).
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 runs the function
minibuffer-complete-word when completion is available.
There are three different ways that RET can work in completing minibuffers, depending on how the argument will be used.
Cautious completion is used for reading file names for files that must already exist.
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. The list of completions counts as help text, so C-M-v typed in the minibuffer scrolls the list.
When completion is done on file names, certain file names are usually
ignored. The variable completion-ignored-extensions contains a list
of strings; a file whose name ends in any of those strings is ignored as a
possible completion. The standard value of this variable has several
elements including ".o", ".elc", ".dvi" and "~".
The effect is that, for example, `foo' can complete to `foo.c'
even though `foo.o' exists as well. If the only possible completions
are files that end in "ignored" strings, then they are not ignored.
Normally, a completion command that finds the next character is undetermined
automatically displays a list of all possible completions. If the variable
completion-auto-help is set to nil, this does not happen,
and you must type ? to display the possible completions.
Every command that uses the minibuffer at least once is recorded on a special history list, together with the values of the minibuffer arguments, so that you can repeat the command easily. In particular, every use of Meta-x is recorded, since M-x uses the minibuffer to read the command name.
repeat-complex-command).
previous-complex-command).
next-complex-command).
C-x 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; 1 means the last one, and larger numbers specify earlier ones.
C-x 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.
Even if you don't understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you do not change the text, you can be sure it will repeat exactly as before.
Once inside the minibuffer for C-x ESC, if the command shown to you is not the one you want to repeat, you can move around the list of previous commands using M-n and M-p. M-p replaces the contents of the minibuffer with the next earlier recorded command, and M-n replaces them with the next later command. After finding the desired previous command, you can edit its expression as usual and then resubmit it by typing RET as usual. Any editing you have done on the command to be repeated is lost if you use M-n or M-p.
M-p is more useful than M-n, since more often you will
initially request to repeat the most recent command and then decide to
repeat an older one instead. These keys are specially defined within
C-x ESC to run the commands previous-complex-command and
next-complex-command.
The list of previous minibuffer-using commands is stored as a Lisp list
in the variable command-history. Each element is a Lisp expression
which describes one command and its arguments. Lisp programs can reexecute
a command by feeding the corresponding command-history element to
eval.
Go to the previous, next section.