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