mini.texi 29.5 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
3
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4 5 6 7 8 9
@c See file emacs.texi for copying conditions.
@node Minibuffer, M-x, Basic, Top
@chapter The Minibuffer
@cindex minibuffer

  The @dfn{minibuffer} is where Emacs commands read complicated
10 11 12 13 14
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.
Glenn Morris's avatar
Glenn Morris committed
15 16 17

@cindex prompt
  When the minibuffer is in use, it appears in the echo area, with a
18 19 20
cursor.  The minibuffer starts with a @dfn{prompt} in a distinct
color, usually ending with a colon.  The prompt states what kind of
input is expected, and how it will be used.
21 22 23 24 25

  The simplest way to enter a minibuffer argument is to type the text,
then @key{RET} to submit the argument and exit the minibuffer.  You
can cancel the minibuffer, and the command that wants the argument, by
typing @kbd{C-g}.
Glenn Morris's avatar
Glenn Morris committed
26 27

@cindex default argument
28
  Sometimes, a @dfn{default argument} appears in the prompt, inside
29 30 31 32
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.
Glenn Morris's avatar
Glenn Morris committed
33 34

  Since the minibuffer appears in the echo area, it can conflict with
35 36 37 38 39
other uses of the echo area.  If an error message or an informative
message is emitted while the minibuffer is active, the message hides
the minibuffer for a few seconds, or until you type something; then
the minibuffer comes back.  While the minibuffer is in use, keystrokes
do not echo.
Glenn Morris's avatar
Glenn Morris committed
40 41

@menu
42 43
* Minibuffer File::       Entering file names with the minibuffer.
* Minibuffer Edit::       How to edit in the minibuffer.
44
* Completion::            An abbreviation facility for minibuffer input.
Glenn Morris's avatar
Glenn Morris committed
45
* Minibuffer History::    Reusing recent minibuffer arguments.
46
* Repetition::            Re-executing commands that used the minibuffer.
Chong Yidong's avatar
Chong Yidong committed
47
* Passwords::             Entering passwords in the echo area.
Glenn Morris's avatar
Glenn Morris committed
48 49 50 51 52
@end menu

@node Minibuffer File
@section Minibuffers for File Names

53
@cindex default directory
54 55 56
  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
57 58
some initial text ending in a slash.  This is the @dfn{default
directory}.  For example, it may start out like this:
Glenn Morris's avatar
Glenn Morris committed
59 60 61 62 63 64

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

@noindent
65 66
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
67 68
specifies the file @file{/u2/emacs/src/buffer.c}.  @xref{File Names},
for information about the default directory.
69

70 71 72 73
  You can specify 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}).
74 75 76 77 78 79

  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:
Glenn Morris's avatar
Glenn Morris committed
80 81 82 83 84 85 86 87 88 89

@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
90 91
Emacs interprets a double slash as ``ignore everything before the
second slash in the pair.''  In the example above,
92
@file{/u2/emacs/src/} is ignored, so the argument you supplied is
93
@file{/etc/termcap}.  The ignored part of the file name is dimmed if
94
the terminal allows it.  (To disable this dimming, turn off File Name
95 96 97
Shadow mode with the command @kbd{M-x file-name-shadow-mode}.)

@cindex home directory shorthand
98 99 100
  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
101
directory.  In addition, @file{~@var{user-id}/} means the home
102 103 104 105 106 107 108 109
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
110
@ref{MS-DOS File Names}.
111 112
@end ifnottex
@iftex
113 114
@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of
the Emacs Manual}.
115 116 117 118
@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.
119 120

@vindex insert-default-directory
121 122 123 124 125
  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.
Glenn Morris's avatar
Glenn Morris committed
126

127 128
  You can also enter remote file names in the minibuffer.
@xref{Remote Files}.
129

Glenn Morris's avatar
Glenn Morris committed
130 131 132
@node Minibuffer Edit
@section Editing in the Minibuffer

133
  The minibuffer is an Emacs buffer, albeit a peculiar one, and the
Glenn Morris's avatar
Glenn Morris committed
134
usual Emacs commands are available for editing the argument text.
135
(The prompt, however, is @dfn{read-only}, and cannot be changed.)
Glenn Morris's avatar
Glenn Morris committed
136

137 138 139 140 141
  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}).
Glenn Morris's avatar
Glenn Morris committed
142

143 144 145 146 147
  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.
148 149 150 151 152

  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}.
Glenn Morris's avatar
Glenn Morris committed
153 154 155 156 157

@cindex height of minibuffer
@cindex size of minibuffer
@cindex growing minibuffer
@cindex resizing minibuffer
158 159 160 161 162 163 164
  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}.
Glenn Morris's avatar
Glenn Morris committed
165 166

@vindex resize-mini-windows
167 168
  Normally, the minibuffer window occupies a single screen line.
However, if you add two or more lines' worth of text into the
Juanma Barranquero's avatar
Juanma Barranquero committed
169
minibuffer, it expands automatically to accommodate the text.  The
170 171 172 173 174 175 176 177
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}).
Glenn Morris's avatar
Glenn Morris committed
178 179 180

@vindex max-mini-window-height
  The variable @code{max-mini-window-height} controls the maximum
181
height for resizing the minibuffer window.  A floating-point number
Glenn Morris's avatar
Glenn Morris committed
182 183 184 185 186
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
187 188 189 190 191
commands that display help text of any sort in another window.  You
can also scroll the help text with @kbd{M-@key{prior}} and
@kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and
@kbd{M-@key{PageDown}}).  This is especially useful with long lists of
possible completions.  @xref{Other Window}.
Glenn Morris's avatar
Glenn Morris committed
192 193 194

@vindex enable-recursive-minibuffers
  Emacs normally disallows most commands that use the minibuffer while
195 196
the minibuffer is active.  To allow such commands in the minibuffer,
set the variable @code{enable-recursive-minibuffers} to @code{t}.
Glenn Morris's avatar
Glenn Morris committed
197 198 199

@node Completion
@section Completion
200 201
@c This node is referenced in the tutorial.  When renaming or deleting
@c it, the tutorial needs to be adjusted.
Glenn Morris's avatar
Glenn Morris committed
202
@cindex completion
203

204 205 206
  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.
207

208
@cindex completion alternative
209
  When completion is available, certain keys (usually @key{TAB},
210 211 212 213 214 215 216 217 218 219
@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 see a list of
completion alternatives.

  Although completion is usually done in the minibuffer, the feature
is sometimes available in ordinary buffers too.  @xref{Symbol
Completion}.
Glenn Morris's avatar
Glenn Morris committed
220 221 222 223 224

@menu
* Example: Completion Example.    Examples of using completion.
* Commands: Completion Commands.  A list of completion commands.
* Strict Completion::             Different types of completion.
225
* Completion Styles::             How completion matches are chosen.
Glenn Morris's avatar
Glenn Morris committed
226 227 228 229 230 231 232
* Options: Completion Options.    Options for completion.
@end menu

@node Completion Example
@subsection Completion Example

@kindex TAB @r{(completion)}
233 234 235 236 237 238 239 240 241 242 243 244
  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}.
Glenn Morris's avatar
Glenn Morris committed
245 246

  If you type @key{TAB} again immediately, it cannot determine the
247 248 249
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.
Glenn Morris's avatar
Glenn Morris committed
250

251 252 253 254 255 256 257
  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 @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}.
Glenn Morris's avatar
Glenn Morris committed
258 259 260 261 262 263 264 265 266 267

@node Completion Commands
@subsection Completion Commands

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

@table @kbd
@item @key{TAB}
@findex minibuffer-complete
268 269
Complete the text in the minibuffer as much as possible; if unable to
complete, display a list of possible completions
Glenn Morris's avatar
Glenn Morris committed
270 271 272
(@code{minibuffer-complete}).
@item @key{SPC}
Complete up to one word from the minibuffer text before point
273 274
(@code{minibuffer-complete-word}).  This command is not available for
arguments that often include spaces, such as file names.
Glenn Morris's avatar
Glenn Morris committed
275 276
@item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing
277
first (@code{minibuffer-complete-and-exit}).  @xref{Strict Completion}.
Glenn Morris's avatar
Glenn Morris committed
278
@item ?
279
Display a list of completions (@code{minibuffer-completion-help}).
Glenn Morris's avatar
Glenn Morris committed
280 281
@end table

282
@kindex TAB @r{(completion)}
283 284
@findex minibuffer-complete
  @key{TAB} (@code{minibuffer-complete}) is the most fundamental
285 286 287 288
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.
289

290
@kindex SPC @r{(completion)}
Glenn Morris's avatar
Glenn Morris committed
291
@findex minibuffer-complete-word
292 293 294 295 296 297
  @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}.
Glenn Morris's avatar
Glenn Morris committed
298

299 300
@kindex ? @r{(completion)}
@cindex completion list
301
  If @key{TAB} or @key{SPC} is unable to complete, it displays a list
302 303 304 305
of matching completion alternatives (if there are any) in another
window.  You can display the same list with @kbd{?}
(@code{minibuffer-completion-help}).  The following commands can be
used with the completion list:
Glenn Morris's avatar
Glenn Morris committed
306 307 308 309 310

@table @kbd
@findex mouse-choose-completion
@item Mouse-1
@itemx Mouse-2
311 312
Clicking mouse button 1 or 2 on a completion alternative chooses it
(@code{mouse-choose-completion}).
Glenn Morris's avatar
Glenn Morris committed
313 314

@findex switch-to-completions
315 316
@item M-v
@itemx @key{PageUp}
317
@itemx @key{prior}
318
Typing @kbd{M-v}, while in the minibuffer, selects the window showing
319 320 321 322
the completion list (@code{switch-to-completions}).  This paves the
way for using the commands below.  @key{PageUp} or @key{prior} does
the same.  You can also select the window in other ways
(@pxref{Windows}).
Glenn Morris's avatar
Glenn Morris committed
323 324 325

@findex choose-completion
@item @key{RET}
326 327
While in the completion list buffer, this chooses the completion at
point (@code{choose-completion}).
Glenn Morris's avatar
Glenn Morris committed
328 329

@findex next-completion
330
@item @key{Right}
331 332
While in the completion list buffer, this moves point to the following
completion alternative (@code{next-completion}).
Glenn Morris's avatar
Glenn Morris committed
333 334

@findex previous-completion
335
@item @key{Left}
336 337
While in the completion list buffer, this moves point to the previous
completion alternative (@code{previous-completion}).
Glenn Morris's avatar
Glenn Morris committed
338 339 340 341 342
@end table

@node Strict Completion
@subsection Strict Completion

343 344
  There are three ways that the @key{RET}
(@code{minibuffer-complete-and-exit}) completion command can act,
Glenn Morris's avatar
Glenn Morris committed
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372
depending on how the argument will be used.

@itemize @bullet
@item
@dfn{Strict} completion accepts only known completion candidates.  For
example, when @kbd{C-x k} reads the name of a buffer to kill, only the
name of an existing buffer makes sense.  In strict completion,
@key{RET} refuses to exit if the text in the minibuffer does not
complete to an exact match.

@item
@dfn{Cautious} completion is similar to strict completion, except that
@key{RET} exits only if the text is an already exact match.
Otherwise, @key{RET} does not exit, but it does complete the text.  If
that completes to an exact match, a second @key{RET} will 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.  For example, when @kbd{C-x C-f}
reads the name of a file to visit, any file name is allowed, including
nonexistent file (in case you want to create a file).  In permissive
completion, @key{RET} does not complete, it just submits the argument
as you have entered it.
@end itemize

373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
  Like the other completion commands, @key{RET} displays a list of all
possible completions whenever it is supposed to complete but is unable
to complete any further.

@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 the name of a completion style (a
Lisp symbol).  The default completion styles are (in order):

@table @code
@item 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.

@findex partial completion
@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 character at the corresponding
position in the completion alternative.

@item emacs22
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 and
earlier.
@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
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 initials
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
Glenn Morris's avatar
Glenn Morris committed
446 447 448 449

@node Completion Options
@subsection Completion Options

450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
@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
465 466 467
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}.
468 469 470 471

@vindex completion-ignored-extensions
@cindex ignored file names, in completion
  When completing file names, Emacs usually omits certain alternatives
472 473 474 475 476 477 478 479
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}
480 481
completes to @samp{foo.c}.  However, if @emph{all} possible
completions end in ``ignored'' strings, they are not ignored: in the
482 483 484
previous example, @samp{foo.e} completes to @samp{foo.elc}.  Emacs
disregards @code{completion-ignored-extensions} when showing
completion alternatives in the completion list.
485

486 487 488 489 490 491 492
@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} does the
Juanma Barranquero's avatar
Juanma Barranquero committed
493
completion list buffer.
494

495 496 497 498 499 500 501 502 503 504 505 506
@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 fewer than @var{n} alternatives.
Glenn Morris's avatar
Glenn Morris committed
507 508 509 510 511 512 513 514 515 516 517 518 519

@cindex Icomplete mode
@findex icomplete-mode
  Icomplete mode presents a constantly-updated display that tells you
what completions are available for the text you've entered so far.  The
command to enable or disable this minor mode is @kbd{M-x
icomplete-mode}.

@node Minibuffer History
@section Minibuffer History
@cindex minibuffer history
@cindex history of minibuffer input

520
  Every argument that you enter with the minibuffer is saved in a
Glenn Morris's avatar
Glenn Morris committed
521
@dfn{minibuffer history list} so you can easily use it again later.
522 523
You can use the following arguments to quickly fetch an earlier
argument into the minibuffer:
Glenn Morris's avatar
Glenn Morris committed
524 525

@table @kbd
526 527 528 529 530 531
@item M-p
@itemx @key{Up}
Move to the previous item in the minibuffer history, an earlier
argument (@code{previous-history-element}).
@item M-n
@itemx @key{Down}
Glenn Morris's avatar
Glenn Morris committed
532 533 534
Move to the next item in the minibuffer history
(@code{next-history-element}).
@item M-r @var{regexp} @key{RET}
535
Move to an earlier item in the minibuffer history that
Glenn Morris's avatar
Glenn Morris committed
536 537 538 539 540 541 542 543
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)}
544 545
@kindex UP @r{(minibuffer history)}
@kindex DOWN @r{(minibuffer history)}
Glenn Morris's avatar
Glenn Morris committed
546 547
@findex next-history-element
@findex previous-history-element
548 549 550 551 552 553 554
  While in the minibuffer, @kbd{M-p} or @key{Up}
(@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} or @key{Down} (@code{next-history-element}) moves
through the minibuffer history list in the opposite direction,
fetching later entries into the minibuffer.
555 556 557 558

  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
559 560
arguments: values that you are likely to enter.  You can think of this
as moving through the ``future history'' list.
561

562 563 564 565
  If you edit the text inserted by the @kbd{M-p} or @key{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.
Glenn Morris's avatar
Glenn Morris committed
566 567 568 569 570

@findex previous-matching-history-element
@findex next-matching-history-element
@kindex M-r @r{(minibuffer history)}
@kindex M-s @r{(minibuffer history)}
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591
  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{Search
Case}).

  You can also search through the history using an incremental search.
@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}).
Glenn Morris's avatar
Glenn Morris committed
592 593 594 595

@vindex history-length
  The variable @code{history-length} specifies the maximum length of a
minibuffer history list; adding a new element deletes the oldest
596 597
element if the list gets too long.  If the value is @code{t}, there is
no maximum length.
Glenn Morris's avatar
Glenn Morris committed
598 599 600

@vindex history-delete-duplicates
  The variable @code{history-delete-duplicates} specifies whether to
601 602 603
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}.
Glenn Morris's avatar
Glenn Morris committed
604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627

@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
628 629 630 631
  @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.
Glenn Morris's avatar
Glenn Morris committed
632 633 634

  @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
into a Lisp expression and then entering a minibuffer initialized with
635 636 637 638 639 640 641 642 643 644 645 646
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 repeated 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 repeat
it by typing @key{RET}.
Glenn Morris's avatar
Glenn Morris committed
647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662

@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 @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 which describes one command and its arguments.  Lisp programs
can re-execute a command by calling @code{eval} with the
@code{command-history} element.

Chong Yidong's avatar
Chong Yidong committed
663 664 665 666 667 668 669 670
@node Passwords
@section 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}).

671 672 673 674 675
  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 a dot (@samp{.}) instead of its usual form.
Chong Yidong's avatar
Chong Yidong committed
676 677 678 679 680 681 682 683 684 685 686 687 688 689

  Most of the features and commands associated with the minibuffer can
@emph{not} 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.  @key{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}).  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.