ChangeLog fix
[emacs.git] / doc / emacs / mini.texi
bloba87aff0e135ee97aa15e847f3d746ad85aad4805
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Minibuffer
6 @chapter The Minibuffer
7 @cindex minibuffer
9   The @dfn{minibuffer} is where Emacs commands read complicated
10 arguments, such as file names, buffer names, Emacs command names, or
11 Lisp expressions.  We call it the ``minibuffer'' because it's a
12 special-purpose buffer with a small amount of screen space.  You can
13 use the usual Emacs editing commands in the minibuffer to edit the
14 argument text.
16 @menu
17 * Basic Minibuffer::      Basic usage of the minibuffer.
18 * Minibuffer File::       Entering file names with the minibuffer.
19 * Minibuffer Edit::       How to edit in the minibuffer.
20 * Completion::            An abbreviation facility for minibuffer input.
21 * Minibuffer History::    Reusing recent minibuffer arguments.
22 * Repetition::            Re-executing commands that used the minibuffer.
23 * Passwords::             Entering passwords in the echo area.
24 * Yes or No Prompts::     Replying yes or no in the echo area.
25 @end menu
27 @node Basic Minibuffer
28 @section Using the Minibuffer
30 @cindex prompt
31   When the minibuffer is in use, it appears in the echo area, with a
32 cursor.  The minibuffer starts with a @dfn{prompt}, usually ending
33 with a colon.  The prompt states what kind of input is expected, and
34 how it will be used.  The prompt is highlighted using the
35 @code{minibuffer-prompt} face (@pxref{Faces}).
37   The simplest way to enter a minibuffer argument is to type the text,
38 then @key{RET} to submit the argument and exit the minibuffer.
39 Alternatively, you can type @kbd{C-g} to exit the minibuffer by
40 canceling the command asking for the argument (@pxref{Quitting}).
42 @cindex default argument
43   Sometimes, the prompt shows a @dfn{default argument}, inside
44 parentheses before the colon.  This default will be used as the
45 argument if you just type @key{RET}.  For example, commands that read
46 buffer names usually show a buffer name as the default; you can type
47 @key{RET} to operate on that default buffer.
49 @cindex Minibuffer Electric Default mode
50 @cindex mode, Minibuffer Electric Default
51 @findex minibuffer-electric-default-mode
52 @vindex minibuffer-eldef-shorten-default
53   If you enable Minibuffer Electric Default mode, a global minor mode,
54 Emacs hides the default argument as soon as you modify the contents of
55 the minibuffer (since typing @key{RET} would no longer submit that
56 default).  If you ever bring back the original minibuffer text, the
57 prompt again shows the default.  Furthermore, if you change the
58 variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil}
59 value, the default argument is displayed as @samp{[@var{default}]}
60 instead of @samp{(default @var{default})}, saving some screen space.
61 To enable this minor mode, type @kbd{M-x
62 minibuffer-electric-default-mode}.
64   Since the minibuffer appears in the echo area, it can conflict with
65 other uses of the echo area.  If an error message or an informative
66 message is emitted while the minibuffer is active, the message hides
67 the minibuffer for a few seconds, or until you type something; then
68 the minibuffer comes back.  While the minibuffer is in use, keystrokes
69 do not echo.
71 @node Minibuffer File
72 @section Minibuffers for File Names
74 @cindex default directory
75   Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer
76 to read a file name argument (@pxref{Basic Files}).  When the
77 minibuffer is used to read a file name, it typically starts out with
78 some initial text ending in a slash.  This is the @dfn{default
79 directory}.  For example, it may start out like this:
81 @example
82 Find file: /u2/emacs/src/
83 @end example
85 @noindent
86 Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is
87 the default directory.  If you now type @kbd{buffer.c} as input, that
88 specifies the file @file{/u2/emacs/src/buffer.c}.  @xref{File Names},
89 for information about the default directory.
91   You can specify the parent directory with @file{..}:
92 @file{/a/b/../foo.el} is equivalent to @file{/a/foo.el}.
93 Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names
94 backwards (@pxref{Words}).
96   To specify a file in a completely different directory, you can kill
97 the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}).
98 Alternatively, you can ignore the default, and enter an absolute file
99 name starting with a slash or a tilde after the default directory.
100 For example, you can specify @file{/etc/termcap} as follows:
102 @example
103 Find file: /u2/emacs/src//etc/termcap
104 @end example
106 @noindent
107 @cindex // in file name
108 @cindex double slash in file name
109 @cindex slashes repeated in file name
110 @findex file-name-shadow-mode
111 Emacs interprets a double slash as ``ignore everything before the
112 second slash in the pair''.  In the example above,
113 @file{/u2/emacs/src/} is ignored, so the argument you supplied is
114 @file{/etc/termcap}.  The ignored part of the file name is dimmed if
115 the terminal allows it.  (To disable this dimming, turn off File Name
116 Shadow mode with the command @kbd{M-x file-name-shadow-mode}.)
118 @cindex home directory shorthand
119   Emacs interprets @file{~/} as your home directory.  Thus,
120 @file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a
121 directory named @file{foo}, which is in turn located in your home
122 directory.  In addition, @file{~@var{user-id}/} means the home
123 directory of a user whose login name is @var{user-id}.  Any leading
124 directory name in front of the @file{~} is ignored: thus,
125 @file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}.
127   On MS-Windows and MS-DOS systems, where a user doesn't always have a
128 home directory, Emacs uses several alternatives.  For MS-Windows, see
129 @ref{Windows HOME}; for MS-DOS, see
130 @ifnottex
131 @ref{MS-DOS File Names}.
132 @end ifnottex
133 @iftex
134 @ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of
135 the Emacs Manual}.
136 @end iftex
137 On these systems, the @file{~@var{user-id}/} construct is supported
138 only for the current user, i.e., only if @var{user-id} is the current
139 user's login name.
141 @vindex insert-default-directory
142   To prevent Emacs from inserting the default directory when reading
143 file names, change the variable @code{insert-default-directory} to
144 @code{nil}.  In that case, the minibuffer starts out empty.
145 Nonetheless, relative file name arguments are still interpreted based
146 on the same default directory.
148   You can also enter remote file names in the minibuffer.
149 @xref{Remote Files}.
151 @node Minibuffer Edit
152 @section Editing in the Minibuffer
154   The minibuffer is an Emacs buffer, albeit a peculiar one, and the
155 usual Emacs commands are available for editing the argument text.
156 (The prompt, however, is @dfn{read-only}, and cannot be changed.)
158   Since @key{RET} in the minibuffer submits the argument, you can't
159 use it to insert a newline.  You can do that with @kbd{C-q C-j}, which
160 inserts a @kbd{C-j} control character, which is formally equivalent to
161 a newline character (@pxref{Inserting Text}).  Alternatively, you can
162 use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}).
164   Inside a minibuffer, the keys @key{TAB}, @key{SPC}, and @kbd{?} are
165 often bound to @dfn{completion commands}, which allow you to easily
166 fill in the desired text without typing all of it.  @xref{Completion}.
167 As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB},
168 @key{SPC}, or @samp{?}  character.
170   For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a
171 minibuffer moves point to the beginning of the argument text, not the
172 beginning of the prompt.  For example, this allows you to erase the
173 entire argument with @kbd{C-a C-k}.
175 @cindex height of minibuffer
176 @cindex size of minibuffer
177 @cindex growing minibuffer
178 @cindex resizing minibuffer
179   When the minibuffer is active, the echo area is treated much like an
180 ordinary Emacs window.  For instance, you can switch to another window
181 (with @kbd{C-x o}), edit text there, then return to the minibuffer
182 window to finish the argument.  You can even kill text in another
183 window, return to the minibuffer window, and yank the text into the
184 argument.  There are some restrictions on the minibuffer window,
185 however: for instance, you cannot split it.  @xref{Windows}.
187 @vindex resize-mini-windows
188   Normally, the minibuffer window occupies a single screen line.
189 However, if you add two or more lines' worth of text into the
190 minibuffer, it expands automatically to accommodate the text.  The
191 variable @code{resize-mini-windows} controls the resizing of the
192 minibuffer.  The default value is @code{grow-only}, which means the
193 behavior we have just described.  If the value is @code{t}, the
194 minibuffer window will also shrink automatically if you remove some
195 lines of text from the minibuffer, down to a minimum of one screen
196 line.  If the value is @code{nil}, the minibuffer window never changes
197 size automatically, but you can use the usual window-resizing commands
198 on it (@pxref{Windows}).
200 @vindex max-mini-window-height
201   The variable @code{max-mini-window-height} controls the maximum
202 height for resizing the minibuffer window.  A floating-point number
203 specifies a fraction of the frame's height; an integer specifies the
204 maximum number of lines; @code{nil} means do not resize the minibuffer
205 window automatically.  The default value is 0.25.
207   The @kbd{C-M-v} command in the minibuffer scrolls the help text from
208 commands that display help text of any sort in another window.  You
209 can also scroll the help text with @kbd{M-@key{prior}} and
210 @kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and
211 @kbd{M-@key{PageDown}}).  This is especially useful with long lists of
212 possible completions.  @xref{Other Window}.
214 @vindex enable-recursive-minibuffers
215   Emacs normally disallows most commands that use the minibuffer while
216 the minibuffer is active.  To allow such commands in the minibuffer,
217 set the variable @code{enable-recursive-minibuffers} to @code{t}.
219 @findex minibuffer-inactive-mode
220   When not active, the minibuffer is in @code{minibuffer-inactive-mode},
221 and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer.
222 If you use a dedicated frame for minibuffers, Emacs also recognizes
223 certain keys there, for example @kbd{n} to make a new frame.
225 @node Completion
226 @section Completion
227 @c This node is referenced in the tutorial.  When renaming or deleting
228 @c it, the tutorial needs to be adjusted.
229 @cindex completion
231   You can often use a feature called @dfn{completion} to help enter
232 arguments.  This means that after you type part of the argument, Emacs
233 can fill in the rest, or some of it, based on what was typed so far.
235 @cindex completion alternative
236   When completion is available, certain keys (usually @key{TAB},
237 @key{RET}, and @key{SPC}) are rebound in the minibuffer to special
238 completion commands (@pxref{Completion Commands}).  These commands
239 attempt to complete the text in the minibuffer, based on a set of
240 @dfn{completion alternatives} provided by the command that requested
241 the argument.  You can usually type @kbd{?} to see a list of
242 completion alternatives.
244   Although completion is usually done in the minibuffer, the feature
245 is sometimes available in ordinary buffers too.  @xref{Symbol
246 Completion}.
248 @menu
249 * Completion Example::       Examples of using completion.
250 * Completion Commands::      A list of completion commands.
251 * Completion Exit::          Completion and minibuffer text submission.
252 * Completion Styles::        How completion matches are chosen.
253 * Completion Options::       Options for completion.
254 @end menu
256 @node Completion Example
257 @subsection Completion Example
259 @kindex TAB @r{(completion)}
260   A simple example may help here.  @kbd{M-x} uses the minibuffer to
261 read the name of a command, so completion works by matching the
262 minibuffer text against the names of existing Emacs commands.  Suppose
263 you wish to run the command @code{auto-fill-mode}.  You can do that by
264 typing @kbd{M-x auto-fill-mode @key{RET}}, but it is easier to use
265 completion.
267   If you type @kbd{M-x a u @key{TAB}}, the @key{TAB} looks for
268 completion alternatives (in this case, command names) that start with
269 @samp{au}.  There are several, including @code{auto-fill-mode} and
270 @code{autoconf-mode}, but they all begin with @code{auto}, so the
271 @samp{au} in the minibuffer completes to @samp{auto}.  (More commands
272 may be defined in your Emacs session.  For example, if a command
273 called @code{authorize-me} was defined, Emacs could only complete
274 as far as @samp{aut}.)
276   If you type @key{TAB} again immediately, it cannot determine the
277 next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
278 does not add any characters; instead, @key{TAB} displays a list of all
279 possible completions in another window.
281   Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
282 the only command name that starts with this is @code{auto-fill-mode}.
283 If you now type @key{TAB}, completion fills in the rest of the
284 argument @samp{auto-fill-mode} into the minibuffer.
286   Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to
287 enter @samp{auto-fill-mode}.
289 @node Completion Commands
290 @subsection Completion Commands
292   Here is a list of the completion commands defined in the minibuffer
293 when completion is allowed.
295 @table @kbd
296 @item @key{TAB}
297 @findex minibuffer-complete
298 Complete the text in the minibuffer as much as possible; if unable to
299 complete, display a list of possible completions
300 (@code{minibuffer-complete}).
301 @item @key{SPC}
302 Complete up to one word from the minibuffer text before point
303 (@code{minibuffer-complete-word}).  This command is not available for
304 arguments that often include spaces, such as file names.
305 @item @key{RET}
306 Submit the text in the minibuffer as the argument, possibly completing
307 first (@code{minibuffer-complete-and-exit}).  @xref{Completion Exit}.
308 @item ?
309 Display a list of completions (@code{minibuffer-completion-help}).
310 @end table
312 @kindex TAB @r{(completion)}
313 @findex minibuffer-complete
314   @key{TAB} (@code{minibuffer-complete}) is the most fundamental
315 completion command.  It searches for all possible completions that
316 match the existing minibuffer text, and attempts to complete as much
317 as it can.  @xref{Completion Styles}, for how completion alternatives
318 are chosen.
320 @kindex SPC @r{(completion)}
321 @findex minibuffer-complete-word
322   @key{SPC} (@code{minibuffer-complete-word}) completes like
323 @key{TAB}, but only up to the next hyphen or space.  If you have
324 @samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the
325 completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-},
326 giving @samp{auto-fill-}.  Another @key{SPC} at this point completes
327 all the way to @samp{auto-fill-mode}.
329 @kindex ? @r{(completion)}
330 @cindex completion list
331   If @key{TAB} or @key{SPC} is unable to complete, it displays a list
332 of matching completion alternatives (if there are any) in another
333 window.  You can display the same list with @kbd{?}
334 (@code{minibuffer-completion-help}).  The following commands can be
335 used with the completion list:
337 @table @kbd
338 @findex mouse-choose-completion
339 @item Mouse-1
340 @itemx Mouse-2
341 Clicking mouse button 1 or 2 on a completion alternative chooses it
342 (@code{mouse-choose-completion}).
344 @findex switch-to-completions
345 @item M-v
346 @itemx @key{PageUp}
347 @itemx @key{prior}
348 Typing @kbd{M-v}, while in the minibuffer, selects the window showing
349 the completion list (@code{switch-to-completions}).  This paves the
350 way for using the commands below.  @key{PageUp} or @key{prior} does
351 the same.  You can also select the window in other ways
352 (@pxref{Windows}).
354 @findex choose-completion
355 @item @key{RET}
356 While in the completion list buffer, this chooses the completion at
357 point (@code{choose-completion}).
359 @findex next-completion
360 @item @key{RIGHT}
361 While in the completion list buffer, this moves point to the following
362 completion alternative (@code{next-completion}).
364 @findex previous-completion
365 @item @key{LEFT}
366 While in the completion list buffer, this moves point to the previous
367 completion alternative (@code{previous-completion}).
368 @end table
370 @node Completion Exit
371 @subsection Completion Exit
373 @kindex RET @r{(completion in minibuffer)}
374 @findex minibuffer-complete-and-exit
375   When a command reads an argument using the minibuffer with
376 completion, it also controls what happens when you type @key{RET}
377 (@code{minibuffer-complete-and-exit}) to submit the argument.  There
378 are four types of behavior:
380 @itemize @bullet
381 @item
382 @dfn{Strict completion} accepts only exact completion matches.  Typing
383 @key{RET} exits the minibuffer only if the minibuffer text is an exact
384 match, or completes to one.  Otherwise, Emacs refuses to exit the
385 minibuffer; instead it tries to complete, and if no completion can be
386 done it momentarily displays @samp{[No match]} after the minibuffer
387 text.  (You can still leave the minibuffer by typing @kbd{C-g} to
388 cancel the command.)
390 An example of a command that uses this behavior is @kbd{M-x}, since it
391 is meaningless for it to accept a non-existent command name.
393 @item
394 @dfn{Cautious completion} is like strict completion, except @key{RET}
395 exits only if the text is already an exact match.  If the text
396 completes to an exact match, @key{RET} performs that completion but
397 does not exit yet; you must type a second @key{RET} to exit.
399 Cautious completion is used for reading file names for files that must
400 already exist, for example.
402 @item
403 @dfn{Permissive completion} allows any input; the completion
404 candidates are just suggestions.  Typing @key{RET} does not complete,
405 it just submits the argument as you have entered it.
407 @cindex minibuffer confirmation
408 @cindex confirming in the minibuffer
409 @item
410 @dfn{Permissive completion with confirmation} is like permissive
411 completion, with an exception: if you typed @key{TAB} and this
412 completed the text up to some intermediate state (i.e., one that is not
413 yet an exact completion match), typing @key{RET} right afterward does
414 not submit the argument.  Instead, Emacs asks for confirmation by
415 momentarily displaying @samp{[Confirm]} after the text; type @key{RET}
416 again to confirm and submit the text.  This catches a common mistake,
417 in which one types @key{RET} before realizing that @key{TAB} did not
418 complete as far as desired.
420 @vindex confirm-nonexistent-file-or-buffer
421 You can tweak the confirmation behavior by customizing the variable
422 @code{confirm-nonexistent-file-or-buffer}.  The default value,
423 @code{after-completion}, gives the behavior we have just described.
424 If you change it to @code{nil}, Emacs does not ask for confirmation,
425 falling back on permissive completion.  If you change it to any other
426 non-@code{nil} value, Emacs asks for confirmation whether or not the
427 preceding command was @key{TAB}.
429 This behavior is used by most commands that read file names, like
430 @kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}.
431 @end itemize
433 @node Completion Styles
434 @subsection How Completion Alternatives Are Chosen
435 @cindex completion style
437   Completion commands work by narrowing a large list of possible
438 completion alternatives to a smaller subset that ``matches'' what you
439 have typed in the minibuffer.  In @ref{Completion Example}, we gave a
440 simple example of such matching.  The procedure of determining what
441 constitutes a ``match'' is quite intricate.  Emacs attempts to offer
442 plausible completions under most circumstances.
444   Emacs performs completion using one or more @dfn{completion
445 styles}---sets of criteria for matching minibuffer text to completion
446 alternatives.  During completion, Emacs tries each completion style in
447 turn.  If a style yields one or more matches, that is used as the list
448 of completion alternatives.  If a style produces no matches, Emacs
449 falls back on the next style.
451 @vindex completion-styles
452   The list variable @code{completion-styles} specifies the completion
453 styles to use.  Each list element is the name of a completion style (a
454 Lisp symbol).  The default completion styles are (in order):
456 @table @code
457 @item basic
458 A matching completion alternative must have the same beginning as the
459 text in the minibuffer before point.  Furthermore, if there is any
460 text in the minibuffer after point, the rest of the completion
461 alternative must contain that text as a substring.
463 @findex partial completion
464 @item partial-completion
465 This aggressive completion style divides the minibuffer text into
466 words separated by hyphens or spaces, and completes each word
467 separately.  (For example, when completing command names,
468 @samp{em-l-m} completes to @samp{emacs-lisp-mode}.)
470 Furthermore, a @samp{*} in the minibuffer text is treated as a
471 @dfn{wildcard}---it matches any character at the corresponding
472 position in the completion alternative.
474 @item emacs22
475 This completion style is similar to @code{basic}, except that it
476 ignores the text in the minibuffer after point.  It is so-named
477 because it corresponds to the completion behavior in Emacs 22.
478 @end table
480 @noindent
481 The following additional completion styles are also defined, and you
482 can add them to @code{completion-styles} if you wish
483 (@pxref{Customization}):
485 @table @code
486 @item substring
487 A matching completion alternative must contain the text in the
488 minibuffer before point, and the text in the minibuffer after point,
489 as substrings (in that same order).
491 Thus, if the text in the minibuffer is @samp{foobar}, with point
492 between @samp{foo} and @samp{bar}, that matches
493 @samp{@var{a}foo@var{b}bar@var{c}}, where @var{a}, @var{b}, and
494 @var{c} can be any string including the empty string.
496 @item initials
497 This very aggressive completion style attempts to complete acronyms
498 and initialisms.  For example, when completing command names, it
499 matches @samp{lch} to @samp{list-command-history}.
500 @end table
502 @noindent
503 There is also a very simple completion style called @code{emacs21}.
504 In this style, if the text in the minibuffer is @samp{foobar},
505 only matches starting with @samp{foobar} are considered.
507 @vindex completion-category-overrides
508 You can use different completion styles in different situations,
509 by setting the variable @code{completion-category-overrides}.
510 For example, the default setting says to use only @code{basic}
511 and @code{substring} completion for buffer names.
514 @node Completion Options
515 @subsection Completion Options
517 @cindex case-sensitivity and completion
518 @cindex case in completion
519   Case is significant when completing case-sensitive arguments, such
520 as command names.  For example, when completing command names,
521 @samp{AU} does not complete to @samp{auto-fill-mode}.  Case
522 differences are ignored when completing arguments in which case does
523 not matter.
525 @vindex read-file-name-completion-ignore-case
526 @vindex read-buffer-completion-ignore-case
527   When completing file names, case differences are ignored if the
528 variable @code{read-file-name-completion-ignore-case} is
529 non-@code{nil}.  The default value is @code{nil} on systems that have
530 case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on
531 systems that have case-insensitive file-names, such as Microsoft
532 Windows.  When completing buffer names, case differences are ignored
533 if the variable @code{read-buffer-completion-ignore-case} is
534 non-@code{nil}; the default is @code{nil}.
536 @vindex completion-ignored-extensions
537 @cindex ignored file names, in completion
538   When completing file names, Emacs usually omits certain alternatives
539 that are considered unlikely to be chosen, as determined by the list
540 variable @code{completion-ignored-extensions}.  Each element in the
541 list should be a string; any file name ending in such a string is
542 ignored as a completion alternative.  Any element ending in a slash
543 (@file{/}) represents a subdirectory name.  The standard value of
544 @code{completion-ignored-extensions} has several elements including
545 @code{".o"}, @code{".elc"}, and @code{"~"}.  For example, if a
546 directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo}
547 completes to @samp{foo.c}.  However, if @emph{all} possible
548 completions end in ``ignored'' strings, they are not ignored: in the
549 previous example, @samp{foo.e} completes to @samp{foo.elc}.  Emacs
550 disregards @code{completion-ignored-extensions} when showing
551 completion alternatives in the completion list.
553   Shell completion is an extended version of filename completion,
554 @pxref{Shell Options}.
556 @vindex completion-auto-help
557   If @code{completion-auto-help} is set to @code{nil}, the completion
558 commands never display the completion list buffer; you must type
559 @kbd{?}  to display the list.  If the value is @code{lazy}, Emacs only
560 shows the completion list buffer on the second attempt to complete.
561 In other words, if there is nothing to complete, the first @key{TAB}
562 echoes @samp{Next char not unique}; the second @key{TAB} shows the
563 completion list buffer.
565 @vindex completion-cycle-threshold
566   If @code{completion-cycle-threshold} is non-@code{nil}, completion
567 commands can ``cycle'' through completion alternatives.  Normally, if
568 there is more than one completion alternative for the text in the
569 minibuffer, a completion command completes up to the longest common
570 substring.  If you change @code{completion-cycle-threshold} to
571 @code{t}, the completion command instead completes to the first of
572 those completion alternatives; each subsequent invocation of the
573 completion command replaces that with the next completion alternative,
574 in a cyclic manner.  If you give @code{completion-cycle-threshold} a
575 numeric value @var{n}, completion commands switch to this cycling
576 behavior only when there are @var{n} or fewer alternatives.
578 @node Minibuffer History
579 @section Minibuffer History
580 @cindex minibuffer history
581 @cindex history of minibuffer input
583   Every argument that you enter with the minibuffer is saved in a
584 @dfn{minibuffer history list} so you can easily use it again later.
585 You can use the following arguments to quickly fetch an earlier
586 argument into the minibuffer:
588 @table @kbd
589 @item M-p
590 @itemx @key{UP}
591 Move to the previous item in the minibuffer history, an earlier
592 argument (@code{previous-history-element}).
593 @item M-n
594 @itemx @key{DOWN}
595 Move to the next item in the minibuffer history
596 (@code{next-history-element}).
597 @item M-r @var{regexp} @key{RET}
598 Move to an earlier item in the minibuffer history that
599 matches @var{regexp} (@code{previous-matching-history-element}).
600 @item M-s @var{regexp} @key{RET}
601 Move to a later item in the minibuffer history that matches
602 @var{regexp} (@code{next-matching-history-element}).
603 @end table
605 @kindex M-p @r{(minibuffer history)}
606 @kindex M-n @r{(minibuffer history)}
607 @kindex UP @r{(minibuffer history)}
608 @kindex DOWN @r{(minibuffer history)}
609 @findex next-history-element
610 @findex previous-history-element
611   While in the minibuffer, @kbd{M-p} or @key{UP}
612 (@code{previous-history-element}) moves through the minibuffer history
613 list, one item at a time.  Each @kbd{M-p} fetches an earlier item from
614 the history list into the minibuffer, replacing its existing contents.
615 Typing @kbd{M-n} or @key{DOWN} (@code{next-history-element}) moves
616 through the minibuffer history list in the opposite direction,
617 fetching later entries into the minibuffer.
619   If you type @kbd{M-n} in the minibuffer when there are no later
620 entries in the minibuffer history (e.g., if you haven't previously
621 typed @kbd{M-p}), Emacs tries fetching from a list of default
622 arguments: values that you are likely to enter.  You can think of this
623 as moving through the ``future history'' list.
625   If you edit the text inserted by the @kbd{M-p} or @key{M-n}
626 minibuffer history commands, this does not change its entry in the
627 history list.  However, the edited argument does go at the end of the
628 history list when you submit it.
630 @findex previous-matching-history-element
631 @findex next-matching-history-element
632 @kindex M-r @r{(minibuffer history)}
633 @kindex M-s @r{(minibuffer history)}
634   You can use @kbd{M-r} (@code{previous-matching-history-element}) to
635 search through older elements in the history list, and @kbd{M-s}
636 (@code{next-matching-history-element}) to search through newer
637 entries.  Each of these commands asks for a @dfn{regular expression}
638 as an argument, and fetches the first matching entry into the
639 minibuffer.  @xref{Regexps}, for an explanation of regular
640 expressions.  A numeric prefix argument @var{n} means to fetch the
641 @var{n}th matching entry.  These commands are unusual, in that they
642 use the minibuffer to read the regular expression argument, even
643 though they are invoked from the minibuffer.  An upper-case letter in
644 the regular expression makes the search case-sensitive (@pxref{Search
645 Case}).
647   You can also search through the history using an incremental search.
648 @xref{Isearch Minibuffer}.
650   Emacs keeps separate history lists for several different kinds of
651 arguments.  For example, there is a list for file names, used by all
652 the commands that read file names.  Other history lists include buffer
653 names, command names (used by @kbd{M-x}), and command arguments (used
654 by commands like @code{query-replace}).
656 @vindex history-length
657   The variable @code{history-length} specifies the maximum length of a
658 minibuffer history list; adding a new element deletes the oldest
659 element if the list gets too long.  If the value is @code{t}, there is
660 no maximum length.
662 @vindex history-delete-duplicates
663   The variable @code{history-delete-duplicates} specifies whether to
664 delete duplicates in history.  If it is non-@code{nil}, adding a new
665 element deletes from the list all other elements that are equal to it.
666 The default is @code{nil}.
668 @node Repetition
669 @section Repeating Minibuffer Commands
670 @cindex command history
671 @cindex history of commands
673   Every command that uses the minibuffer once is recorded on a special
674 history list, the @dfn{command history}, together with the values of
675 its arguments, so that you can repeat the entire command.  In
676 particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x}
677 uses the minibuffer to read the command name.
679 @findex list-command-history
680 @table @kbd
681 @item C-x @key{ESC} @key{ESC}
682 Re-execute a recent minibuffer command from the command history
683  (@code{repeat-complex-command}).
684 @item M-x list-command-history
685 Display the entire command history, showing all the commands
686 @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
687 @end table
689 @kindex C-x ESC ESC
690 @findex repeat-complex-command
691   @kbd{C-x @key{ESC} @key{ESC}} re-executes a recent command that used
692 the minibuffer.  With no argument, it repeats the last such command.
693 A numeric argument specifies which command to repeat; 1 means the last
694 one, 2 the previous, and so on.
696   @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
697 into a Lisp expression and then entering a minibuffer initialized with
698 the text for that expression.  Even if you don't know Lisp, it will
699 probably be obvious which command is displayed for repetition.  If you
700 type just @key{RET}, that repeats the command unchanged.  You can also
701 change the command by editing the Lisp expression before you execute
702 it.  The executed command is added to the front of the command history
703 unless it is identical to the most recent item.
705   Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you
706 can use the usual minibuffer history commands (@pxref{Minibuffer
707 History}) to move through the history list.  After finding the desired
708 previous command, you can edit its expression as usual and then execute
709 it by typing @key{RET}.
711 @vindex isearch-resume-in-command-history
712   Incremental search does not, strictly speaking, use the minibuffer.
713 Therefore, although it behaves like a complex command, it normally
714 does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}.
715 You can make incremental search commands appear in the history by
716 setting @code{isearch-resume-in-command-history} to a non-@code{nil}
717 value.  @xref{Incremental Search}.
719 @vindex command-history
720   The list of previous minibuffer-using commands is stored as a Lisp
721 list in the variable @code{command-history}.  Each element is a Lisp
722 expression that describes one command and its arguments.  Lisp programs
723 can re-execute a command by calling @code{eval} with the
724 @code{command-history} element.
726 @node Passwords
727 @section Entering passwords
729 Sometimes, you may need to enter a password into Emacs.  For instance,
730 when you tell Emacs to visit a file on another machine via a network
731 protocol such as FTP, you often need to supply a password to gain
732 access to the machine (@pxref{Remote Files}).
734   Entering a password is similar to using a minibuffer.  Emacs
735 displays a prompt in the echo area (such as @samp{Password: }); after
736 you type the required password, press @key{RET} to submit it.  To
737 prevent others from seeing your password, every character you type is
738 displayed as a dot (@samp{.}) instead of its usual form.
740   Most of the features and commands associated with the minibuffer can
741 @emph{not} be used when entering a password.  There is no history or
742 completion, and you cannot change windows or perform any other action
743 with Emacs until you have submitted the password.
745   While you are typing the password, you may press @key{DEL} to delete
746 backwards, removing the last character entered.  @kbd{C-u} deletes
747 everything you have typed so far.  @kbd{C-g} quits the password prompt
748 (@pxref{Quitting}).  @kbd{C-y} inserts the current kill into the
749 password (@pxref{Killing}).  You may type either @key{RET} or
750 @key{ESC} to submit the password.  Any other self-inserting character
751 key inserts the associated character into the password, and all other
752 input is ignored.
754 @node Yes or No Prompts
755 @section Yes or No Prompts
757   An Emacs command may require you to answer a ``yes or no'' question
758 during the course of its execution.  Such queries come in two main
759 varieties.
761 @cindex y or n prompt
762   For the first type of ``yes or no'' query, the prompt ends with
763 @samp{(y or n)}.  Such a query does not actually use the minibuffer;
764 the prompt appears in the echo area, and you answer by typing either
765 @samp{y} or @samp{n}, which immediately delivers the response.  For
766 example, if you type @kbd{C-x C-w} (@kbd{write-file}) to save a
767 buffer, and enter the name of an existing file, Emacs issues a prompt
768 like this:
770 @smallexample
771 File `foo.el' exists; overwrite? (y or n)
772 @end smallexample
774 @noindent
775 Because this query does not actually use the minibuffer, the usual
776 minibuffer editing commands cannot be used.  However, you can perform
777 some window scrolling operations while the query is active: @kbd{C-l}
778 recenters the selected window; @kbd{M-v} (or @key{PageDown} or
779 @key{next}) scrolls forward; @kbd{C-v} (or @key{PageUp}, or
780 @key{prior}) scrolls backward; @kbd{C-M-v} scrolls forward in the next
781 window; and @kbd{C-M-S-v} scrolls backward in the next window.  Typing
782 @kbd{C-g} dismisses the query, and quits the command that issued it
783 (@pxref{Quitting}).
785 @cindex yes or no prompt
786   The second type of ``yes or no'' query is typically employed if
787 giving the wrong answer would have serious consequences; it uses the
788 minibuffer, and features a prompt ending with @samp{(yes or no)}.  For
789 example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a
790 file-visiting buffer with unsaved changes, Emacs activates the
791 minibuffer with a prompt like this:
793 @smallexample
794 Buffer foo.el modified; kill anyway? (yes or no)
795 @end smallexample
797 @noindent
798 To answer, you must type @samp{yes} or @samp{no} into the minibuffer,
799 followed by @key{RET}.  The minibuffer behaves as described in the
800 previous sections; you can switch to another window with @kbd{C-x o},
801 use the history commands @kbd{M-p} and @kbd{M-f}, etc.  Type @kbd{C-g}
802 to quit the minibuffer and the querying command.