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