emacs-gpu/doc/emacs/mini.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2026 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Minibuffer
@chapter The Minibuffer
@cindex minibuffer

  The @dfn{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.

@menu
* Basic Minibuffer::      Basic usage of the minibuffer.
* Minibuffer File::       Entering file names with the minibuffer.
* Minibuffer Edit::       How to edit in the minibuffer.
* Completion::            An abbreviation facility for minibuffer input.
* Minibuffer History::    Reusing recent minibuffer arguments.
* Repetition::            Re-executing commands that used the minibuffer.
* Passwords::             Entering passwords in the echo area.
* Yes or No Prompts::     Replying yes or no in the echo area.
@end menu

@node Basic Minibuffer
@section Using the Minibuffer

@cindex prompt
  When the minibuffer is in use, it appears in the echo area, with a
cursor.  The minibuffer starts with a @dfn{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
@code{minibuffer-prompt} face (@pxref{Faces}).

  The simplest way to enter a minibuffer argument is to type the text,
then @key{RET} to submit the argument and exit the minibuffer.
Alternatively, you can type @kbd{C-g} to exit the minibuffer by
canceling the command asking for the argument (@pxref{Quitting}).

@cindex default argument
@vindex minibuffer-default-prompt-format
  Sometimes, the prompt shows a @dfn{default argument}, inside
parentheses before the colon.  This default will be used as the
argument if you just type @key{RET}.  For example, commands that read
buffer names usually show a buffer name as the default; you can type
@key{RET} to operate on that default buffer.  You can customize how
the default argument is shown with the user option
@code{minibuffer-default-prompt-format}.

@cindex Minibuffer Electric Default mode
@cindex mode, Minibuffer Electric Default
@findex minibuffer-electric-default-mode
@vindex minibuffer-eldef-shorten-default
  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 @key{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
@kbd{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.

@vindex minibuffer-follows-selected-frame
  While using the minibuffer, you can switch to a different frame,
perhaps to note text you need to enter (@pxref{Frame Commands}).  By
default, the active minibuffer moves to this new frame.  If you set
the user option @code{minibuffer-follows-selected-frame} to
@code{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 @code{nil} nor @code{t}, the minibuffer moves frame only
after a recursive minibuffer has been opened in the current command
(@pxref{Recursive Mini,,, elisp}).  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.

@node Minibuffer File
@section Minibuffers for File Names

@cindex default directory
  Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer
to read a file name argument (@pxref{Basic 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 @dfn{default
directory}.  For example, it may start out like this:

@example
Find file: /u2/emacs/src/
@end example

@noindent
Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is
the default directory.  If you now type @kbd{buffer.c} as input, that
specifies the file @file{/u2/emacs/src/buffer.c}.  @xref{File Names},
for information about the default directory.

  Alternative defaults for the file name you may want are available by
typing @kbd{M-n}, see @ref{Minibuffer History}.

  You can specify a file in the parent directory with @file{..}:
@file{/a/b/../foo.el} is equivalent to @file{/a/foo.el}.
Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names
backwards (@pxref{Words}).

  To specify a file in a completely different directory, you can kill
the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}).
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 @file{/etc/termcap} as follows:

@example
Find file: /u2/emacs/src//etc/termcap
@end example

@noindent
@cindex // in file name
@cindex double slash in file name
@cindex slashes repeated in file name
@findex file-name-shadow-mode
A double slash causes Emacs to ignore everything before the
second slash in the pair.  In the example above,
@file{/u2/emacs/src/} is ignored, so the argument you supplied is
@file{/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 @w{@kbd{M-x file-name-shadow-mode}}.)

  When completing remote file names (@pxref{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.  @xref{File name completion,,, tramp, The Tramp Manual}.

@cindex home directory shorthand
  Emacs interprets @file{~/} as your home directory.  Thus,
@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a
directory named @file{foo}, which is in turn located in your home
directory.  In addition, @file{~@var{user-id}/} means the home
directory of a user whose login name is @var{user-id}.  Any leading
directory name in front of the @file{~} is ignored: thus,
@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/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
@ref{Windows HOME}; for MS-DOS, see
@ifnottex
@ref{MS-DOS File Names}.
@end ifnottex
@iftex
@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of
the Emacs Manual}.
@end iftex
On these systems, the @file{~@var{user-id}/} construct is supported
only for the current user, i.e., only if @var{user-id} is the current
user's login name.

@vindex insert-default-directory
  To prevent Emacs from inserting the default directory when reading
file names, change the variable @code{insert-default-directory} to
@code{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.
@xref{Remote Files}.

@node Minibuffer Edit
@section Editing in the Minibuffer

  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 @dfn{read-only}, and cannot be changed.)

  Since @key{RET} in the minibuffer submits the argument, you can't
use it to insert a newline.  You can do that with @kbd{C-q C-j}, which
inserts a @kbd{C-j} control character, which is formally equivalent to
a newline character (@pxref{Inserting Text}).  Alternatively, you can
use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}).

  Inside a minibuffer, the keys @key{TAB}, @key{SPC}, and @kbd{?} are
often bound to @dfn{completion commands}, which allow you to easily
fill in the desired text without typing all of it.  @xref{Completion}.
As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB},
@key{SPC}, or @samp{?} character.  If you want to make @key{SPC} and
@key{?} insert normally instead of starting completion, you can put
the following in your init file:

@lisp
(keymap-unset minibuffer-local-completion-map "SPC")
(keymap-unset minibuffer-local-completion-map "?")
@end lisp

  For convenience, @kbd{C-a} (@code{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 @kbd{C-a C-k}.

@cindex height of minibuffer
@cindex size of minibuffer
@cindex growing minibuffer
@cindex resizing minibuffer
  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 @kbd{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.  @xref{Windows}.

@vindex resize-mini-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 @code{resize-mini-windows} controls the resizing of the
minibuffer.  The default value is @code{grow-only}, which means the
behavior we have just described.  If the value is @code{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 @code{nil}, the minibuffer window never changes
size automatically, but you can use the usual window-resizing commands
on it (@pxref{Windows}).

@vindex max-mini-window-height
  The variable @code{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; @code{nil} means do not resize the minibuffer
window automatically.  The default value is 0.25.

  The @kbd{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 @kbd{M-@key{PageUp}} and
@kbd{M-@key{PageDown}} (or, equivalently, @kbd{M-@key{prior}} and
@kbd{M-@key{next}}).  This is especially useful with long lists of
possible completions.  @xref{Other Window}.

@vindex enable-recursive-minibuffers
@findex minibuffer-depth-indicate-mode
  Emacs normally disallows most commands that use the minibuffer while
the minibuffer is active.  To allow such commands in the minibuffer,
set the variable @code{enable-recursive-minibuffers} to @code{t}.
You might need also to enable @code{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 @code{minibuffer-mode}.
This is an internal Emacs mode without any special features.

@findex minibuffer-inactive-mode
  When not active, the minibuffer is in @code{minibuffer-inactive-mode},
and clicking @kbd{mouse-1} there shows the @file{*Messages*} buffer.
If you use a dedicated frame for minibuffers, Emacs also recognizes
certain keys there, for example, @kbd{n} to make a new frame.

@node Completion
@section Completion
@c This node is referenced in the tutorial.  When renaming or deleting
@c it, the tutorial needs to be adjusted.
@cindex completion

  You can often use a feature called @dfn{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.

@cindex completion alternative
  When completion is available, certain keys (usually @key{TAB},
@key{RET}, and @key{SPC}) are rebound in the minibuffer to special
completion commands (@pxref{Completion Commands}).  These commands
attempt to complete the text in the minibuffer, based on a set of
@dfn{completion alternatives} provided by the command that requested the
argument.  You can usually type @kbd{?} to have Emacs pop up a buffer
(named @samp{*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.  @xref{Symbol
Completion}.

@menu
* Completion Example::       Examples of using completion.
* Completion Commands::      A list of completion commands.
* Completion Exit::          Completion and minibuffer text submission.
* Completion Styles::        How completion matches are chosen.
* Completion Options::       Options for completion.
@end menu

@node Completion Example
@subsection Completion Example

@kindex TAB @r{(completion example)}
  A simple example may help here.  @kbd{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 @code{auto-fill-mode}.  You can do that by
typing @kbd{M-x auto-fill-mode @key{RET}}, but it is easier to use
completion.

  If you type @kbd{M-x a u @key{TAB}}, the @key{TAB} looks for
completion alternatives (in this case, command names) that start with
@samp{au}.  There are several, including @code{auto-fill-mode} and
@code{autoconf-mode}, but they all begin with @code{auto}, so the
@samp{au} in the minibuffer completes to @samp{auto}.  (More commands
may be defined in your Emacs session.  For example, if a command
called @code{authorize-me} was defined, Emacs could only complete
as far as @samp{aut}.)

  If you type @kbd{@key{TAB}} again immediately, it cannot determine
the next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So
it does not add any characters; instead, @key{TAB} displays a list of
all possible completions in another window.

  Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
the only command name that starts with this is @code{auto-fill-mode}.
If you now type @kbd{@key{TAB}}, completion fills in the rest of the
argument @samp{auto-fill-mode} into the minibuffer.

  Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to
enter @samp{auto-fill-mode}.

  @key{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 @kbd{M-x autocm}, then press
@kbd{C-b} to move point before the @samp{m}, you can type
@kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
at the end of the minibuffer, so that the minibuffer contains
@samp{autoconf-mode}.

@node Completion Commands
@subsection Completion Commands

  Here is a list of the completion commands defined in the minibuffer or
the completions buffer when completion is available.

@table @kbd
@item @key{TAB}
Complete the text in the minibuffer as much as possible; if unable to
complete, display a list of possible completions.
@item @key{SPC}
Complete up to one word from the minibuffer text before point.
@item C-x @key{UP}
Complete the text in the minibuffer using minibuffer history.
@item C-x @key{DOWN}
Complete the text in the minibuffer using minibuffer defaults.
@item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing
first.  @xref{Completion Exit}.
@item ?
Display a list of completions and a few useful key bindings
(@code{minibuffer-completion-help}).
@item M-@key{DOWN}
@itemx M-@key{UP}
Navigate through the list of completions.
@item M-v
@itemx M-g M-c
@itemx @key{PageUp}
@itemx @key{prior}
While in the minibuffer, select the window showing the completion list.
@item @key{RET}
In the completions buffer, choose the completion at point.
@item mouse-1
@itemx mouse-2
In the completions buffer, choose the completion at mouse click.
@item @key{TAB}
@itemx n
In the completions buffer, move to the following completion candidate.
@item S-@key{TAB}
@itemx p
In the completions buffer, move to the previous completion candidate.
@item @key{RIGHT}
@itemx @key{LEFT}
In the completions buffer, navigate column-wise through the completion list.
@item @key{DOWN}
@itemx @key{UP}
In the completions buffer, navigate line-wise through the completion list.
@item q
Quit the completions window and switch to the minibuffer window.
@item z
Kill the completions buffer and delete the window showing it.
@end table

@kindex TAB @r{(completion)}
@findex minibuffer-complete
  @key{TAB} (@code{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.  @xref{Completion Styles}, for how completion alternatives
are chosen.

@kindex SPC @r{(completion)}
@findex minibuffer-complete-word
  @key{SPC} (@code{minibuffer-complete-word}) completes like
@key{TAB}, but only up to the next hyphen or space.  If you have
@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the
completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-},
giving @samp{auto-fill-}.  Another @key{SPC} at this point completes
all the way to @samp{auto-fill-mode}.  This command is not available for
arguments that often include spaces, such as file names.

@kindex ? @r{(completion)}
@cindex completion list
  If @key{TAB} or @key{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 @kbd{?}
(@code{minibuffer-completion-help}).  The following commands can be used
with the completion list:

@vindex minibuffer-completion-auto-choose
@kindex M-DOWN
@kindex M-UP
@kindex M-RET
@findex minibuffer-next-completion
@findex minibuffer-previous-completion
@findex minibuffer-choose-completion
@findex minibuffer-complete-and-exit
While in the minibuffer or in the completion list buffer,
@kbd{M-@key{DOWN}} (@code{minibuffer-next-completion}) and
@kbd{M-@key{UP}} (@code{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 @code{completions-format} is
@code{horizontal} and line-wise when its value is @code{vertical}
(@pxref{Completion Options}).  If you set
@code{minibuffer-completion-auto-choose} to non-@code{nil}, using these
commands also inserts the current completion candidate into the
minibuffer.  You can use @kbd{M-@key{RET}}
(@code{minibuffer-choose-completion}) or @kbd{@key{RET}}
(@code{minibuffer-complete-and-exit}) to choose the selected completion
candidate.  By default, these commands exit the minibuffer, but with a
prefix argument (that is, @kbd{C-u M-@key{RET}} or @kbd{C-u @key{RET}})
they insert the currently selected candidate into the minibuffer without
exiting it.

@findex switch-to-completions
Typing @kbd{M-v}, while in the minibuffer, selects the window showing
the completion list (@code{switch-to-completions}).  This paves the
way for using the commands below.  @key{PageUp}, @key{prior} and
@kbd{M-g M-c} do the same.  You can also select the window in other
ways (@pxref{Windows}).

@findex choose-completion
While in the completion list buffer, @kbd{@key{RET}} chooses the completion
candidate at point (@code{choose-completion}) and @kbd{mouse-1} and
@kbd{mouse-2} choose the completion at mouse click.  With a prefix
argument, @kbd{C-u @key{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.

@findex next-completion
@findex previous-completion
While in the completion list buffer, you can use @kbd{@key{TAB}} or
@kbd{n} to move point to the following completion candidate
(@code{next-completion}) and @kbd{S-@key{TAB}} or @kbd{p} to move point
to the previous completion alternative (@code{previous-completion}).
Like @kbd{M-@key{DOWN}} and @kbd{M-@key{UP}}, these commands are also
sensitive to the completion list format.

@findex next-column-completion
@findex next-line-completion
@findex previous-column-completion
@findex previous-line-completion
In contrast, @kbd{@key{RIGHT}} (@code{next-column-completion}) and
@kbd{@key{LEFT}} (@code{previous-column-completion}) always move point
column-wise, regardless of the completion list format.  Likewise,
@kbd{@key{DOWN}} (@code{next-line-completion}) and @kbd{@key{UP}}
(@code{previous-line-completion}) always move point line-wise.

  All of these movement commands (and also @kbd{M-@key{DOWN}} and
@kbd{M-@key{UP}}) accept a numeric prefix argument @var{n}, which makes
point move to the @var{n}th following or preceding completion candidate.

@findex minibuffer-complete-history
@findex minibuffer-complete-defaults
@kindex C-x UP @r{(completion)}
@kindex C-x DOWN @r{(completion)}
You can also complete using the history of minibuffer inputs for the
command which prompted you.  @kbd{C-x @key{UP}}
(@code{minibuffer-complete-history}) works like @kbd{@key{TAB}}, but
completes using minibuffer history instead of the usual completion
candidates.  A similar command @kbd{C-x @key{DOWN}}
(@code{minibuffer-complete-defaults}) completes using the default input
items provided by the prompting command.

@findex quit-window
@findex kill-current-buffer
Finally, @kbd{q} quits the window showing it and selects the window
showing the minibuffer (@code{quit-window}), and @kbd{z} kills the
completion buffer and delete the window showing it
(@code{kill-current-buffer}).

@vindex minibuffer-visible-completions
  If the variable @code{minibuffer-visible-completions} is customized to
the value @code{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,
@kbd{@key{RIGHT}} and @kbd{@key{LEFT}} only move point column-wise and
@kbd{@key{DOWN}} and @kbd{@key{UP}} only move point line-wise,
regardless of the completion list format).  Similarly, @kbd{@key{RET}}
selects the current candidate, like @kbd{M-@key{RET}} does normally.
@code{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 @code{up-down}, only the @kbd{@key{UP}} and @kbd{@key{DOWN}}
arrow keys move point between completion candidates, while
@kbd{@key{RIGHT}} and @kbd{@key{LEFT}} move point in the minibuffer
window.

@node Completion Exit
@subsection Completion Exit

@kindex RET @r{(completion in minibuffer)}
@findex minibuffer-complete-and-exit
  When a command reads an argument using the minibuffer with
completion, it also controls what happens when you type @key{RET}
(@code{minibuffer-complete-and-exit}) to submit the argument.  There
are four types of behavior:

@itemize @bullet
@item
@dfn{Strict completion} accepts only exact completion matches.  Typing
@key{RET} exits the minibuffer only if the minibuffer text is an exact
match, or completes to one.  Otherwise, Emacs refuses to exit the
minibuffer; instead it tries to complete, and if no completion can be
done it momentarily displays @samp{[No match]} after the minibuffer
text.  (You can still leave the minibuffer by typing @kbd{C-g} to
cancel the command.)

An example of a command that uses this behavior is @kbd{M-x}, since it
is meaningless for it to accept a non-existent command name.

@item
@dfn{Cautious completion} is like strict completion, except @key{RET}
exits only if the text is already an exact match.  If the text
completes to an exact match, @key{RET} performs that completion but
does not exit yet; you must type a second @key{RET} to exit.

Cautious completion is used for reading file names for files that must
already exist, for example.

@item
@dfn{Permissive completion} allows any input; the completion
candidates are just suggestions.  Typing @key{RET} does not complete,
it just submits the argument as you have entered it.

@cindex minibuffer confirmation
@cindex confirming in the minibuffer
@item
@dfn{Permissive completion with confirmation} is like permissive
completion, with an exception: if you typed @key{TAB} and this
completed the text up to some intermediate state (i.e., one that is not
yet an exact completion match), typing @key{RET} right afterward does
not submit the argument.  Instead, Emacs asks for confirmation by
momentarily displaying @samp{[Confirm]} after the text; type @key{RET}
again to confirm and submit the text.  This catches a common mistake,
in which one types @key{RET} before realizing that @key{TAB} did not
complete as far as desired.

@vindex confirm-nonexistent-file-or-buffer
You can tweak the confirmation behavior by customizing the variable
@code{confirm-nonexistent-file-or-buffer}.  The default value,
@code{after-completion}, gives the behavior we have just described.
If you change it to @code{nil}, Emacs does not ask for confirmation,
falling back on permissive completion.  If you change it to any other
non-@code{nil} value, Emacs asks for confirmation whether or not the
preceding command was @key{TAB}.

This behavior is used by most commands that read file names, like
@kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}.
@end itemize

@node Completion Styles
@subsection How Completion Alternatives Are Chosen
@cindex completion style

  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 @ref{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 @dfn{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.

@vindex completion-styles
  The list variable @code{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 @code{let}-style list of bindings which will be in
effect for that completion style.  Multiple elements of
@code{completion-styles} can name the same completion style with
different variable bindings.

The available style symbols are stored in the variable
@code{completion-styles-alist} (@pxref{Completion Variables,,, elisp,
The Emacs Lisp Reference Manual}).  The default completion styles are
(in order):

@table @code
@item basic
@cindex @code{basic}, completion style
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.

@cindex partial completion
@cindex @code{partial-completion}, completion style
@item 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,
@samp{em-l-m} completes to @samp{emacs-lisp-mode}.)

Furthermore, a @samp{*} in the minibuffer text is treated as a
@dfn{wildcard}---it matches any string of characters at the
corresponding position in the completion alternative.

@vindex completion-pcm-leading-wildcard
If @code{completion-pcm-leading-wildcard} is set to @code{t}, this style
always acts as if a @dfn{wildcard} is present at the start of each word
in the minibuffer text, similar to the @code{substring} style.  For
example, @samp{l-ode} will complete to @samp{emacs-lisp-mode}.

@item emacs22
@cindex @code{emacs22}, completion style
This completion style is similar to @code{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.
@end table

@noindent
The following additional completion styles are also defined, and you
can add them to @code{completion-styles} if you wish
(@pxref{Customization}):

@table @code
@item substring
@cindex @code{substring}, completion style
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 @samp{foobar}, with point
between @samp{foo} and @samp{bar}, that matches
@samp{@var{a}foo@var{b}bar@var{c}}, where @var{a}, @var{b}, and
@var{c} can be any string including the empty string.

@item flex
@cindex @code{flex}, completion style
This aggressive completion style, also known as @code{flx} or
@code{fuzzy} or @code{scatter} completion, attempts to complete using
in-order substrings.  For example, it can consider @samp{foo} to match
@samp{frodo} or @samp{fbarbazoo}.

@item initials
@cindex @code{initials}, completion style
This very aggressive completion style attempts to complete acronyms
and initialisms.  For example, when completing command names, it
matches @samp{lch} to @samp{list-command-history}.
@end table

@noindent
There is also a very simple completion style called @code{emacs21}.
In this style, if the text in the minibuffer is @samp{foobar},
only matches starting with @samp{foobar} are considered.

@vindex completion-category-overrides
You can use different completion styles in different situations,
by setting the variable @code{completion-category-overrides}.
For example, the default setting says to use only @code{basic}
and @code{substring} completion for buffer names.


@node Completion Options
@subsection Completion Options

@cindex case-sensitivity and completion
@cindex case in completion
  Case is significant when completing case-sensitive arguments, such
as command names.  For example, when completing command names,
@samp{AU} does not complete to @samp{auto-fill-mode}.  Case
differences are ignored when completing arguments in which case does
not matter.

@vindex read-file-name-completion-ignore-case
@vindex read-buffer-completion-ignore-case
  When completing file names, case differences are ignored if the
variable @code{read-file-name-completion-ignore-case} is
non-@code{nil}.  The default value is @code{nil} on systems that have
case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on
systems that have case-insensitive file-names, such as Microsoft
Windows.  When completing buffer names, case differences are ignored
if the variable @code{read-buffer-completion-ignore-case} is
non-@code{nil}; the default is @code{nil}.

@vindex completion-ignored-extensions
@cindex ignored file names, in completion
  When completing file names, Emacs usually omits certain alternatives
that are considered unlikely to be chosen, as determined by the list
variable @code{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
(@file{/}) represents a subdirectory name.  The standard value of
@code{completion-ignored-extensions} has several elements including
@code{".o"}, @code{".elc"}, and @code{"~"}.  For example, if a
directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo}
completes to @samp{foo.c}.  However, if @emph{all} possible
completions end in otherwise-ignored strings, they are not ignored: in the
previous example, @samp{foo.e} completes to @samp{foo.elc}.  Emacs
disregards @code{completion-ignored-extensions} when showing
completion alternatives in the completion list.

  Shell completion is an extended version of filename completion,
@pxref{Shell Options}.

@vindex completion-auto-help
  If @code{completion-auto-help} is set to @code{nil}, the completion
commands never display the completion list buffer; you must type
@kbd{?} to display the list.  If the value is @code{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 @key{TAB}
echoes @samp{Next char not unique}; the second @key{TAB} shows the
completion list buffer.  If the value is @code{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 @code{completion-auto-help}.  If the
value is @code{t} or @code{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 @code{always}, the window pops down only when you exit
the completion.  The value @code{visible} is a hybrid: it behaves like
@code{t} when it decides whether to pop up the window showing the
completion list buffer, and like @code{always} when it decides whether
to pop it down.

@vindex completion-auto-select
  Emacs can optionally select the window showing the completions when
it shows that window.  To enable this behavior, customize the user
option @code{completion-auto-select} to @code{t}, which changes the
behavior of @key{TAB} when Emacs pops up the completions: pressing
@kbd{@key{TAB}} will switch to the completion list buffer, and you can
then move to a candidate by cursor motion commands and select it with
@kbd{@key{RET}}.  If the value of @code{completion-auto-select} is
@code{second-tab}, then the first @kbd{@key{TAB}} will pop up the
completions list buffer, and the second one will switch to it.

@vindex completion-cycle-threshold
  If @code{completion-cycle-threshold} is non-@code{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 @code{completion-cycle-threshold} to
@code{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 @code{completion-cycle-threshold} a
numeric value @var{n}, completion commands switch to this cycling
behavior only when there are @var{n} or fewer alternatives.

@vindex completions-sort
  The user option @code{completions-sort} controls the order in which
the completions are sorted in the @samp{*Completions*} buffer.  With the
default value @code{alphabetical}, the completions are displayed in
alphabetical order.  The value @code{nil} disables sorting; the value
@code{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.

@vindex completions-format
  By default, the @samp{*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 @code{completions-format}.  If its value is @code{vertical}, the
@samp{*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 @code{one-column}, all completions appear in a
single column.@footnote{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 @code{completions-format} is @code{horizontal} or @code{vertical}.}

@vindex completion-auto-wrap
  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
@code{completion-auto-wrap} to @code{nil}; then typing @kbd{@key{TAB}}
or @kbd{n} on the last candidate, or typing @kbd{S-@key{TAB}} or @kbd{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 @kbd{@key{RIGHT}}
and @kbd{@key{LEFT}}, and in the vertical format @kbd{@key{DOWN}} and
@kbd{@key{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
@kbd{@key{DOWN}} and @kbd{@key{UP}} move---and wrap, if wrapping is
enabled---only within the current column of completions, and in the
vertical format @kbd{@key{RIGHT}} and @kbd{@key{LEFT}} move (and wrap,
if enabled) only within the current line of completions.@footnote{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
@code{completion-auto-wrap} is non-@code{nil}.}

@vindex completions-max-height
  When @code{completions-max-height} is non-@code{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
@code{display-buffer-alist} (@pxref{Buffer Display Action
Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp
Reference Manual}).

@vindex completions-header-format
The variable @code{completions-header-format} is a format spec string to
control the informative line shown before the completions list of
candidates.  If it contains a @samp{%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
@code{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 @code{face} or @code{cursor-intangible}
(@pxref{Special Properties,,Properties with Special Meanings, elisp,
The Emacs Lisp Reference Manual}).

@vindex completions-highlight-face
When @code{completions-highlight-face} names a face, the current
completion candidate, the one that will be selected by typing
@kbd{@key{RET}} or clicking the mouse, will be highlighted using that
face.  The default value of this variable is
@code{completions-highlight}; the value is @code{nil} disables this
highlighting.  This feature uses the special text property
@code{cursor-face}.

@node Minibuffer History
@section Minibuffer History
@cindex minibuffer history
@cindex history of minibuffer input
@cindex completion, walking through candidates

  Everything you type in the minibuffer is saved in a @dfn{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:

@table @kbd
@item M-p
Move to the previous item in the minibuffer history, an earlier
argument (@code{previous-history-element}).
@item M-n
Move to the next item in the minibuffer history
(@code{next-history-element}).
@item @key{UP}
@itemx @key{DOWN}
Like @kbd{M-p} and @kbd{M-n}, but move to the previous or next line of
a multi-line item before going to the previous history item
(@code{previous-line-or-history-element} and
@code{next-line-or-history-element}) .
@item M-r @var{regexp} @key{RET}
Move to an earlier item in the minibuffer history that
matches @var{regexp} (@code{previous-matching-history-element}).
@item M-s @var{regexp} @key{RET}
Move to a later item in the minibuffer history that matches
@var{regexp} (@code{next-matching-history-element}).
@end table

@kindex M-p @r{(minibuffer history)}
@kindex M-n @r{(minibuffer history)}
@findex next-history-element
@findex previous-history-element
  While in the minibuffer, @kbd{M-p} (@code{previous-history-element})
moves through the minibuffer history list, one item at a time.  Each
@kbd{M-p} fetches an earlier item from the history list into the
minibuffer, replacing its existing contents.  Typing @kbd{M-n}
(@code{next-history-element}) moves through the minibuffer history
list in the opposite direction, fetching later entries into the
minibuffer.

@cindex future history
  If you type @kbd{M-n} in the minibuffer when there are no later
entries in the minibuffer history (e.g., if you haven't previously
typed @kbd{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 @dfn{future history}.  Searching forward through
minibuffer history (@pxref{Isearch Minibuffer}) includes the ``future
history'' as well.

@cindex minibuffer defaults for file names
@vindex file-name-at-point-functions
  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 @code{file-name-at-point-functions}.  By
default, its value invokes the @code{ffap} package (@pxref{FFAP}),
which tries to guess the default file or URL from the text around
point.  To disable this guessing, customize the option to a @code{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.

@findex previous-line-or-history-element
@findex next-line-or-history-element
@kindex UP @r{(minibuffer history)}
@kindex DOWN @r{(minibuffer history)}
  The arrow keys @kbd{@key{UP}} and @kbd{@key{DOWN}} work like
@kbd{M-p} and @kbd{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 @kbd{M-p} or @kbd{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.

@findex previous-matching-history-element
@findex next-matching-history-element
@kindex M-r @r{(minibuffer history)}
@kindex M-s @r{(minibuffer history)}
  You can use @kbd{M-r} (@code{previous-matching-history-element}) to
search through older elements in the history list, and @kbd{M-s}
(@code{next-matching-history-element}) to search through newer
entries.  Each of these commands asks for a @dfn{regular expression}
as an argument, and fetches the first matching entry into the
minibuffer.  @xref{Regexps}, for an explanation of regular
expressions.  A numeric prefix argument @var{n} means to fetch the
@var{n}th 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 (@pxref{Lax
Search}).

  You can also search through the minibuffer history using incremental
search (@kbd{C-s} and @kbd{C-r}).  @xref{Isearch 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 @kbd{M-x}), and command arguments (used
by commands like @code{query-replace}).

@vindex history-length
  The variable @code{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 @code{t}, there is
no maximum length.

@vindex history-delete-duplicates
  The variable @code{history-delete-duplicates} specifies whether to
delete duplicates in history.  If it is non-@code{nil}, adding a new
element deletes from the list all other elements that are equal to it.
The default is @code{nil}.

@node Repetition
@section Repeating Minibuffer Commands
@cindex command history
@cindex history of commands

  Every command that uses the minibuffer once is recorded on a special
history list, the @dfn{command history}, together with the values of
its arguments, so that you can repeat the entire command.  In
particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x}
uses the minibuffer to read the command name.

@findex list-command-history
@table @kbd
@item C-x @key{ESC} @key{ESC}
Re-execute a recent minibuffer command from the command history
 (@code{repeat-complex-command}).
@item M-x list-command-history
Display the entire command history, showing all the commands
@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
@end table

@kindex C-x ESC ESC
@findex repeat-complex-command
  @kbd{C-x @key{ESC} @key{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.

  @kbd{C-x @key{ESC} @key{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 @key{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 @kbd{C-x @key{ESC} @key{ESC}}, you
can use the usual minibuffer history commands (@pxref{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 @key{RET}.

@vindex isearch-resume-in-command-history
  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 @w{@kbd{C-x @key{ESC} @key{ESC}}}.
You can make incremental search commands appear in the history by
setting @code{isearch-resume-in-command-history} to a non-@code{nil}
value.  @xref{Incremental Search}.

@vindex command-history
  The list of previous minibuffer-using commands is stored as a Lisp
list in the variable @code{command-history}.  Each element is a Lisp
expression that describes one command and its arguments.  Lisp programs
can re-execute a command by calling @code{eval} with the
@code{command-history} element.

@node Passwords
@section Entering passwords
@cindex entering passwords

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 (@pxref{Remote Files}).

  Entering a password is similar to using a minibuffer.  Emacs
displays a prompt in the echo area (such as @samp{Password: }); after
you type the required password, press @key{RET} to submit it.  To
prevent others from seeing your password, every character you type is
displayed as an asterisk (@samp{*}) instead of its usual form.

  Most of the features and commands associated with the minibuffer
@emph{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 @key{DEL} to delete
backwards, removing the last character entered.  @kbd{C-u} deletes
everything you have typed so far.  @kbd{C-g} quits the password prompt
(@pxref{Quitting}).  @kbd{C-y} inserts the current kill into the
password (@pxref{Killing}).  @key{TAB} toggles the visibility of the
password.  You may type either @key{RET} or @key{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 @kbd{mouse-1} on it toggles the password
visibility as well.

@node Yes or No Prompts
@section Yes or No Prompts

  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.

@cindex y or n prompt
  For the first type of yes-or-no query, the prompt ends with
@w{@samp{(y or n)}}.  You answer the query by typing a single key,
either @samp{y} or @samp{n}, which immediately exits the minibuffer
and delivers the response.  For example, if you type @kbd{C-x C-w}
(@kbd{write-file}) to save a buffer, and enter the name of an existing
file, Emacs issues a prompt like this:

@smallexample
File `foo.el' exists; overwrite? (y or n)
@end smallexample

@cindex yes or no prompt
@vindex yes-or-no-prompt
  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 @samp{(yes or no)} (or the value of
@code{yes-or-no-prompt} if you've customized that).  For example, if
you invoke @kbd{C-x k} (@code{kill-buffer}) on a file-visiting buffer
with unsaved changes, Emacs activates the minibuffer with a prompt
like this:

@smallexample
Buffer foo.el modified; kill anyway? (yes or no)
@end smallexample

@noindent
To answer, you must type @samp{yes} or @samp{no} into the minibuffer,
followed by @key{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
@kbd{C-l}, scroll that window (@kbd{C-v} or @kbd{PageDown} scrolls
forward, @kbd{M-v} or @kbd{PageUp} scrolls backward), switch to
another window with @kbd{C-x o}, use the history commands @kbd{M-p}
and @kbd{M-n}, etc.  Type @kbd{C-g} to dismiss the query, and quit the
minibuffer and the querying command (@pxref{Quitting}).