Commit | Line | Data |
---|---|---|
8cf51b2c | 1 | @c This is part of the Emacs manual. |
ab422c4d PE |
2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software |
3 | @c 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 | 15 | |
7d806bfe CY |
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 | |
26 | ||
27 | @node Basic Minibuffer | |
28 | @section Using the Minibuffer | |
29 | ||
8cf51b2c GM |
30 | @cindex prompt |
31 | When the minibuffer is in use, it appears in the echo area, with a | |
7d806bfe CY |
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}). | |
01163003 CY |
36 | |
37 | The simplest way to enter a minibuffer argument is to type the text, | |
7d806bfe CY |
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 | cancelling the command asking for the argument (@pxref{Quitting}). | |
8cf51b2c GM |
41 | |
42 | @cindex default argument | |
7d806bfe | 43 | Sometimes, the prompt shows a @dfn{default argument}, inside |
27a16462 CY |
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. | |
8cf51b2c | 48 | |
7d806bfe CY |
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}. | |
63 | ||
8cf51b2c | 64 | Since the minibuffer appears in the echo area, it can conflict with |
27a16462 CY |
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. | |
8cf51b2c | 70 | |
8cf51b2c GM |
71 | @node Minibuffer File |
72 | @section Minibuffers for File Names | |
73 | ||
27a16462 | 74 | @cindex default directory |
01163003 CY |
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 | |
653ec62b CY |
78 | some initial text ending in a slash. This is the @dfn{default |
79 | directory}. For example, it may start out like this: | |
8cf51b2c GM |
80 | |
81 | @example | |
49fe4321 | 82 | Find file: /u2/emacs/src/ |
8cf51b2c GM |
83 | @end example |
84 | ||
85 | @noindent | |
49fe4321 | 86 | Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is |
01163003 | 87 | the default directory. If you now type @kbd{buffer.c} as input, that |
653ec62b CY |
88 | specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names}, |
89 | for information about the default directory. | |
01163003 | 90 | |
ae742cb5 CY |
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}). | |
01163003 CY |
95 | |
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: | |
8cf51b2c GM |
101 | |
102 | @example | |
49fe4321 | 103 | Find file: /u2/emacs/src//etc/termcap |
8cf51b2c GM |
104 | @end example |
105 | ||
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 | |
01163003 | 111 | Emacs interprets a double slash as ``ignore everything before the |
16152b76 | 112 | second slash in the pair''. In the example above, |
2d6fc764 | 113 | @file{/u2/emacs/src/} is ignored, so the argument you supplied is |
653ec62b | 114 | @file{/etc/termcap}. The ignored part of the file name is dimmed if |
27a16462 | 115 | the terminal allows it. (To disable this dimming, turn off File Name |
653ec62b CY |
116 | Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) |
117 | ||
118 | @cindex home directory shorthand | |
2d6fc764 EZ |
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 | |
653ec62b | 122 | directory. In addition, @file{~@var{user-id}/} means the home |
2d6fc764 EZ |
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}. | |
126 | ||
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 | |
27a16462 | 131 | @ref{MS-DOS File Names}. |
2d6fc764 EZ |
132 | @end ifnottex |
133 | @iftex | |
27a16462 CY |
134 | @ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of |
135 | the Emacs Manual}. | |
2d6fc764 EZ |
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. | |
653ec62b CY |
140 | |
141 | @vindex insert-default-directory | |
01163003 CY |
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. | |
8cf51b2c | 147 | |
27a16462 CY |
148 | You can also enter remote file names in the minibuffer. |
149 | @xref{Remote Files}. | |
fe676f91 | 150 | |
8cf51b2c GM |
151 | @node Minibuffer Edit |
152 | @section Editing in the Minibuffer | |
153 | ||
01163003 | 154 | The minibuffer is an Emacs buffer, albeit a peculiar one, and the |
8cf51b2c | 155 | usual Emacs commands are available for editing the argument text. |
01163003 | 156 | (The prompt, however, is @dfn{read-only}, and cannot be changed.) |
8cf51b2c | 157 | |
27a16462 CY |
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}). | |
8cf51b2c | 163 | |
27a16462 CY |
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. | |
01163003 CY |
169 | |
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}. | |
8cf51b2c GM |
174 | |
175 | @cindex height of minibuffer | |
176 | @cindex size of minibuffer | |
177 | @cindex growing minibuffer | |
178 | @cindex resizing minibuffer | |
01163003 CY |
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}. | |
8cf51b2c GM |
186 | |
187 | @vindex resize-mini-windows | |
01163003 CY |
188 | Normally, the minibuffer window occupies a single screen line. |
189 | However, if you add two or more lines' worth of text into the | |
7ee6a1d3 | 190 | minibuffer, it expands automatically to accommodate the text. The |
01163003 CY |
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}). | |
8cf51b2c GM |
199 | |
200 | @vindex max-mini-window-height | |
201 | The variable @code{max-mini-window-height} controls the maximum | |
01163003 | 202 | height for resizing the minibuffer window. A floating-point number |
8cf51b2c GM |
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. | |
206 | ||
207 | The @kbd{C-M-v} command in the minibuffer scrolls the help text from | |
b5700de6 CY |
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}. | |
8cf51b2c GM |
213 | |
214 | @vindex enable-recursive-minibuffers | |
215 | Emacs normally disallows most commands that use the minibuffer while | |
01163003 CY |
216 | the minibuffer is active. To allow such commands in the minibuffer, |
217 | set the variable @code{enable-recursive-minibuffers} to @code{t}. | |
8cf51b2c | 218 | |
104dc9c6 GM |
219 | @findex minibuffer-inactive-mode |
220 | When not active, the minibuffer is in @code{minibuffer-inactive-mode}, | |
1c64e6ed | 221 | and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer. |
104dc9c6 GM |
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. | |
224 | ||
8cf51b2c GM |
225 | @node Completion |
226 | @section Completion | |
59eda47f RS |
227 | @c This node is referenced in the tutorial. When renaming or deleting |
228 | @c it, the tutorial needs to be adjusted. | |
8cf51b2c | 229 | @cindex completion |
01163003 | 230 | |
27a16462 CY |
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. | |
01163003 | 234 | |
27a16462 | 235 | @cindex completion alternative |
01163003 | 236 | When completion is available, certain keys (usually @key{TAB}, |
27a16462 CY |
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. | |
243 | ||
244 | Although completion is usually done in the minibuffer, the feature | |
245 | is sometimes available in ordinary buffers too. @xref{Symbol | |
246 | Completion}. | |
8cf51b2c | 247 | |
8cf51b2c | 248 | @menu |
a70e06c1 CY |
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. | |
8cf51b2c GM |
254 | @end menu |
255 | ||
256 | @node Completion Example | |
257 | @subsection Completion Example | |
258 | ||
259 | @kindex TAB @r{(completion)} | |
27a16462 CY |
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. | |
266 | ||
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 | |
49fe4321 GM |
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}.) | |
8cf51b2c GM |
275 | |
276 | If you type @key{TAB} again immediately, it cannot determine the | |
01163003 CY |
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. | |
8cf51b2c | 280 | |
27a16462 CY |
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. | |
285 | ||
286 | Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to | |
287 | enter @samp{auto-fill-mode}. | |
8cf51b2c GM |
288 | |
289 | @node Completion Commands | |
290 | @subsection Completion Commands | |
291 | ||
292 | Here is a list of the completion commands defined in the minibuffer | |
293 | when completion is allowed. | |
294 | ||
295 | @table @kbd | |
296 | @item @key{TAB} | |
297 | @findex minibuffer-complete | |
7fb1a584 CY |
298 | Complete the text in the minibuffer as much as possible; if unable to |
299 | complete, display a list of possible completions | |
8cf51b2c GM |
300 | (@code{minibuffer-complete}). |
301 | @item @key{SPC} | |
302 | Complete up to one word from the minibuffer text before point | |
27a16462 CY |
303 | (@code{minibuffer-complete-word}). This command is not available for |
304 | arguments that often include spaces, such as file names. | |
8cf51b2c GM |
305 | @item @key{RET} |
306 | Submit the text in the minibuffer as the argument, possibly completing | |
a70e06c1 | 307 | first (@code{minibuffer-complete-and-exit}). @xref{Completion Exit}. |
8cf51b2c | 308 | @item ? |
27a16462 | 309 | Display a list of completions (@code{minibuffer-completion-help}). |
8cf51b2c GM |
310 | @end table |
311 | ||
27a16462 | 312 | @kindex TAB @r{(completion)} |
7fb1a584 CY |
313 | @findex minibuffer-complete |
314 | @key{TAB} (@code{minibuffer-complete}) is the most fundamental | |
27a16462 CY |
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. | |
7fb1a584 | 319 | |
27a16462 | 320 | @kindex SPC @r{(completion)} |
8cf51b2c | 321 | @findex minibuffer-complete-word |
01163003 CY |
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}. | |
8cf51b2c | 328 | |
27a16462 CY |
329 | @kindex ? @r{(completion)} |
330 | @cindex completion list | |
7fb1a584 | 331 | If @key{TAB} or @key{SPC} is unable to complete, it displays a list |
27a16462 CY |
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: | |
8cf51b2c GM |
336 | |
337 | @table @kbd | |
338 | @findex mouse-choose-completion | |
339 | @item Mouse-1 | |
340 | @itemx Mouse-2 | |
27a16462 CY |
341 | Clicking mouse button 1 or 2 on a completion alternative chooses it |
342 | (@code{mouse-choose-completion}). | |
8cf51b2c GM |
343 | |
344 | @findex switch-to-completions | |
01163003 CY |
345 | @item M-v |
346 | @itemx @key{PageUp} | |
b5700de6 | 347 | @itemx @key{prior} |
01163003 | 348 | Typing @kbd{M-v}, while in the minibuffer, selects the window showing |
27a16462 CY |
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}). | |
8cf51b2c GM |
353 | |
354 | @findex choose-completion | |
355 | @item @key{RET} | |
27a16462 CY |
356 | While in the completion list buffer, this chooses the completion at |
357 | point (@code{choose-completion}). | |
8cf51b2c GM |
358 | |
359 | @findex next-completion | |
01163003 | 360 | @item @key{Right} |
27a16462 CY |
361 | While in the completion list buffer, this moves point to the following |
362 | completion alternative (@code{next-completion}). | |
8cf51b2c GM |
363 | |
364 | @findex previous-completion | |
01163003 | 365 | @item @key{Left} |
27a16462 CY |
366 | While in the completion list buffer, this moves point to the previous |
367 | completion alternative (@code{previous-completion}). | |
8cf51b2c GM |
368 | @end table |
369 | ||
a70e06c1 CY |
370 | @node Completion Exit |
371 | @subsection Completion Exit | |
8cf51b2c | 372 | |
a70e06c1 CY |
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: | |
8cf51b2c GM |
379 | |
380 | @itemize @bullet | |
381 | @item | |
a70e06c1 CY |
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.) | |
389 | ||
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. | |
8cf51b2c GM |
392 | |
393 | @item | |
a70e06c1 CY |
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. | |
8cf51b2c GM |
398 | |
399 | Cautious completion is used for reading file names for files that must | |
400 | already exist, for example. | |
401 | ||
402 | @item | |
a70e06c1 CY |
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. | |
8cf51b2c | 406 | |
a70e06c1 CY |
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 | |
49fe4321 | 412 | completed the text up to some intermediate state (i.e., one that is not |
a70e06c1 CY |
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. | |
419 | ||
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}. | |
428 | ||
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 | |
27a16462 CY |
432 | |
433 | @node Completion Styles | |
434 | @subsection How Completion Alternatives Are Chosen | |
435 | @cindex completion style | |
436 | ||
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. | |
443 | ||
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. | |
450 | ||
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): | |
455 | ||
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. | |
462 | ||
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}.) | |
469 | ||
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. | |
473 | ||
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 | |
49fe4321 | 477 | because it corresponds to the completion behavior in Emacs 22. |
27a16462 CY |
478 | @end table |
479 | ||
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}): | |
484 | ||
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). | |
490 | ||
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. | |
495 | ||
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 | |
8cf51b2c | 501 | |
49fe4321 GM |
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. | |
506 | ||
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. | |
512 | ||
513 | ||
8cf51b2c GM |
514 | @node Completion Options |
515 | @subsection Completion Options | |
516 | ||
27a16462 CY |
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. | |
524 | ||
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 | |
de09aa52 CY |
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}. | |
27a16462 CY |
535 | |
536 | @vindex completion-ignored-extensions | |
537 | @cindex ignored file names, in completion | |
538 | When completing file names, Emacs usually omits certain alternatives | |
de09aa52 CY |
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} | |
27a16462 CY |
547 | completes to @samp{foo.c}. However, if @emph{all} possible |
548 | completions end in ``ignored'' strings, they are not ignored: in the | |
de09aa52 CY |
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. | |
27a16462 | 552 | |
fdadeb49 JC |
553 | Shell completion is an extended version of filename completion, |
554 | @pxref{Shell Options}. | |
555 | ||
01163003 CY |
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} | |
49fe4321 | 562 | echoes @samp{Next char not unique}; the second @key{TAB} shows the |
867d4bb3 | 563 | completion list buffer. |
01163003 | 564 | |
de09aa52 CY |
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 | |
f42f1094 | 576 | behavior only when there are @var{n} or fewer alternatives. |
8cf51b2c | 577 | |
8cf51b2c GM |
578 | @cindex Icomplete mode |
579 | @findex icomplete-mode | |
580 | Icomplete mode presents a constantly-updated display that tells you | |
581 | what completions are available for the text you've entered so far. The | |
582 | command to enable or disable this minor mode is @kbd{M-x | |
583 | icomplete-mode}. | |
584 | ||
585 | @node Minibuffer History | |
586 | @section Minibuffer History | |
587 | @cindex minibuffer history | |
588 | @cindex history of minibuffer input | |
589 | ||
01163003 | 590 | Every argument that you enter with the minibuffer is saved in a |
8cf51b2c | 591 | @dfn{minibuffer history list} so you can easily use it again later. |
01163003 CY |
592 | You can use the following arguments to quickly fetch an earlier |
593 | argument into the minibuffer: | |
8cf51b2c GM |
594 | |
595 | @table @kbd | |
01163003 CY |
596 | @item M-p |
597 | @itemx @key{Up} | |
598 | Move to the previous item in the minibuffer history, an earlier | |
599 | argument (@code{previous-history-element}). | |
600 | @item M-n | |
601 | @itemx @key{Down} | |
8cf51b2c GM |
602 | Move to the next item in the minibuffer history |
603 | (@code{next-history-element}). | |
604 | @item M-r @var{regexp} @key{RET} | |
fe676f91 | 605 | Move to an earlier item in the minibuffer history that |
8cf51b2c GM |
606 | matches @var{regexp} (@code{previous-matching-history-element}). |
607 | @item M-s @var{regexp} @key{RET} | |
608 | Move to a later item in the minibuffer history that matches | |
609 | @var{regexp} (@code{next-matching-history-element}). | |
610 | @end table | |
611 | ||
612 | @kindex M-p @r{(minibuffer history)} | |
613 | @kindex M-n @r{(minibuffer history)} | |
3dc62b2b CY |
614 | @kindex UP @r{(minibuffer history)} |
615 | @kindex DOWN @r{(minibuffer history)} | |
8cf51b2c GM |
616 | @findex next-history-element |
617 | @findex previous-history-element | |
3dc62b2b CY |
618 | While in the minibuffer, @kbd{M-p} or @key{Up} |
619 | (@code{previous-history-element}) moves through the minibuffer history | |
620 | list, one item at a time. Each @kbd{M-p} fetches an earlier item from | |
621 | the history list into the minibuffer, replacing its existing contents. | |
622 | Typing @kbd{M-n} or @key{Down} (@code{next-history-element}) moves | |
623 | through the minibuffer history list in the opposite direction, | |
624 | fetching later entries into the minibuffer. | |
01163003 CY |
625 | |
626 | If you type @kbd{M-n} in the minibuffer when there are no later | |
627 | entries in the minibuffer history (e.g., if you haven't previously | |
628 | typed @kbd{M-p}), Emacs tries fetching from a list of default | |
3dc62b2b CY |
629 | arguments: values that you are likely to enter. You can think of this |
630 | as moving through the ``future history'' list. | |
01163003 | 631 | |
3dc62b2b CY |
632 | If you edit the text inserted by the @kbd{M-p} or @key{M-n} |
633 | minibuffer history commands, this does not change its entry in the | |
634 | history list. However, the edited argument does go at the end of the | |
635 | history list when you submit it. | |
8cf51b2c GM |
636 | |
637 | @findex previous-matching-history-element | |
638 | @findex next-matching-history-element | |
639 | @kindex M-r @r{(minibuffer history)} | |
640 | @kindex M-s @r{(minibuffer history)} | |
3dc62b2b CY |
641 | You can use @kbd{M-r} (@code{previous-matching-history-element}) to |
642 | search through older elements in the history list, and @kbd{M-s} | |
643 | (@code{next-matching-history-element}) to search through newer | |
644 | entries. Each of these commands asks for a @dfn{regular expression} | |
645 | as an argument, and fetches the first matching entry into the | |
646 | minibuffer. @xref{Regexps}, for an explanation of regular | |
647 | expressions. A numeric prefix argument @var{n} means to fetch the | |
648 | @var{n}th matching entry. These commands are unusual, in that they | |
649 | use the minibuffer to read the regular expression argument, even | |
650 | though they are invoked from the minibuffer. An upper-case letter in | |
651 | the regular expression makes the search case-sensitive (@pxref{Search | |
652 | Case}). | |
653 | ||
654 | You can also search through the history using an incremental search. | |
655 | @xref{Isearch Minibuffer}. | |
656 | ||
657 | Emacs keeps separate history lists for several different kinds of | |
658 | arguments. For example, there is a list for file names, used by all | |
659 | the commands that read file names. Other history lists include buffer | |
660 | names, command names (used by @kbd{M-x}), and command arguments (used | |
661 | by commands like @code{query-replace}). | |
8cf51b2c GM |
662 | |
663 | @vindex history-length | |
664 | The variable @code{history-length} specifies the maximum length of a | |
665 | minibuffer history list; adding a new element deletes the oldest | |
3dc62b2b CY |
666 | element if the list gets too long. If the value is @code{t}, there is |
667 | no maximum length. | |
8cf51b2c GM |
668 | |
669 | @vindex history-delete-duplicates | |
670 | The variable @code{history-delete-duplicates} specifies whether to | |
01163003 CY |
671 | delete duplicates in history. If it is non-@code{nil}, adding a new |
672 | element deletes from the list all other elements that are equal to it. | |
673 | The default is @code{nil}. | |
8cf51b2c GM |
674 | |
675 | @node Repetition | |
676 | @section Repeating Minibuffer Commands | |
677 | @cindex command history | |
678 | @cindex history of commands | |
679 | ||
680 | Every command that uses the minibuffer once is recorded on a special | |
681 | history list, the @dfn{command history}, together with the values of | |
682 | its arguments, so that you can repeat the entire command. In | |
683 | particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} | |
684 | uses the minibuffer to read the command name. | |
685 | ||
686 | @findex list-command-history | |
687 | @table @kbd | |
688 | @item C-x @key{ESC} @key{ESC} | |
689 | Re-execute a recent minibuffer command from the command history | |
690 | (@code{repeat-complex-command}). | |
691 | @item M-x list-command-history | |
692 | Display the entire command history, showing all the commands | |
693 | @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. | |
694 | @end table | |
695 | ||
696 | @kindex C-x ESC ESC | |
697 | @findex repeat-complex-command | |
3dc62b2b CY |
698 | @kbd{C-x @key{ESC} @key{ESC}} re-executes a recent command that used |
699 | the minibuffer. With no argument, it repeats the last such command. | |
700 | A numeric argument specifies which command to repeat; 1 means the last | |
701 | one, 2 the previous, and so on. | |
8cf51b2c GM |
702 | |
703 | @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command | |
704 | into a Lisp expression and then entering a minibuffer initialized with | |
3dc62b2b CY |
705 | the text for that expression. Even if you don't know Lisp, it will |
706 | probably be obvious which command is displayed for repetition. If you | |
707 | type just @key{RET}, that repeats the command unchanged. You can also | |
708 | change the command by editing the Lisp expression before you execute | |
6c24e35f | 709 | it. The executed command is added to the front of the command history |
3dc62b2b CY |
710 | unless it is identical to the most recent item. |
711 | ||
712 | Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you | |
713 | can use the usual minibuffer history commands (@pxref{Minibuffer | |
714 | History}) to move through the history list. After finding the desired | |
429cdb05 | 715 | previous command, you can edit its expression as usual and then execute |
3dc62b2b | 716 | it by typing @key{RET}. |
8cf51b2c GM |
717 | |
718 | @vindex isearch-resume-in-command-history | |
719 | Incremental search does not, strictly speaking, use the minibuffer. | |
720 | Therefore, although it behaves like a complex command, it normally | |
721 | does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. | |
722 | You can make incremental search commands appear in the history by | |
723 | setting @code{isearch-resume-in-command-history} to a non-@code{nil} | |
724 | value. @xref{Incremental Search}. | |
725 | ||
726 | @vindex command-history | |
727 | The list of previous minibuffer-using commands is stored as a Lisp | |
728 | list in the variable @code{command-history}. Each element is a Lisp | |
49fe4321 | 729 | expression that describes one command and its arguments. Lisp programs |
8cf51b2c GM |
730 | can re-execute a command by calling @code{eval} with the |
731 | @code{command-history} element. | |
732 | ||
2760fefb CY |
733 | @node Passwords |
734 | @section Entering passwords | |
735 | ||
736 | Sometimes, you may need to enter a password into Emacs. For instance, | |
737 | when you tell Emacs to visit a file on another machine via a network | |
738 | protocol such as FTP, you often need to supply a password to gain | |
739 | access to the machine (@pxref{Remote Files}). | |
740 | ||
3dc62b2b CY |
741 | Entering a password is similar to using a minibuffer. Emacs |
742 | displays a prompt in the echo area (such as @samp{Password: }); after | |
743 | you type the required password, press @key{RET} to submit it. To | |
744 | prevent others from seeing your password, every character you type is | |
745 | displayed as a dot (@samp{.}) instead of its usual form. | |
2760fefb CY |
746 | |
747 | Most of the features and commands associated with the minibuffer can | |
748 | @emph{not} be used when entering a password. There is no history or | |
749 | completion, and you cannot change windows or perform any other action | |
750 | with Emacs until you have submitted the password. | |
751 | ||
752 | While you are typing the password, you may press @key{DEL} to delete | |
c6b68a28 | 753 | backwards, removing the last character entered. @kbd{C-u} deletes |
2760fefb CY |
754 | everything you have typed so far. @kbd{C-g} quits the password prompt |
755 | (@pxref{Quitting}). @kbd{C-y} inserts the current kill into the | |
756 | password (@pxref{Killing}). You may type either @key{RET} or | |
757 | @key{ESC} to submit the password. Any other self-inserting character | |
758 | key inserts the associated character into the password, and all other | |
759 | input is ignored. | |
48de8b12 CY |
760 | |
761 | @node Yes or No Prompts | |
762 | @section Yes or No Prompts | |
763 | ||
764 | An Emacs command may require you to answer a ``yes or no'' question | |
765 | during the course of its execution. Such queries come in two main | |
766 | varieties. | |
767 | ||
768 | @cindex y or n prompt | |
769 | For the first type of ``yes or no'' query, the prompt ends with | |
770 | @samp{(y or n)}. Such a query does not actually use the minibuffer; | |
771 | the prompt appears in the echo area, and you answer by typing either | |
772 | @samp{y} or @samp{n}, which immediately delivers the response. For | |
773 | example, if you type @kbd{C-x C-w} (@kbd{write-file}) to save a | |
774 | buffer, and enter the name of an existing file, Emacs issues a prompt | |
775 | like this: | |
776 | ||
777 | @smallexample | |
778 | File `foo.el' exists; overwrite? (y or n) | |
779 | @end smallexample | |
780 | ||
781 | @noindent | |
782 | Because this query does not actually use the minibuffer, the usual | |
783 | minibuffer editing commands cannot be used. However, you can perform | |
784 | some window scrolling operations while the query is active: @kbd{C-l} | |
785 | recenters the selected window; @kbd{M-v} (or @key{PageDown} or | |
786 | @key{next}) scrolls forward; @kbd{C-v} (or @key{PageUp}, or | |
787 | @key{prior}) scrolls backward; @kbd{C-M-v} scrolls forward in the next | |
788 | window; and @kbd{C-M-S-v} scrolls backward in the next window. Typing | |
789 | @kbd{C-g} dismisses the query, and quits the command that issued it | |
790 | (@pxref{Quitting}). | |
791 | ||
792 | @cindex yes or no prompt | |
793 | The second type of ``yes or no'' query is typically employed if | |
794 | giving the wrong answer would have serious consequences; it uses the | |
795 | minibuffer, and features a prompt ending with @samp{(yes or no)}. For | |
796 | example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a | |
797 | file-visiting buffer with unsaved changes, Emacs activates the | |
798 | minibuffer with a prompt like this: | |
799 | ||
800 | @smallexample | |
801 | Buffer foo.el modified; kill anyway? (yes or no) | |
802 | @end smallexample | |
803 | ||
804 | @noindent | |
805 | To answer, you must type @samp{yes} or @samp{no} into the minibuffer, | |
806 | followed by @key{RET}. The minibuffer behaves as described in the | |
807 | previous sections; you can switch to another window with @kbd{C-x o}, | |
808 | use the history commands @kbd{M-p} and @kbd{M-f}, etc. Type @kbd{C-g} | |
809 | to quit the minibuffer and the querying command. |