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