Go to the first, previous, next, last section, table of contents.

The Minibuffer

Emacs commands use the minibuffer 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. To edit the argument in the minibuffer, you can use Emacs editing commands.

When the minibuffer is in use, it appears in the echo area, and the cursor moves there. The beginning of the minibuffer line displays a prompt indicating what kind of input you should supply and how it will be used. The prompt is often derived from the name of the command 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 is used as the argument value if you enter an empty argument (e.g., by just typing 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 to exit the minibuffer. To get out of the minibuffer and cancel the command that it was for, type 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:

If a command gets an error while you are in the minibuffer, this does not cancel the minibuffer. However, the echo area is needed for the error message and therefore the minibuffer itself is hidden for a while. It comes back after a few seconds, or as soon as you type anything.
If you use a command in the minibuffer whose purpose is to print a message in the echo area (for example C-x =) the message is displayed normally, and the minibuffer is hidden for a while. It comes back after a few seconds, or as soon as you type anything.
Echoing of keystrokes does not take place while the minibuffer is in use.

Minibuffers for File Names

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 informs you in which directory the file will be looked for if you do not specify a different one. 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 use M-DEL to kill 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 XEmacs. 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.

Editing in the Minibuffer

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, you must use C-o or C-q LFD to insert a newline into the minibuffer. (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. The minibuffer 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, however, some restrictions on the use of the minibuffer window. You cannot switch buffers in it--the minibuffer and its window are permanently attached. You also cannot split or kill the minibuffer window, but you can make it taller with C-x ^.

If you are in the minibuffer and issue a command that displays help text in another window, that window will be scrolled if you type M-C-v while in the minibuffer until you exit the minibuffer. This feature is helpful if a completing minibuffer gives you a long list of possible completions.

If the variable minibuffer-confirm-incomplete is t, you are asked for confirmation if there is no known completion for the text you typed. For example, if you attempted to visit a non-existent file, the minibuffer might read:

        Find File:chocolate_bar.c [no completions, confirm]

If you press Return again, that confirms the filename. Otherwise, you can continue editing it.

Emacs supports recursive use of the minibuffer. 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.

Completion

When appropriate, the minibuffer provides a completion facility. You type the beginning of an argument and one of the completion keys, and Emacs visibly fills in the rest, depending on what you have already 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 specified by program.

When a completion list is displayed, the completions will highlight as you move the mouse over them. Clicking the middle mouse button on any highlighted completion will "select" it just as if you had typed it in and hit RET.

A Completion Example

Consider the following example. If you type Meta-x au TAB, TAB looks for alternatives (in this case, command names) that start with `au'. There are only two commands: auto-fill-mode and auto-save-mode. They 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 command. 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.

Completion Commands

Here is a list of all the completion commands defined in the minibuffer when completion is available.

TAB: Complete the text in the minibuffer as much as possible
(minibuffer-complete).
SPC: Complete the text in the minibuffer but don't add or fill out more than one word (minibuffer-complete-word).
RET: Submit the text in the minibuffer as the argument, possibly completing first as described below (minibuffer-complete-and-exit).
?: Print a list of all possible completions of the text in the minibuffer (minibuffer-list-completions).
button2: Select the highlighted text under the mouse as a minibuffer response. When the minibuffer is being used to prompt the user for a completion, any valid completions which are visible on the screen will be highlighted when the mouse moves over them. Clicking button2 will select the highlighted completion and exit the minibuffer. (minibuf-select-highlighted-completion).

SPC completes in a way that is similar to TAB, but it 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-'. The result is `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.

Strict completion is used when it is meaningless to give any argument except one of the known alternatives. For example, when C-x k reads the name of a buffer to kill, it is meaningless to give anything but the name of an existing buffer. In strict completion, RET refuses to exit if the text in the minibuffer does not complete to an exact match.
Cautious completion is similar to strict completion, except that RET exits only if the text was an exact match already, not needing completion. If the text is not an exact match, RET does not exit, but it does complete the text. If it completes to an exact match, a second RET will exit. Cautious completion is used for reading file names for files that must already exist.
Permissive completion is used when any string is meaningful, and the list of completion alternatives is just a guide. For example, when C-x C-f reads the name of a file to visit, any file name is allowed, in case you want to create a file. In permissive completion, RET takes the text in the minibuffer exactly as given, without completing it.

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. 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' completes to `foo.c' even though `foo.o' exists as well. If the only possible completions are files that end in "ignored" strings, they are not ignored.

If a completion command finds the next character is undetermined, it 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.

If the variable minibuffer-confirm-incomplete is set to t, then in contexts where completing-read allows answers that are not valid completions, an extra RET must be typed to confirm the response. This is helpful for catching typos.

Repeating Minibuffer Commands

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.

C-x ESC: Re-execute a recent minibuffer command
(repeat-complex-command).
M-p: Within C-x ESC, move to previous recorded command (previous-history-element).
M-n: Within C-x ESC, move to the next (more recent) recorded command (next-history-element).
M-x list-command-history: Display the entire command history, showing all the commands C-x ESC can repeat, most recent first.

C-x ESC is used to re-execute a recent command that used the minibuffer. With no argument, it repeats the last command. A numeric argument specifies which command to repeat; 1 means the last one, and larger numbers specify earlier commands.

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. The expression you finally submit 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 the command will repeat exactly as before.

If you are in the minibuffer for C-x ESC and 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 it with the next later command. After finding the desired previous command, you can edit its expression and then resubmit it by typing RET. Any editing you have done on the command to be repeated is lost if you use M-n or M-p.

M-n and M-p are specially defined within C-x ESC to run the commands previous-history-element and next-history-element.

The list of previous commands using the minibuffer is stored as a Lisp list in the variable command-history. Each element of the list 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 first, previous, next, last section, table of contents.