Commit | Line | Data |
---|---|---|
8cf51b2c | 1 | @c This is part of the Emacs manual. |
73b0cd50 | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 |
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 | |
18 | cursor. The minibuffer display starts with a @dfn{prompt} in a | |
01163003 CY |
19 | distinct color, usually ending with a colon. The prompt states what |
20 | kind of input is expected, and how it will be used. | |
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 |
8cf51b2c GM |
29 | parentheses before the colon. The default will be used as the |
30 | argument value if you just type @key{RET}. For example, commands that | |
01163003 CY |
31 | read buffer names usually show a buffer name as the default; you can |
32 | type @key{RET} to operate on that default buffer. | |
8cf51b2c GM |
33 | |
34 | Since the minibuffer appears in the echo area, it can conflict with | |
01163003 CY |
35 | other uses of the echo area. If an error occurs while the minibuffer |
36 | is active, the error message hides the minibuffer for a few seconds, | |
37 | or until you type something; then the minibuffer comes back. If a | |
38 | command such as @kbd{C-x =} needs to display a message in the echo | |
39 | area, the message hides the minibuffer for a few seconds, or until you | |
40 | type something; then the minibuffer comes back. While the minibuffer | |
41 | is in use, keystrokes do not echo. | |
8cf51b2c GM |
42 | |
43 | @menu | |
01163003 CY |
44 | * Minibuffer File:: Entering file names with the minibuffer. |
45 | * Minibuffer Edit:: How to edit in the minibuffer. | |
8838673e | 46 | * Completion:: An abbreviation facility for minibuffer input. |
8cf51b2c | 47 | * Minibuffer History:: Reusing recent minibuffer arguments. |
8838673e | 48 | * Repetition:: Re-executing commands that used the minibuffer. |
2760fefb | 49 | * Passwords:: Entering passwords in the echo area. |
8cf51b2c GM |
50 | @end menu |
51 | ||
52 | @node Minibuffer File | |
53 | @section Minibuffers for File Names | |
54 | ||
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 | |
62 | Find File: /u2/emacs/src/ | |
63 | @end example | |
64 | ||
65 | @noindent | |
01163003 CY |
66 | Here, @samp{Find File:@: } is the prompt and @samp{/u2/emacs/src/} is |
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 | |
83 | Find File: /u2/emacs/src//etc/termcap | |
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 CY |
91 | Emacs interprets a double slash as ``ignore everything before the |
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 CY |
94 | @file{/etc/termcap}. The ignored part of the file name is dimmed if |
95 | the terminal allows it (to disable this dimming, turn off File Name | |
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 | |
111 | @ref{MS-DOS File Names, HOME on MS-DOS}. | |
112 | @end ifnottex | |
113 | @iftex | |
114 | @ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the Emacs Manual}, in | |
115 | the main Emacs manual. | |
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 | |
9a70f03d PE |
128 | For rules how to read remote file names in the minibuffer, see |
129 | @ref{Filename completion, file name completion,, tramp}, in the Tramp | |
130 | manual. | |
131 | ||
8cf51b2c GM |
132 | @node Minibuffer Edit |
133 | @section Editing in the Minibuffer | |
134 | ||
01163003 | 135 | The minibuffer is an Emacs buffer, albeit a peculiar one, and the |
8cf51b2c | 136 | usual Emacs commands are available for editing the argument text. |
01163003 | 137 | (The prompt, however, is @dfn{read-only}, and cannot be changed.) |
8cf51b2c GM |
138 | |
139 | Since @key{RET} in the minibuffer is defined to exit the minibuffer, | |
140 | you can't use it to insert a newline in the minibuffer. To do that, | |
141 | type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the | |
142 | @acronym{ASCII} character control-J.) | |
143 | ||
01163003 CY |
144 | Inside a minibuffer, the keys @kbd{@key{TAB}}, @kbd{@key{SPC}}, and |
145 | @kbd{@key{?}} are often bound to commands that perform | |
146 | @dfn{completion}. @xref{Completion}. You can use @kbd{C-q} | |
147 | (@code{quoted-insert}) to insert a @key{TAB}, @key{SPC}, or @key{?} | |
148 | character. For example, @kbd{C-q @key{TAB}} inserts a @key{TAB} | |
149 | character. @xref{Inserting Text}. | |
150 | ||
151 | For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a | |
152 | minibuffer moves point to the beginning of the argument text, not the | |
153 | beginning of the prompt. For example, this allows you to erase the | |
154 | entire argument with @kbd{C-a C-k}. | |
8cf51b2c GM |
155 | |
156 | @cindex height of minibuffer | |
157 | @cindex size of minibuffer | |
158 | @cindex growing minibuffer | |
159 | @cindex resizing minibuffer | |
01163003 CY |
160 | When the minibuffer is active, the echo area is treated much like an |
161 | ordinary Emacs window. For instance, you can switch to another window | |
162 | (with @kbd{C-x o}), edit text there, then return to the minibuffer | |
163 | window to finish the argument. You can even kill text in another | |
164 | window, return to the minibuffer window, and yank the text into the | |
165 | argument. There are some restrictions on the minibuffer window, | |
166 | however: for instance, you cannot split it. @xref{Windows}. | |
8cf51b2c GM |
167 | |
168 | @vindex resize-mini-windows | |
01163003 CY |
169 | Normally, the minibuffer window occupies a single screen line. |
170 | However, if you add two or more lines' worth of text into the | |
7ee6a1d3 | 171 | minibuffer, it expands automatically to accommodate the text. The |
01163003 CY |
172 | variable @code{resize-mini-windows} controls the resizing of the |
173 | minibuffer. The default value is @code{grow-only}, which means the | |
174 | behavior we have just described. If the value is @code{t}, the | |
175 | minibuffer window will also shrink automatically if you remove some | |
176 | lines of text from the minibuffer, down to a minimum of one screen | |
177 | line. If the value is @code{nil}, the minibuffer window never changes | |
178 | size automatically, but you can use the usual window-resizing commands | |
179 | on it (@pxref{Windows}). | |
8cf51b2c GM |
180 | |
181 | @vindex max-mini-window-height | |
182 | The variable @code{max-mini-window-height} controls the maximum | |
01163003 | 183 | height for resizing the minibuffer window. A floating-point number |
8cf51b2c GM |
184 | specifies a fraction of the frame's height; an integer specifies the |
185 | maximum number of lines; @code{nil} means do not resize the minibuffer | |
186 | window automatically. The default value is 0.25. | |
187 | ||
188 | The @kbd{C-M-v} command in the minibuffer scrolls the help text from | |
b5700de6 CY |
189 | commands that display help text of any sort in another window. You |
190 | can also scroll the help text with @kbd{M-@key{prior}} and | |
191 | @kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and | |
192 | @kbd{M-@key{PageDown}}). This is especially useful with long lists of | |
193 | possible completions. @xref{Other Window}. | |
8cf51b2c GM |
194 | |
195 | @vindex enable-recursive-minibuffers | |
196 | Emacs normally disallows most commands that use the minibuffer while | |
01163003 CY |
197 | the minibuffer is active. To allow such commands in the minibuffer, |
198 | set the variable @code{enable-recursive-minibuffers} to @code{t}. | |
8cf51b2c GM |
199 | |
200 | @node Completion | |
201 | @section Completion | |
59eda47f RS |
202 | @c This node is referenced in the tutorial. When renaming or deleting |
203 | @c it, the tutorial needs to be adjusted. | |
8cf51b2c | 204 | @cindex completion |
01163003 CY |
205 | |
206 | Sometimes, you can use a feature called @dfn{completion} to help you | |
207 | enter arguments. This means that after you type part of the argument, | |
208 | Emacs can fill in the rest, or some of it, based on what you have | |
209 | typed so far. | |
210 | ||
211 | When completion is available, certain keys (usually @key{TAB}, | |
212 | @key{RET}, and @key{SPC}) are rebound to complete the text in the | |
213 | minibuffer into a longer string chosen from a set of @dfn{completion | |
214 | alternatives}. The set of completion alternatives depends on the | |
215 | command that requested the argument, and on what you have typed so | |
216 | far. In addition, you can usually type @kbd{?} to display a list of | |
217 | possible completions. | |
8cf51b2c GM |
218 | |
219 | For example, @kbd{M-x} uses the minibuffer to read the name of a | |
01163003 CY |
220 | command, so completion works by matching the minibuffer text against |
221 | the names of existing Emacs commands. So, to run the command | |
222 | @code{insert-buffer}, you can type @kbd{M-x ins @key{SPC} b @key{RET}} | |
223 | instead of the full @kbd{M-x insert-buffer @key{RET}}. | |
8cf51b2c GM |
224 | |
225 | Case is significant in completion when it is significant in the | |
01163003 CY |
226 | argument you are entering, such as command names. Thus, |
227 | @samp{insert-buffer} is not a valid completion for @samp{IN}. | |
8cf51b2c GM |
228 | Completion ignores case distinctions for certain arguments in which |
229 | case does not matter. | |
230 | ||
8cf51b2c GM |
231 | @menu |
232 | * Example: Completion Example. Examples of using completion. | |
233 | * Commands: Completion Commands. A list of completion commands. | |
234 | * Strict Completion:: Different types of completion. | |
235 | * Options: Completion Options. Options for completion. | |
236 | @end menu | |
237 | ||
238 | @node Completion Example | |
239 | @subsection Completion Example | |
240 | ||
241 | @kindex TAB @r{(completion)} | |
01163003 | 242 | A concrete example may help here. If you type @kbd{M-x a u |
8cf51b2c GM |
243 | @key{TAB}}, the @key{TAB} looks for alternatives (in this case, |
244 | command names) that start with @samp{au}. There are several, | |
01163003 CY |
245 | including @code{auto-fill-mode} and @code{autoconf-mode}, but they all |
246 | begin with @code{auto}, so the @samp{au} in the minibuffer completes | |
247 | to @samp{auto}. | |
8cf51b2c GM |
248 | |
249 | If you type @key{TAB} again immediately, it cannot determine the | |
01163003 CY |
250 | next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it |
251 | does not add any characters; instead, @key{TAB} displays a list of all | |
252 | possible completions in another window. | |
8cf51b2c | 253 | |
01163003 CY |
254 | Next, type @kbd{- f}. The minibuffer now contains @samp{auto-f}, |
255 | and the only command name that starts with this is | |
256 | @code{auto-fill-mode}. If you now type @key{TAB}, completion fills in | |
257 | the rest of the argument @samp{auto-fill-mode} into the minibuffer. | |
258 | You have been able to enter @samp{auto-fill-mode} by typing just | |
259 | @kbd{a u @key{TAB} - f @key{TAB}}. | |
8cf51b2c GM |
260 | |
261 | @node Completion Commands | |
262 | @subsection Completion Commands | |
263 | ||
264 | Here is a list of the completion commands defined in the minibuffer | |
265 | when completion is allowed. | |
266 | ||
267 | @table @kbd | |
268 | @item @key{TAB} | |
269 | @findex minibuffer-complete | |
7fb1a584 CY |
270 | Complete the text in the minibuffer as much as possible; if unable to |
271 | complete, display a list of possible completions | |
8cf51b2c GM |
272 | (@code{minibuffer-complete}). |
273 | @item @key{SPC} | |
274 | Complete up to one word from the minibuffer text before point | |
275 | (@code{minibuffer-complete-word}). @key{SPC} for completion is not | |
276 | available when entering a file name, since file names often include | |
277 | spaces. | |
278 | @item @key{RET} | |
279 | Submit the text in the minibuffer as the argument, possibly completing | |
01163003 | 280 | first as described in the next |
8cf51b2c | 281 | @iftex |
01163003 | 282 | subsection (@code{minibuffer-complete-and-exit}). |
8cf51b2c GM |
283 | @end iftex |
284 | @ifnottex | |
01163003 | 285 | node (@code{minibuffer-complete-and-exit}). @xref{Strict Completion}. |
8cf51b2c GM |
286 | @end ifnottex |
287 | @item ? | |
288 | Display a list of possible completions of the text before point | |
289 | (@code{minibuffer-completion-help}). | |
290 | @end table | |
291 | ||
7fb1a584 CY |
292 | @kindex TAB |
293 | @findex minibuffer-complete | |
294 | @key{TAB} (@code{minibuffer-complete}) is the most fundamental | |
295 | completion command. It searches for all possible completion | |
296 | alternatives that match the existing minibuffer text, and attempts to | |
297 | complete as much as it can. The matching of completion alternatives | |
298 | to the minibuffer text is performed according to somewhat intricate | |
299 | rules, which are designed so that plausible completions are offered | |
300 | under most circumstances. A valid completion alternative must satisfy | |
301 | the following criteria: | |
302 | ||
303 | @itemize @bullet | |
304 | @item | |
305 | The minibuffer text before point must be the same as the beginning of | |
306 | the completion alternative. If there is any minibuffer text after | |
307 | point, it must be a substring of the remainder of the completion | |
308 | alternative. | |
309 | ||
310 | @item | |
311 | If no completion alternative satisfies the above rules, try using | |
312 | @dfn{partial completion} rules: divide the minibuffer text into words | |
313 | separated by hyphens or spaces, and complete each word separately. | |
314 | Thus, when completing command names, @samp{em-l-m} completes to | |
315 | @samp{emacs-lisp-mode}. | |
316 | ||
317 | @item | |
318 | If there is still no completion alternative, try the first rule again, | |
319 | but ignore the minibuffer text after point (i.e., don't try matching | |
320 | it). | |
321 | @end itemize | |
322 | ||
323 | @noindent | |
324 | When performing these comparisons, a @samp{*} in the minibuffer text | |
325 | acts as a @dfn{wildcard}---it matches any character at the | |
326 | corresponding position in the completion alternative. | |
327 | ||
8cf51b2c GM |
328 | @kindex SPC |
329 | @findex minibuffer-complete-word | |
01163003 CY |
330 | @key{SPC} (@code{minibuffer-complete-word}) completes like |
331 | @key{TAB}, but only up to the next hyphen or space. If you have | |
332 | @samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the | |
333 | completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, | |
334 | giving @samp{auto-fill-}. Another @key{SPC} at this point completes | |
335 | all the way to @samp{auto-fill-mode}. | |
8cf51b2c | 336 | |
7fb1a584 CY |
337 | If @key{TAB} or @key{SPC} is unable to complete, it displays a list |
338 | of possible completions (if there are any) in a separate window. You | |
339 | can choose a completion from this list using the following commands: | |
8cf51b2c GM |
340 | |
341 | @table @kbd | |
342 | @findex mouse-choose-completion | |
343 | @item Mouse-1 | |
344 | @itemx Mouse-2 | |
345 | Clicking mouse button 1 or 2 on a completion possibility chooses that | |
01163003 | 346 | completion (@code{mouse-choose-completion}). |
8cf51b2c GM |
347 | |
348 | @findex switch-to-completions | |
01163003 CY |
349 | @item M-v |
350 | @itemx @key{PageUp} | |
b5700de6 | 351 | @itemx @key{prior} |
01163003 CY |
352 | Typing @kbd{M-v}, while in the minibuffer, selects the window showing |
353 | the completion list buffer (@code{switch-to-completions}). This paves | |
354 | the way for using the commands below. Typing @key{PageUp} or | |
b5700de6 | 355 | @key{prior} does the same, as does selecting that window in other |
01163003 | 356 | ways. |
8cf51b2c GM |
357 | |
358 | @findex choose-completion | |
359 | @item @key{RET} | |
01163003 | 360 | Typing @key{RET}, while in the completion list buffer, chooses the |
8cf51b2c GM |
361 | completion that point is in or next to (@code{choose-completion}). To |
362 | use this command, you must first switch to the completion list window. | |
363 | ||
364 | @findex next-completion | |
01163003 CY |
365 | @item @key{Right} |
366 | Typing the right-arrow key @key{Right}, while in the completion list | |
367 | buffer, moves point to the following completion possibility | |
8cf51b2c GM |
368 | (@code{next-completion}). |
369 | ||
370 | @findex previous-completion | |
01163003 CY |
371 | @item @key{Left} |
372 | Typing the left-arrow key @key{Left}, while in the completion list | |
373 | buffer, moves point to the previous completion possibility | |
8cf51b2c GM |
374 | (@code{previous-completion}). |
375 | @end table | |
376 | ||
377 | @node Strict Completion | |
378 | @subsection Strict Completion | |
379 | ||
380 | There are three different ways that @key{RET} can do completion, | |
381 | depending on how the argument will be used. | |
382 | ||
383 | @itemize @bullet | |
384 | @item | |
385 | @dfn{Strict} completion accepts only known completion candidates. For | |
386 | example, when @kbd{C-x k} reads the name of a buffer to kill, only the | |
387 | name of an existing buffer makes sense. In strict completion, | |
388 | @key{RET} refuses to exit if the text in the minibuffer does not | |
389 | complete to an exact match. | |
390 | ||
391 | @item | |
392 | @dfn{Cautious} completion is similar to strict completion, except that | |
393 | @key{RET} exits only if the text is an already exact match. | |
394 | Otherwise, @key{RET} does not exit, but it does complete the text. If | |
395 | that completes to an exact match, a second @key{RET} will exit. | |
396 | ||
397 | Cautious completion is used for reading file names for files that must | |
398 | already exist, for example. | |
399 | ||
400 | @item | |
401 | @dfn{Permissive} completion allows any input; the completion | |
402 | candidates are just suggestions. For example, when @kbd{C-x C-f} | |
403 | reads the name of a file to visit, any file name is allowed, including | |
404 | nonexistent file (in case you want to create a file). In permissive | |
405 | completion, @key{RET} does not complete, it just submits the argument | |
406 | as you have entered it. | |
407 | @end itemize | |
408 | ||
409 | The completion commands display a list of all possible completions | |
410 | whenever they can't determine even one more character by completion. | |
411 | Also, typing @kbd{?} explicitly requests such a list. You can scroll | |
412 | the list with @kbd{C-M-v} (@pxref{Other Window}). | |
413 | ||
414 | @node Completion Options | |
415 | @subsection Completion Options | |
416 | ||
01163003 CY |
417 | @vindex completion-auto-help |
418 | If @code{completion-auto-help} is set to @code{nil}, the completion | |
419 | commands never display the completion list buffer; you must type | |
420 | @kbd{?} to display the list. If the value is @code{lazy}, Emacs only | |
421 | shows the completion list buffer on the second attempt to complete. | |
422 | In other words, if there is nothing to complete, the first @key{TAB} | |
423 | echoes @samp{Next char not unique}; the second @key{TAB} does the | |
867d4bb3 | 424 | completion list buffer. |
01163003 | 425 | |
8cf51b2c GM |
426 | @vindex completion-ignored-extensions |
427 | @cindex ignored file names, in completion | |
428 | When completing file names, certain file names are usually ignored. | |
429 | The variable @code{completion-ignored-extensions} contains a list of | |
430 | strings; a file name ending in any of those strings is ignored as a | |
431 | completion candidate. The standard value of this variable has several | |
01163003 CY |
432 | elements including @code{".o"}, @code{".elc"}, and @code{"~"}. For |
433 | example, if a directory contains @samp{foo.c} and @samp{foo.elc}, | |
434 | @samp{foo} completes to @samp{foo.c}. However, if @emph{all} possible | |
435 | completions end in ``ignored'' strings, they are not ignored: in the | |
436 | previous example, @samp{foo.e} completes to @samp{foo.elc}. | |
437 | Displaying a list of possible completions disregards | |
438 | @code{completion-ignored-extensions}; it shows them all. | |
8cf51b2c GM |
439 | |
440 | If an element of @code{completion-ignored-extensions} ends in a | |
01163003 CY |
441 | slash (@file{/}), it's a subdirectory name; that directory and its |
442 | contents are ignored. Elements of | |
443 | @code{completion-ignored-extensions} that do not end in a slash are | |
444 | ordinary file names. | |
8cf51b2c | 445 | |
7fb1a584 CY |
446 | @cindex case-sensitivity and completion |
447 | @vindex read-file-name-completion-ignore-case | |
448 | @vindex read-buffer-completion-ignore-case | |
449 | When completing file names, Emacs ignores case differences if the | |
450 | variable @code{read-file-name-completion-ignore-case} is | |
451 | non-@code{nil}. The default value is @code{nil} on systems that have | |
452 | case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on | |
453 | systems that have case-insensitive file-names, such as Microsoft | |
454 | Windows. When completing buffer names, Emacs ignores case differences | |
455 | if @code{read-buffer-completion-ignore-case} is non-@code{nil} (the | |
456 | default value is @code{nil}). | |
457 | ||
458 | @vindex completion-styles | |
459 | You can customize the matching rules for completion alternatives | |
460 | using the variable @code{completion-styles}. Its value should be a | |
461 | list of symbols, each representing a @dfn{completion style}; valid | |
462 | style symbols are @code{basic}, @code{partial-completion}, | |
26e533e2 CY |
463 | @code{emacs22}, @code{emacs21}, and @code{initials}. When completing, |
464 | Emacs attempts to use the first completion style in the list; if this | |
465 | does not return any completion alternatives, it tries the next | |
466 | completion style in the list, and so on. The completion rules | |
467 | described in @ref{Completion Commands} correspond to the default value | |
468 | of @code{completion-styles}, which is @code{(basic partial-completion | |
469 | emacs22)}. | |
8cf51b2c GM |
470 | |
471 | @cindex Icomplete mode | |
472 | @findex icomplete-mode | |
473 | Icomplete mode presents a constantly-updated display that tells you | |
474 | what completions are available for the text you've entered so far. The | |
475 | command to enable or disable this minor mode is @kbd{M-x | |
476 | icomplete-mode}. | |
477 | ||
478 | @node Minibuffer History | |
479 | @section Minibuffer History | |
480 | @cindex minibuffer history | |
481 | @cindex history of minibuffer input | |
482 | ||
01163003 | 483 | Every argument that you enter with the minibuffer is saved in a |
8cf51b2c | 484 | @dfn{minibuffer history list} so you can easily use it again later. |
01163003 CY |
485 | You can use the following arguments to quickly fetch an earlier |
486 | argument into the minibuffer: | |
8cf51b2c GM |
487 | |
488 | @table @kbd | |
01163003 CY |
489 | @item M-p |
490 | @itemx @key{Up} | |
491 | Move to the previous item in the minibuffer history, an earlier | |
492 | argument (@code{previous-history-element}). | |
493 | @item M-n | |
494 | @itemx @key{Down} | |
8cf51b2c GM |
495 | Move to the next item in the minibuffer history |
496 | (@code{next-history-element}). | |
497 | @item M-r @var{regexp} @key{RET} | |
9a70f03d | 498 | Move to an earlier item in the minibuffer history that |
8cf51b2c GM |
499 | matches @var{regexp} (@code{previous-matching-history-element}). |
500 | @item M-s @var{regexp} @key{RET} | |
501 | Move to a later item in the minibuffer history that matches | |
502 | @var{regexp} (@code{next-matching-history-element}). | |
503 | @end table | |
504 | ||
505 | @kindex M-p @r{(minibuffer history)} | |
506 | @kindex M-n @r{(minibuffer history)} | |
507 | @findex next-history-element | |
508 | @findex previous-history-element | |
01163003 CY |
509 | While in the minibuffer, typing @kbd{M-p} or @key{Up} |
510 | (@code{previous-history-element}) moves up through the minibuffer | |
511 | history list, one item at a time. Each @kbd{M-p} fetches an earlier | |
512 | item from the history list into the minibuffer, replacing its existing | |
513 | contents. Similarly, typing @kbd{M-n} or @key{Down} | |
514 | (@code{next-history-element}) moves back down the history list, | |
515 | fetching later entries into the minibuffer. You can think of these | |
516 | commands as ``backwards'' and ``forwards'' through the history list. | |
517 | ||
518 | If you type @kbd{M-n} in the minibuffer when there are no later | |
519 | entries in the minibuffer history (e.g., if you haven't previously | |
520 | typed @kbd{M-p}), Emacs tries fetching from a list of default | |
521 | argument: values that you are likely to enter. You can think of this | |
522 | as moving through the ``future list'' instead of the ``history list''. | |
523 | ||
524 | The input that @kbd{M-p} or @kbd{M-n} fetches into the minibuffer | |
525 | entirely replaces the existing contents of the minibuffer, so you can | |
526 | simply type @key{RET} to use it as an argument. You can also edit the | |
527 | text before you reuse it; this does not change the history element | |
528 | that you ``moved'' to, but your new argument does go at the end of the | |
529 | history list in its own right. | |
8cf51b2c GM |
530 | |
531 | @findex previous-matching-history-element | |
532 | @findex next-matching-history-element | |
533 | @kindex M-r @r{(minibuffer history)} | |
534 | @kindex M-s @r{(minibuffer history)} | |
535 | There are also commands to search forward or backward through the | |
536 | history; they search for history elements that match a regular | |
537 | expression. @kbd{M-r} (@code{previous-matching-history-element}) | |
538 | searches older elements in the history, while @kbd{M-s} | |
539 | (@code{next-matching-history-element}) searches newer elements. These | |
01163003 | 540 | commands are unusual: they use the minibuffer to read the regular |
8cf51b2c GM |
541 | expression even though they are invoked from the minibuffer. As with |
542 | incremental searching, an upper-case letter in the regular expression | |
69e9cadd JL |
543 | makes the search case-sensitive (@pxref{Search Case}). You can also |
544 | search through the history using an incremental search (@pxref{Isearch | |
545 | Minibuffer}). | |
8cf51b2c | 546 | |
8cf51b2c GM |
547 | All uses of the minibuffer record your input on a history list, but |
548 | there are separate history lists for different kinds of arguments. | |
549 | For example, there is a list for file names, used by all the commands | |
550 | that read file names. (As a special feature, this history list | |
551 | records the absolute file name, even if the name you entered was not | |
552 | absolute.) | |
553 | ||
554 | There are several other specific history lists, including one for | |
555 | buffer names, one for arguments of commands like @code{query-replace}, | |
556 | one used by @kbd{M-x} for command names, and one used by | |
557 | @code{compile} for compilation commands. Finally, there is one | |
558 | ``miscellaneous'' history list that most minibuffer arguments use. | |
559 | ||
560 | @vindex history-length | |
561 | The variable @code{history-length} specifies the maximum length of a | |
562 | minibuffer history list; adding a new element deletes the oldest | |
563 | element if the list gets too long. If the value of | |
01163003 | 564 | @code{history-length} is @code{t}, there is no maximum length. |
8cf51b2c GM |
565 | |
566 | @vindex history-delete-duplicates | |
567 | The variable @code{history-delete-duplicates} specifies whether to | |
01163003 CY |
568 | delete duplicates in history. If it is non-@code{nil}, adding a new |
569 | element deletes from the list all other elements that are equal to it. | |
570 | The default is @code{nil}. | |
8cf51b2c GM |
571 | |
572 | @node Repetition | |
573 | @section Repeating Minibuffer Commands | |
574 | @cindex command history | |
575 | @cindex history of commands | |
576 | ||
577 | Every command that uses the minibuffer once is recorded on a special | |
578 | history list, the @dfn{command history}, together with the values of | |
579 | its arguments, so that you can repeat the entire command. In | |
580 | particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} | |
581 | uses the minibuffer to read the command name. | |
582 | ||
583 | @findex list-command-history | |
584 | @table @kbd | |
585 | @item C-x @key{ESC} @key{ESC} | |
586 | Re-execute a recent minibuffer command from the command history | |
587 | (@code{repeat-complex-command}). | |
588 | @item M-x list-command-history | |
589 | Display the entire command history, showing all the commands | |
590 | @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. | |
591 | @end table | |
592 | ||
593 | @kindex C-x ESC ESC | |
594 | @findex repeat-complex-command | |
595 | @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command | |
596 | that used the minibuffer. With no argument, it repeats the last such | |
597 | command. A numeric argument specifies which command to repeat; 1 | |
598 | means the last one, 2 the previous, and so on. | |
599 | ||
600 | @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command | |
601 | into a Lisp expression and then entering a minibuffer initialized with | |
602 | the text for that expression. Even if you don't understand Lisp | |
603 | syntax, it will probably be obvious which command is displayed for | |
604 | repetition. If you type just @key{RET}, that repeats the command | |
605 | unchanged. You can also change the command by editing the Lisp | |
606 | expression before you execute it. The repeated command is added to | |
607 | the front of the command history unless it is identical to the most | |
da0bbbc4 | 608 | recent item. |
8cf51b2c GM |
609 | |
610 | Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can | |
611 | use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, | |
612 | @kbd{M-s}; @pxref{Minibuffer History}) to move through the history list | |
613 | of saved entire commands. After finding the desired previous command, | |
614 | you can edit its expression as usual and then repeat it by typing | |
615 | @key{RET}. | |
616 | ||
617 | @vindex isearch-resume-in-command-history | |
618 | Incremental search does not, strictly speaking, use the minibuffer. | |
619 | Therefore, although it behaves like a complex command, it normally | |
620 | does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. | |
621 | You can make incremental search commands appear in the history by | |
622 | setting @code{isearch-resume-in-command-history} to a non-@code{nil} | |
623 | value. @xref{Incremental Search}. | |
624 | ||
625 | @vindex command-history | |
626 | The list of previous minibuffer-using commands is stored as a Lisp | |
627 | list in the variable @code{command-history}. Each element is a Lisp | |
628 | expression which describes one command and its arguments. Lisp programs | |
629 | can re-execute a command by calling @code{eval} with the | |
630 | @code{command-history} element. | |
631 | ||
2760fefb CY |
632 | @node Passwords |
633 | @section Entering passwords | |
634 | ||
635 | Sometimes, you may need to enter a password into Emacs. For instance, | |
636 | when you tell Emacs to visit a file on another machine via a network | |
637 | protocol such as FTP, you often need to supply a password to gain | |
638 | access to the machine (@pxref{Remote Files}). | |
639 | ||
640 | Entering a password is, in a basic sense, similar to using a | |
641 | minibuffer. Emacs displays a prompt in the echo area (such as | |
642 | @samp{Password: }); after you type the required password, press | |
643 | @key{RET} to submit it. To prevent others from seeing your password, | |
644 | every character you type is displayed as a dot (@samp{.}) instead of | |
645 | its usual form. | |
646 | ||
647 | Most of the features and commands associated with the minibuffer can | |
648 | @emph{not} be used when entering a password. There is no history or | |
649 | completion, and you cannot change windows or perform any other action | |
650 | with Emacs until you have submitted the password. | |
651 | ||
652 | While you are typing the password, you may press @key{DEL} to delete | |
653 | backwards, removing the last character entered. @key{C-u} deletes | |
654 | everything you have typed so far. @kbd{C-g} quits the password prompt | |
655 | (@pxref{Quitting}). @kbd{C-y} inserts the current kill into the | |
656 | password (@pxref{Killing}). You may type either @key{RET} or | |
657 | @key{ESC} to submit the password. Any other self-inserting character | |
658 | key inserts the associated character into the password, and all other | |
659 | input is ignored. |