The minibuffer is where Emacs commands read complicated arguments, such as file names, buffer names, Emacs command names, or Lisp expressions. We call it the “minibuffer” because it’s a special-purpose buffer with a small amount of screen space. 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, with a
cursor. The minibuffer starts with a prompt, usually ending
with a colon. The prompt states what kind of input is expected, and
how it will be used. The prompt is highlighted using the
minibuffer-prompt face (see Text Faces).
The simplest way to enter a minibuffer argument is to type the text, then RET to submit the argument and exit the minibuffer. Alternatively, you can type C-g to exit the minibuffer by canceling the command asking for the argument (see Quitting and Aborting).
Sometimes, the prompt shows a default argument, inside
parentheses before the colon. This default will be used as the
argument if you just type RET. For example, commands that read
buffer names usually show a buffer name as the default; you can type
RET to operate on that default buffer. You can customize how
the default argument is shown with the user option
minibuffer-default-prompt-format.
If you enable Minibuffer Electric Default mode, a global minor mode, Emacs hides the default argument as soon as you modify the contents of the minibuffer (since typing RET would no longer submit that default). If you ever bring back the original minibuffer text, the prompt again shows the default. To enable this minor mode, type M-x minibuffer-electric-default-mode.
Since the minibuffer appears in the echo area, it can conflict with other uses of the echo area. If an error message or an informative message is emitted while the minibuffer is active, the message is displayed in brackets after the minibuffer text for a few seconds, or until you type something; then the message disappears. While the minibuffer is in use, Emacs does not echo keystrokes.
While using the minibuffer, you can switch to a different frame,
perhaps to note text you need to enter (see Frame Commands). By
default, the active minibuffer moves to this new frame. If you set
the user option minibuffer-follows-selected-frame to
nil, then the minibuffer stays in the frame where you opened
it, and you must switch back to that frame in order to complete (or
abort) the current command. If you set that option to a value which
is neither nil nor t, the minibuffer moves frame only
after a recursive minibuffer has been opened in the current command
(see (elisp)Recursive Mini). This option is mainly to retain
(approximately) the behavior prior to Emacs 28.1. Note that the
effect of the command, when you finally finish using the minibuffer,
always takes place in the frame where you first opened it. The sole
exception is that when that frame no longer exists, the action takes
place in the currently selected frame.
Commands such as C-x C-f (find-file) use the minibuffer
to read a file name argument (see Files). When the
minibuffer is used to read a file name, it typically starts out with
some initial text ending in a slash. This is the default
directory. For example, it may start out like this:
Find file: /u2/emacs/src/
Here, ‘Find file: ’ is the prompt and ‘/u2/emacs/src/’ is the default directory. If you now type buffer.c as input, that specifies the file /u2/emacs/src/buffer.c. See File Names, for information about the default directory.
Alternative defaults for the file name you may want are available by typing M-n, see Minibuffer History.
You can specify a file in the parent directory with ..: /a/b/../foo.el is equivalent to /a/foo.el. Alternatively, you can use M-DEL to kill directory names backwards (see Words).
To specify a file in a completely different directory, you can kill the entire default with C-a C-k (see Editing in the Minibuffer). Alternatively, you can ignore the default, and enter an absolute file name starting with a slash or a tilde after the default directory. For example, you can specify /etc/termcap as follows:
Find file: /u2/emacs/src//etc/termcap
A double slash causes Emacs to ignore everything before the second slash in the pair. In the example above, /u2/emacs/src/ is ignored, so the argument you supplied is /etc/termcap. The ignored part of the file name is dimmed if the terminal allows it. (To disable this dimming, turn off File Name Shadow mode with the command M-x file-name-shadow-mode.)
When completing remote file names (see Remote Files), a double slash behaves slightly differently: it causes Emacs to ignore only the file-name part, leaving the rest (method, host and username, etc.) intact. Typing three slashes in a row ignores everything in remote file names. See File name completion in The Tramp Manual.
Emacs interprets ~/ as your home directory. Thus, ~/foo/bar.txt specifies a file named bar.txt, inside a directory named foo, which is in turn located in your home directory. In addition, ~user-id/ means the home directory of a user whose login name is user-id. Any leading directory name in front of the ~ is ignored: thus, /u2/emacs/~/foo/bar.txt is equivalent to ~/foo/bar.txt.
On MS-Windows and MS-DOS systems, where a user doesn’t always have a home directory, Emacs uses several alternatives. For MS-Windows, see HOME and Startup Directories on MS-Windows; for MS-DOS, see File Names on MS-DOS. On these systems, the ~user-id/ construct is supported only for the current user, i.e., only if user-id is the current user’s login name.
To prevent Emacs from inserting the default directory when reading
file names, change the variable insert-default-directory to
nil. In that case, the minibuffer starts out empty.
Nonetheless, relative file name arguments are still interpreted based
on the same default directory.
You can also enter remote file names in the minibuffer. See Remote Files.
The minibuffer is an Emacs buffer, albeit a peculiar one, and the usual Emacs commands are available for editing the argument text. (The prompt, however, is read-only, and cannot be changed.)
Since RET in the minibuffer submits the argument, you can’t
use it to insert a newline. You can do that with C-q C-j, which
inserts a C-j control character, which is formally equivalent to
a newline character (see Inserting Text). Alternatively, you can
use the C-o (open-line) command (see Blank Lines).
Inside a minibuffer, the keys TAB, SPC, and ? are often bound to completion commands, which allow you to easily fill in the desired text without typing all of it. See Completion. As with RET, you can use C-q to insert a TAB, SPC, or ‘?’ character. If you want to make SPC and ? insert normally instead of starting completion, you can put the following in your init file:
(keymap-unset minibuffer-local-completion-map "SPC") (keymap-unset minibuffer-local-completion-map "?")
For convenience, C-a (move-beginning-of-line) in a
minibuffer moves point to the beginning of the argument text, not the
beginning of the prompt. For example, this allows you to erase the
entire argument with C-a C-k.
When the minibuffer is active, the echo area is treated much like an ordinary Emacs window. For instance, you can switch to another window (with C-x o), edit text there, then return to the minibuffer window to finish the argument. You can even kill text in another window, return to the minibuffer window, and yank the text into the argument. There are some restrictions on the minibuffer window, however: for instance, you cannot split it. See Multiple Windows.
Normally, the minibuffer window occupies a single screen line.
However, if you add two or more lines’ worth of text into the
minibuffer, it expands automatically to accommodate the text. The
variable resize-mini-windows controls the resizing of the
minibuffer. The default value is grow-only, which means the
behavior we have just described. If the value is t, the
minibuffer window will also shrink automatically if you remove some
lines of text from the minibuffer, down to a minimum of one screen
line. If the value is nil, the minibuffer window never changes
size automatically, but you can use the usual window-resizing commands
on it (see Multiple Windows).
The variable max-mini-window-height controls the maximum
height for resizing the minibuffer window. A floating-point number
specifies a fraction of the frame’s height; an integer specifies the
maximum number of lines; nil means do not resize the minibuffer
window automatically. The default value is 0.25.
The C-M-v command in the minibuffer scrolls the help text from commands that display help text of any sort in another window. You can also scroll the help text with M-PageUp and M-PageDown (or, equivalently, M-prior and M-next). This is especially useful with long lists of possible completions. See Using Other Windows.
Emacs normally disallows most commands that use the minibuffer while
the minibuffer is active. To allow such commands in the minibuffer,
set the variable enable-recursive-minibuffers to t.
You might need also to enable minibuffer-depth-indicate-mode
to show the current recursion depth in the minibuffer prompt
on recursive use of the minibuffer.
When active, the minibuffer is usually in minibuffer-mode.
This is an internal Emacs mode without any special features.
When not active, the minibuffer is in minibuffer-inactive-mode,
and clicking mouse-1 there shows the *Messages* buffer.
If you use a dedicated frame for minibuffers, Emacs also recognizes
certain keys there, for example, n to make a new frame.
You can often use a feature called completion to help enter arguments. This means that after you type part of the argument, Emacs can fill in the rest, or some of it, based on what was typed so far.
When completion is available, certain keys (usually TAB, RET, and SPC) are rebound in the minibuffer to special completion commands (see Completion Commands). These commands attempt to complete the text in the minibuffer, based on a set of completion alternatives provided by the command that requested the argument. You can usually type ? to have Emacs pop up a buffer (named ‘*Completions*’) displaying the relevant completion alternatives. As described in more detail below, you can navigate this buffer and choose the desired completion from it.
Although completion is usually done in the minibuffer, the feature is sometimes available in ordinary buffers too. See Completion for Symbol Names.
A simple example may help here. M-x uses the minibuffer to
read the name of a command, so completion works by matching the
minibuffer text against the names of existing Emacs commands. Suppose
you wish to run the command auto-fill-mode. You can do that by
typing M-x auto-fill-mode RET, but it is easier to use
completion.
If you type M-x a u TAB, the TAB looks for
completion alternatives (in this case, command names) that start with
‘au’. There are several, including auto-fill-mode and
autoconf-mode, but they all begin with auto, so the
‘au’ in the minibuffer completes to ‘auto’. (More commands
may be defined in your Emacs session. For example, if a command
called authorize-me was defined, Emacs could only complete
as far as ‘aut’.)
If you type TAB again immediately, it cannot determine the next character; it could be ‘-’, ‘a’, or ‘c’. So it does not add any characters; instead, TAB displays a list of all possible completions in another window.
Next, type -f. The minibuffer now contains ‘auto-f’, and
the only command name that starts with this is auto-fill-mode.
If you now type TAB, completion fills in the rest of the
argument ‘auto-fill-mode’ into the minibuffer.
Hence, typing just a u TAB - f TAB allows you to enter ‘auto-fill-mode’.
TAB also works while point is not at the end of the minibuffer. In that case, it will fill in text both at point and at the end of the minibuffer. If you type M-x autocm, then press C-b to move point before the ‘m’, you can type TAB to insert the text ‘onf-’ at point and ‘ode’ at the end of the minibuffer, so that the minibuffer contains ‘autoconf-mode’.
Here is a list of the completion commands defined in the minibuffer or the completions buffer when completion is available.
Complete the text in the minibuffer as much as possible; if unable to complete, display a list of possible completions.
Complete up to one word from the minibuffer text before point.
Complete the text in the minibuffer using minibuffer history.
Complete the text in the minibuffer using minibuffer defaults.
Submit the text in the minibuffer as the argument, possibly completing first. See Completion Exit.
Display a list of completions and a few useful key bindings
(minibuffer-completion-help).
Navigate through the list of completions.
While in the minibuffer, select the window showing the completion list.
In the completions buffer, choose the completion at point.
In the completions buffer, choose the completion at mouse click.
In the completions buffer, move to the following completion candidate.
In the completions buffer, move to the previous completion candidate.
In the completions buffer, navigate column-wise through the completion list.
In the completions buffer, navigate line-wise through the completion list.
Quit the completions window and switch to the minibuffer window.
Kill the completions buffer and delete the window showing it.
TAB (minibuffer-complete) is the most fundamental
completion command. It searches for all possible completions that
match the existing minibuffer text, and attempts to complete as much
as it can. See How Completion Alternatives Are Chosen, for how completion alternatives
are chosen.
SPC (minibuffer-complete-word) completes like
TAB, but only up to 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 only inserts ‘ill-’,
giving ‘auto-fill-’. Another SPC at this point completes
all the way to ‘auto-fill-mode’. This command is not available for
arguments that often include spaces, such as file names.
If TAB or SPC is unable to complete, it displays in
another window a list of matching completion alternatives (if there are
any) and a few useful commands to select a completion candidate. You
can display the same completion list and help with ?
(minibuffer-completion-help). The following commands can be used
with the completion list:
While in the minibuffer or in the completion list buffer,
M-DOWN (minibuffer-next-completion) and
M-UP (minibuffer-previous-completion) navigate
through the completions displayed in the completions buffer. These
commands are sensitive to the completion list format: they move point
column-wise when the value of completions-format is
horizontal and line-wise when its value is vertical
(see Completion Options). If you set
minibuffer-completion-auto-choose to non-nil, using these
commands also inserts the current completion candidate into the
minibuffer. You can use M-RET
(minibuffer-choose-completion) or RET
(minibuffer-complete-and-exit) to choose the selected completion
candidate. By default, these commands exit the minibuffer, but with a
prefix argument (that is, C-u M-RET or C-u RET)
they insert the currently selected candidate into the minibuffer without
exiting it.
Typing M-v, while in the minibuffer, selects the window showing
the completion list (switch-to-completions). This paves the
way for using the commands below. PageUp, prior and
M-g M-c do the same. You can also select the window in other
ways (see Multiple Windows).
While in the completion list buffer, RET chooses the completion
candidate at point (choose-completion) and mouse-1 and
mouse-2 choose the completion at mouse click. With a prefix
argument, C-u RET inserts the completion at point into the
minibuffer, but doesn’t exit the minibuffer—thus, you can change your
mind and choose another candidate.
While in the completion list buffer, you can use TAB or
n to move point to the following completion candidate
(next-completion) and S-TAB or p to move point
to the previous completion alternative (previous-completion).
Like M-DOWN and M-UP, these commands are also
sensitive to the completion list format.
In contrast, RIGHT (next-column-completion) and
LEFT (previous-column-completion) always move point
column-wise, regardless of the completion list format. Likewise,
DOWN (next-line-completion) and UP
(previous-line-completion) always move point line-wise.
All of these movement commands (and also M-DOWN and M-UP) accept a numeric prefix argument n, which makes point move to the nth following or preceding completion candidate.
You can also complete using the history of minibuffer inputs for the
command which prompted you. C-x UP
(minibuffer-complete-history) works like TAB, but
completes using minibuffer history instead of the usual completion
candidates. A similar command C-x DOWN
(minibuffer-complete-defaults) completes using the default input
items provided by the prompting command.
Finally, q quits the window showing it and selects the window
showing the minibuffer (quit-window), and z kills the
completion buffer and delete the window showing it
(kill-current-buffer).
If the variable minibuffer-visible-completions is customized to
the value t, it changes the commands bound to the arrow keys:
instead of moving in the minibuffer, they move between completion
candidates, like meta-arrow keys do by default (but note that, just as
when the window showing the completion list is selected, here too,
RIGHT and LEFT only move point column-wise and
DOWN and UP only move point line-wise,
regardless of the completion list format). Similarly, RET
selects the current candidate, like M-RET does normally.
C-g hides the completion window, but leaves the minibuffer
active, so you can continue typing at the prompt. If the value of this
variable is up-down, only the UP and DOWN
arrow keys move point between completion candidates, while
RIGHT and LEFT move point in the minibuffer
window.
When a command reads an argument using the minibuffer with
completion, it also controls what happens when you type RET
(minibuffer-complete-and-exit) to submit the argument. There
are four types of behavior:
An example of a command that uses this behavior is M-x, since it is meaningless for it to accept a non-existent command name.
Cautious completion is used for reading file names for files that must already exist, for example.
You can tweak the confirmation behavior by customizing the variable
confirm-nonexistent-file-or-buffer. The default value,
after-completion, gives the behavior we have just described.
If you change it to nil, Emacs does not ask for confirmation,
falling back on permissive completion. If you change it to any other
non-nil value, Emacs asks for confirmation whether or not the
preceding command was TAB.
This behavior is used by most commands that read file names, like C-x C-f, and commands that read buffer names, like C-x b.
Completion commands work by narrowing a large list of possible completion alternatives to a smaller subset that matches what you have typed in the minibuffer. In Completion Example, we gave a simple example of such matching. The procedure of determining what constitutes a match is quite intricate. Emacs attempts to offer plausible completions under most circumstances.
Emacs performs completion using one or more completion styles—sets of criteria for matching minibuffer text to completion alternatives. During completion, Emacs tries each completion style in turn. If a style yields one or more matches, that is used as the list of completion alternatives. If a style produces no matches, Emacs falls back on the next style.
The list variable completion-styles specifies the completion
styles to use. Each list element is either the name of a completion
style (a Lisp symbol) or a list starting with the name of a completion
style followed by let-style list of bindings which will be in
effect for that completion style. Multiple elements of
completion-styles can name the same completion style with
different variable bindings.
The available style symbols are stored in the variable
completion-styles-alist (see Completion Variables in The Emacs Lisp Reference Manual). The default completion styles are
(in order):
basic ¶A matching completion alternative must have the same beginning as the text in the minibuffer before point. Furthermore, if there is any text in the minibuffer after point, the rest of the completion alternative must contain that text as a substring.
partial-completion ¶This aggressive completion style divides the minibuffer text into words separated by hyphens or spaces, and completes each word separately. (For example, when completing command names, ‘em-l-m’ completes to ‘emacs-lisp-mode’.)
Furthermore, a ‘*’ in the minibuffer text is treated as a wildcard—it matches any string of characters at the corresponding position in the completion alternative.
If completion-pcm-leading-wildcard is set to t, this style
always acts as if a wildcard is present at the start of each word
in the minibuffer text, similar to the substring style. For
example, ‘l-ode’ will complete to ‘emacs-lisp-mode’.
emacs22 ¶This completion style is similar to basic, except that it
ignores the text in the minibuffer after point. It is so-named
because it corresponds to the completion behavior in Emacs 22.
The following additional completion styles are also defined, and you
can add them to completion-styles if you wish
(see Customization):
substring ¶A matching completion alternative must contain the text in the minibuffer before point, and the text in the minibuffer after point, as substrings (in that same order).
Thus, if the text in the minibuffer is ‘foobar’, with point between ‘foo’ and ‘bar’, that matches ‘afoobbarc’, where a, b, and c can be any string including the empty string.
flex ¶This aggressive completion style, also known as flx or
fuzzy or scatter completion, attempts to complete using
in-order substrings. For example, it can consider ‘foo’ to match
‘frodo’ or ‘fbarbazoo’.
initials ¶This very aggressive completion style attempts to complete acronyms and initialisms. For example, when completing command names, it matches ‘lch’ to ‘list-command-history’.
There is also a very simple completion style called emacs21.
In this style, if the text in the minibuffer is ‘foobar’,
only matches starting with ‘foobar’ are considered.
You can use different completion styles in different situations,
by setting the variable completion-category-overrides.
For example, the default setting says to use only basic
and substring completion for buffer names.
Case is significant when completing case-sensitive arguments, such as command names. For example, when completing command names, ‘AU’ does not complete to ‘auto-fill-mode’. Case differences are ignored when completing arguments in which case does not matter.
When completing file names, case differences are ignored if the
variable read-file-name-completion-ignore-case is
non-nil. The default value is nil on systems that have
case-sensitive file-names, such as GNU/Linux; it is non-nil on
systems that have case-insensitive file-names, such as Microsoft
Windows. When completing buffer names, case differences are ignored
if the variable read-buffer-completion-ignore-case is
non-nil; the default is nil.
When completing file names, Emacs usually omits certain alternatives
that are considered unlikely to be chosen, as determined by the list
variable completion-ignored-extensions. Each element in the
list should be a string; any file name ending in such a string is
ignored as a completion alternative. Any element ending in a slash
(/) represents a subdirectory name. The standard value of
completion-ignored-extensions has several elements including
".o", ".elc", and "~". For example, if a
directory contains ‘foo.c’ and ‘foo.elc’, ‘foo’
completes to ‘foo.c’. However, if all possible
completions end in otherwise-ignored strings, they are not ignored: in the
previous example, ‘foo.e’ completes to ‘foo.elc’. Emacs
disregards completion-ignored-extensions when showing
completion alternatives in the completion list.
Shell completion is an extended version of filename completion, see Shell Mode Options.
If completion-auto-help is set to nil, the completion
commands never display the completion list buffer; you must type
? to display the list. If the value is lazy, Emacs only
shows the completion list buffer on the second attempt to complete.
In other words, if there is nothing to complete, the first TAB
echoes ‘Next char not unique’; the second TAB shows the
completion list buffer. If the value is always, the completion
list buffer is always shown when completion is attempted.
The display of the completion list buffer after it is shown for the
first time is also controlled by completion-auto-help. If the
value is t or lazy, the window showing the completions
pops down when Emacs is able to complete (and may pop up again if
Emacs is again unable to complete after you type some more text); if
the value is always, the window pops down only when you exit
the completion. The value visible is a hybrid: it behaves like
t when it decides whether to pop up the window showing the
completion list buffer, and like always when it decides whether
to pop it down.
Emacs can optionally select the window showing the completions when
it shows that window. To enable this behavior, customize the user
option completion-auto-select to t, which changes the
behavior of TAB when Emacs pops up the completions: pressing
TAB will switch to the completion list buffer, and you can
then move to a candidate by cursor motion commands and select it with
RET. If the value of completion-auto-select is
second-tab, then the first TAB will pop up the
completions list buffer, and the second one will switch to it.
If completion-cycle-threshold is non-nil, completion
commands can cycle through completion alternatives. Normally, if
there is more than one completion alternative for the text in the
minibuffer, a completion command completes up to the longest common
substring. If you change completion-cycle-threshold to
t, the completion command instead completes to the first of
those completion alternatives; each subsequent invocation of the
completion command replaces that with the next completion alternative,
in a cyclic manner. If you give completion-cycle-threshold a
numeric value n, completion commands switch to this cycling
behavior only when there are n or fewer alternatives.
The user option completions-sort controls the order in which
the completions are sorted in the ‘*Completions*’ buffer. With the
default value alphabetical, the completions are displayed in
alphabetical order. The value nil disables sorting; the value
historical sorts alphabetically first, and then rearranges
according to the order of the candidates in the minibuffer history. The
value can also be a function, which will be called with the list of
completions, and should return the list in the desired order.
By default, the ‘*Completions*’ buffer lists the sorted
completions horizontally (that is, from left to right across the columns
and continuing to the next line below), using as many columns as will
fit in the window-width. You can change this by customizing the user
option completions-format. If its value is vertical, the
‘*Completions*’ buffer lists the sorted completions vertically
(that is, within each column and continuing with the next column to the
left), and with the value one-column, all completions appear in a
single column.5
When point is on the last completion candidate, typing a key that
moves point to the next candidate (according to the sorting order of
current format) “wraps around” by default, that is, moves point to the
first candidate in the completions buffer. Likewise, when point is on
the first candidate, typing a key to move to the previous candidate puts
point on the last candidate in the buffer. You can suppress this
wrapping around by customizing the user option
completion-auto-wrap to nil; then typing TAB
or n on the last candidate, or typing S-TAB or p
on the first candidate, does not move point.
With the arrow keys, the wrapping behavior depends on the completions format in use. In the horizontal format, you can use RIGHT and LEFT, and in the vertical format DOWN and UP, exactly like the format-sensitive keys for moving between completion candidates in the sorting order, and with the same wrapping behavior. In contrast, in the horizontal format DOWN and UP move—and wrap, if wrapping is enabled—only within the current column of completions, and in the vertical format RIGHT and LEFT move (and wrap, if enabled) only within the current line of completions.6
When completions-max-height is non-nil, it limits the
size of the completions window. It is specified in lines and include
mode, header line and a bottom divider, if any. For a more complex
control of the Completion window display properties, you can use
display-buffer-alist (see Action Alists for Buffer Display in The Emacs Lisp
Reference Manual).
The variable completions-header-format is a format spec string to
control the informative line shown before the completions list of
candidates. If it contains a ‘%s’ construct, that get replaced
by the number of completions shown in the completion list buffer. To
suppress the display of the heading line, customize this variable to
nil. The string that is the value of this variable can have
text properties to change the visual appearance of the heading line;
some useful properties face or cursor-intangible
(see Properties with Special Meanings in The Emacs Lisp Reference Manual).
When completions-highlight-face names a face, the current
completion candidate, the one that will be selected by typing
RET or clicking the mouse, will be highlighted using that
face. The default value of this variable is
completions-highlight; the value is nil disables this
highlighting. This feature uses the special text property
cursor-face.
Everything you type in the minibuffer is saved in a minibuffer history list so you can easily use it again later. This includes completion candidates (such as file names, buffer names, command names, etc.) and any other kind of minibuffer input. You can use the following commands to quickly fetch an earlier or alternative response into the minibuffer:
Move to the previous item in the minibuffer history, an earlier
argument (previous-history-element).
Move to the next item in the minibuffer history
(next-history-element).
Like M-p and M-n, but move to the previous or next line of
a multi-line item before going to the previous history item
(previous-line-or-history-element and
next-line-or-history-element) .
Move to an earlier item in the minibuffer history that
matches regexp (previous-matching-history-element).
Move to a later item in the minibuffer history that matches
regexp (next-matching-history-element).
While in the minibuffer, M-p (previous-history-element)
moves through the minibuffer history list, one item at a time. Each
M-p fetches an earlier item from the history list into the
minibuffer, replacing its existing contents. Typing M-n
(next-history-element) moves through the minibuffer history
list in the opposite direction, fetching later entries into the
minibuffer.
If you type M-n in the minibuffer when there are no later entries in the minibuffer history (e.g., if you haven’t previously typed M-p), Emacs tries fetching from a list of default arguments: values that you are likely to enter. You can think of this as moving through the future history. Searching forward through minibuffer history (see Searching the Minibuffer) includes the “future history” as well.
The “future history” for file names includes several possible
alternatives you may find useful, such as the file name or the URL at
point in the current buffer. The defaults put into the “future
history” in this case are controlled by the functions mentioned in
the value of the option file-name-at-point-functions. By
default, its value invokes the ffap package (see Finding Files and URLs at Point),
which tries to guess the default file or URL from the text around
point. To disable this guessing, customize the option to a nil
value, then the “future history” of file names will include only the
file, if any, visited by the current buffer, and the default
directory.
The arrow keys UP and DOWN work like M-p and M-n, but if the current history item is longer than a single line, they allow you to move to the previous or next line of the current history item before going to the previous or next history item.
If you edit the text inserted by the M-p or M-n minibuffer history commands, this does not change its entry in the history list. However, the edited argument does go at the end of the history list when you submit it.
You can use M-r (previous-matching-history-element) to
search through older elements in the history list, and M-s
(next-matching-history-element) to search through newer
entries. Each of these commands asks for a regular expression
as an argument, and fetches the first matching entry into the
minibuffer. See Syntax of Regular Expressions, for an explanation of regular
expressions. A numeric prefix argument n means to fetch the
nth matching entry. These commands are unusual, in that they
use the minibuffer to read the regular expression argument, even
though they are invoked from the minibuffer. An upper-case letter in
the regular expression makes the search case-sensitive (see Lax Matching During Searching).
You can also search through the minibuffer history using incremental search (C-s and C-r). See Searching the Minibuffer.
Emacs keeps separate history lists for several different kinds of
arguments. For example, there is a list for file names, used by all
the commands that read file names. Other history lists include buffer
names, command names (used by M-x), and command arguments (used
by commands like query-replace).
The variable history-length specifies the maximum length of a
minibuffer history list; adding a new element deletes the oldest
element if the list gets too long. If the value is t, there is
no maximum length.
The variable history-delete-duplicates specifies whether to
delete duplicates in history. If it is non-nil, adding a new
element deletes from the list all other elements that are equal to it.
The default is nil.
Every command that uses the minibuffer once is recorded on a special history list, the command history, 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.
Re-execute a recent minibuffer command from the command history
(repeat-complex-command).
Display the entire command history, showing all the commands C-x ESC ESC can repeat, most recent first.
C-x ESC ESC re-executes a recent command that used the minibuffer. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; 1 means the last one, 2 the previous, and so on.
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. Even if you don’t know Lisp, it will probably be obvious which command is displayed for repetition. If you type just RET, that repeats the command unchanged. You can also change the command by editing the Lisp expression before you execute it. The executed command is added to the front of the command history unless it is identical to the most recent item.
Once inside the minibuffer for C-x ESC ESC, you can use the usual minibuffer history commands (see Minibuffer History) to move through the history list. After finding the desired previous command, you can edit its expression as usual and then execute it by typing RET.
Incremental search does not, strictly speaking, use the minibuffer.
Therefore, although it behaves like a complex command, it normally
does not appear in the history list for C-x ESC ESC.
You can make incremental search commands appear in the history by
setting isearch-resume-in-command-history to a non-nil
value. See Incremental Search.
The list of previous minibuffer-using commands is stored as a Lisp
list in the variable command-history. Each element is a Lisp
expression that describes one command and its arguments. Lisp programs
can re-execute a command by calling eval with the
command-history element.
Sometimes, you may need to enter a password into Emacs. For instance, when you tell Emacs to visit a file on another machine via a network protocol such as FTP, you often need to supply a password to gain access to the machine (see Remote Files).
Entering a password is similar to using a minibuffer. Emacs displays a prompt in the echo area (such as ‘Password: ’); after you type the required password, press RET to submit it. To prevent others from seeing your password, every character you type is displayed as an asterisk (‘*’) instead of its usual form.
Most of the features and commands associated with the minibuffer cannot be used when entering a password. There is no history or completion, and you cannot change windows or perform any other action with Emacs until you have submitted the password.
While you are typing the password, you may press DEL to delete backwards, removing the last character entered. C-u deletes everything you have typed so far. C-g quits the password prompt (see Quitting and Aborting). C-y inserts the current kill into the password (see Killing and Moving Text). TAB toggles the visibility of the password. You may type either RET or ESC to submit the password. Any other self-inserting character key inserts the associated character into the password, and all other input is ignored.
There is also an icon in the mode line indicating the password visibility. Clicking mouse-1 on it toggles the password visibility as well.
An Emacs command may require you to answer a yes-or-no question during the course of its execution. Such queries come in two main varieties.
For the first type of yes-or-no query, the prompt ends with ‘(y or n)’. You answer the query by typing a single key, either ‘y’ or ‘n’, which immediately exits the minibuffer and delivers the response. For example, if you type C-x C-w (write-file) to save a buffer, and enter the name of an existing file, Emacs issues a prompt like this:
File `foo.el' exists; overwrite? (y or n)
The second type of yes-or-no query is typically employed if giving
the wrong answer would have serious consequences; it thus features a
longer prompt ending with ‘(yes or no)’ (or the value of
yes-or-no-prompt if you’ve customized that). For example, if
you invoke C-x k (kill-buffer) on a file-visiting buffer
with unsaved changes, Emacs activates the minibuffer with a prompt
like this:
Buffer foo.el modified; kill anyway? (yes or no)
To answer, you must type ‘yes’ or ‘no’ into the minibuffer, followed by RET.
With both types of yes-or-no query the minibuffer behaves as described in the previous sections; you can recenter the selected window with C-l, scroll that window (C-v or PageDown scrolls forward, M-v or PageUp scrolls backward), switch to another window with C-x o, use the history commands M-p and M-n, etc. Type C-g to dismiss the query, and quit the minibuffer and the querying command (see Quitting and Aborting).
If a completion candidate is too long for more
than one column to fit in the window, or it there are three or less
candidates, all completions appear in a single column even if the value
of completions-format is horizontal or vertical.
If the
completions buffer contains only single column even in the horizontal or
vertical format, then both the format-sensitive keys and the arrow keys
move point to the next (respectively, previous) candidate, wrapping only
at the last (respectively, first) candidate, if the value of
completion-auto-wrap is non-nil.