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