Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
b65d8176 | 2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
3f548a7c | 3 | @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Minibuffer, M-x, Basic, Top | |
6 | @chapter The Minibuffer | |
7 | @cindex minibuffer | |
8 | ||
3c8c279c RS |
9 | The @dfn{minibuffer} is where Emacs commands read complicated |
10 | arguments (anything more a single number). We call it the | |
11 | ``minibuffer'' because it's a special-purpose buffer with a small | |
12 | amount of screen space. Minibuffer arguments can be file names, | |
13 | buffer names, Lisp function names, Emacs command names, Lisp | |
14 | expressions, and many other things---whatever the command wants to | |
15 | read. You can use the usual Emacs editing commands in the minibuffer | |
16 | to edit the argument text. | |
6bf7aab6 DL |
17 | |
18 | @cindex prompt | |
3c8c279c RS |
19 | When the minibuffer is in use, it appears in the echo area, with a |
20 | cursor. The minibuffer display starts with a @dfn{prompt} in a | |
21 | distinct color; it says what kind of input is expected and how it will | |
22 | be used. Often the prompt is derived from the name of the command | |
23 | that is reading the argument. The prompt normally ends with a colon. | |
6bf7aab6 DL |
24 | |
25 | @cindex default argument | |
3c8c279c RS |
26 | Sometimes a @dfn{default argument} appears in the prompt, inside |
27 | parentheses before the colon. The default will be used as the | |
28 | argument value if you just type @key{RET}. For example, commands that | |
29 | read buffer names show a buffer name as the default. You can type | |
30 | @key{RET} to operate on that default buffer. | |
31 | ||
32 | The simplest way to enter a minibuffer argument is to type the text, | |
33 | then @key{RET} to exit the minibuffer. You can cancel the minibuffer, | |
34 | and the command that wants the argument, by typing @kbd{C-g}. | |
35 | ||
36 | Since the minibuffer appears in the echo area, it can conflict with | |
37 | other uses of the echo area. Here is how Emacs handles such | |
38 | conflicts: | |
6bf7aab6 DL |
39 | |
40 | @itemize @bullet | |
41 | @item | |
3c8c279c RS |
42 | An error occurs while the minibuffer is active. |
43 | ||
44 | The error message hides the minibuffer for a few seconds, or until you | |
45 | type something. Then the minibuffer comes back. | |
6bf7aab6 DL |
46 | |
47 | @item | |
3c8c279c RS |
48 | A command such as @kbd{C-x =} needs to display a message in the echo |
49 | area. | |
50 | ||
51 | The message hides the minibuffer for a few seconds, or until you type | |
52 | something. Then the minibuffer comes back. | |
6bf7aab6 DL |
53 | |
54 | @item | |
3c8c279c | 55 | Keystrokes don't echo while the minibuffer is in use. |
6bf7aab6 DL |
56 | @end itemize |
57 | ||
58 | @menu | |
59 | * File: Minibuffer File. Entering file names with the minibuffer. | |
60 | * Edit: Minibuffer Edit. How to edit in the minibuffer. | |
61 | * Completion:: An abbreviation facility for minibuffer input. | |
62 | * Minibuffer History:: Reusing recent minibuffer arguments. | |
63 | * Repetition:: Re-executing commands that used the minibuffer. | |
64 | @end menu | |
65 | ||
66 | @node Minibuffer File | |
67 | @section Minibuffers for File Names | |
68 | ||
3c8c279c RS |
69 | When you use the minibuffer to enter a file name, it starts out with |
70 | some initial text---the @dfn{default directory}, ending in a slash. | |
71 | The file you specify will be in this directory unless you alter or | |
72 | replace it. | |
6bf7aab6 | 73 | |
eb9ee0db | 74 | @c Separate paragraph to clean up ugly page break--rms |
6bf7aab6 | 75 | @need 1500 |
3c8c279c | 76 | For example, if the minibuffer starts out with these contents: |
6bf7aab6 DL |
77 | |
78 | @example | |
79 | Find File: /u2/emacs/src/ | |
80 | @end example | |
81 | ||
82 | @noindent | |
3c8c279c RS |
83 | (where @samp{Find File:@: } is the prompt), and you type |
84 | @kbd{buffer.c} as input, that specifies the file | |
85 | @file{/u2/emacs/src/buffer.c}. You can specify the parent directory | |
86 | by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you | |
87 | will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use | |
88 | @kbd{M-@key{DEL}} to kill the directory names you don't want | |
89 | (@pxref{Words}). | |
90 | ||
86264ca1 RS |
91 | You can kill the entire default with @kbd{C-a C-k}, but there's no |
92 | need to do that. It's easier to ignore the default, and enter an | |
93 | absolute file name starting with a slash or a tilde after the default | |
94 | directory. For example, to specify @file{/etc/termcap}, just type | |
95 | that name: | |
6bf7aab6 DL |
96 | |
97 | @example | |
98 | Find File: /u2/emacs/src//etc/termcap | |
99 | @end example | |
100 | ||
101 | @noindent | |
102 | @cindex // in file name | |
103 | @cindex double slash in file name | |
104 | @cindex slashes repeated in file name | |
cf6ac72b | 105 | @findex file-name-shadow-mode |
3c8c279c RS |
106 | GNU Emacs interprets a double slash (which is not normally useful in |
107 | file names) as, ``ignore everything before the second slash in the | |
108 | pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so | |
109 | you get @file{/etc/termcap}. The ignored part of the file name is | |
110 | dimmed if the terminal allows it; to disable this dimming, turn off | |
111 | File Name Shadow mode (a minor mode) with the command | |
112 | @kbd{M-x file-name-shadow-mode}. | |
113 | ||
114 | If the variable @code{insert-default-directory} is @code{nil}, the | |
708bf232 | 115 | default directory is never inserted in the minibuffer---so the |
3c8c279c RS |
116 | minibuffer starts out empty. Nonetheless, relative file name |
117 | arguments are still interpreted based on the same default directory. | |
6bf7aab6 DL |
118 | |
119 | @node Minibuffer Edit | |
120 | @section Editing in the Minibuffer | |
121 | ||
3c8c279c RS |
122 | The minibuffer is an Emacs buffer (albeit a peculiar one), and the |
123 | usual Emacs commands are available for editing the argument text. | |
6bf7aab6 DL |
124 | |
125 | Since @key{RET} in the minibuffer is defined to exit the minibuffer, | |
126 | you can't use it to insert a newline in the minibuffer. To do that, | |
708bf232 RS |
127 | type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the |
128 | @acronym{ASCII} character control-J.) | |
129 | ||
3c8c279c RS |
130 | The minibuffer has its own window, which normally has space in the |
131 | frame at all times, but it only acts like an Emacs window when the | |
132 | minibuffer is active. When active, this window is much like any other | |
133 | Emacs window; for instance, you can switch to another window (with | |
134 | @kbd{C-x o}), edit text there, then return to the minibuffer window to | |
135 | finish the argument. You can even kill text in another window, return | |
136 | to the minibuffer window, and then yank the text into the argument. | |
137 | @xref{Windows}. | |
6bf7aab6 | 138 | |
6bf7aab6 DL |
139 | @cindex height of minibuffer |
140 | @cindex size of minibuffer | |
141 | @cindex growing minibuffer | |
b80da86d | 142 | @cindex resizing minibuffer |
3c8c279c RS |
143 | There are some restrictions on the minibuffer window, however: you |
144 | cannot kill it, or split it, or switch buffers in it---the minibuffer | |
145 | and its window are permanently attached. | |
1cf7421b GM |
146 | |
147 | @vindex resize-mini-windows | |
58fa012d | 148 | The minibuffer window expands vertically as necessary to hold the |
c0a5ac4a | 149 | text that you put in the minibuffer. If @code{resize-mini-windows} is |
3c8c279c RS |
150 | @code{t} (the default), the window always resizes as needed by its |
151 | contents. If its value is the symbol @code{grow-only}, the window | |
152 | grows automatically as needed, but shrinks (back to the normal size) | |
153 | only when the minibuffer becomes inactive. If its value is | |
154 | @code{nil}, you have to adjust the height yourself. | |
1cf7421b GM |
155 | |
156 | @vindex max-mini-window-height | |
79529b12 RS |
157 | The variable @code{max-mini-window-height} controls the maximum |
158 | height for resizing the minibuffer window: a floating-point number | |
159 | specifies a fraction of the frame's height; an integer specifies the | |
160 | maximum number of lines; @code{nil} means do not resize the minibuffer | |
161 | window automatically. The default value is 0.25. | |
6bf7aab6 | 162 | |
3c8c279c RS |
163 | The @kbd{C-M-v} command in the minibuffer scrolls the help text from |
164 | commands that display help text of any sort in another window. | |
165 | @kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that | |
166 | help text. This is especially useful with long lists of possible | |
c0a5ac4a | 167 | completions. @xref{Other Window}. |
6bf7aab6 DL |
168 | |
169 | @vindex enable-recursive-minibuffers | |
170 | Emacs normally disallows most commands that use the minibuffer while | |
3c8c279c RS |
171 | the minibuffer is active. (Entering the minibuffer from the |
172 | minibuffer can be confusing.) To allow such commands in the | |
173 | minibuffer, set the variable @code{enable-recursive-minibuffers} to | |
174 | @code{t}. | |
6bf7aab6 DL |
175 | |
176 | @node Completion | |
177 | @section Completion | |
178 | @cindex completion | |
3c8c279c RS |
179 | |
180 | Some arguments allow @dfn{completion} to enter their value. This | |
181 | means that after you type part of the argument, Emacs can fill in the | |
182 | rest, or some of it, based on what you have typed so far. | |
183 | ||
184 | When completion is available, certain keys---@key{TAB}, @key{RET}, | |
185 | and @key{SPC}---are rebound to complete the text in the minibuffer | |
186 | before point into a longer string chosen from a set of @dfn{completion | |
187 | alternatives} provided by the command that requested the argument. | |
188 | (@key{SPC} does not do completion in reading file names, because it is | |
189 | common to use spaces in file names on some systems.) @kbd{?} displays | |
190 | a list of the possible completions at any time. | |
191 | ||
192 | For example, @kbd{M-x} uses the minibuffer to read the name of a | |
193 | command, so it provides a list of all Emacs command names for | |
194 | completion candidates. The completion keys match the minibuffer text | |
195 | against these candidates, find any additional name characters implied | |
40b6cb79 | 196 | by the text already present in the minibuffer, and add those |
3c8c279c RS |
197 | characters. This makes it possible to type @kbd{M-x ins @key{SPC} b |
198 | @key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example. | |
199 | ||
200 | Case is significant in completion when it is significant in the | |
201 | argument you are entering (buffer names, file names, command names, | |
202 | for instance). Thus, @samp{fo} does not complete to @samp{Foo}. | |
203 | Completion ignores case distinctions for certain arguments in which | |
6bf7aab6 DL |
204 | case does not matter. |
205 | ||
be8a531d RS |
206 | Completion acts only on the text before point. If there is text in |
207 | the minibuffer after point---i.e., if you move point backward after | |
208 | typing some text into the minibuffer---it remains unchanged. | |
209 | ||
6bf7aab6 | 210 | @menu |
50fcce74 JL |
211 | * Example: Completion Example. Examples of using completion. |
212 | * Commands: Completion Commands. A list of completion commands. | |
213 | * Strict Completion:: Different types of completion. | |
214 | * Options: Completion Options. Options for completion. | |
6bf7aab6 DL |
215 | @end menu |
216 | ||
217 | @node Completion Example | |
218 | @subsection Completion Example | |
219 | ||
220 | @kindex TAB @r{(completion)} | |
3c8c279c RS |
221 | A concrete example may help here. If you type @kbd{M-x au |
222 | @key{TAB}}, the @key{TAB} looks for alternatives (in this case, | |
223 | command names) that start with @samp{au}. There are several, | |
224 | including @code{auto-fill-mode} and @code{auto-save-mode}, but they | |
225 | all begin with @code{auto-}, so the @samp{au} in the minibuffer | |
226 | completes to @samp{auto-}. | |
227 | ||
228 | If you type @key{TAB} again immediately, it cannot determine the | |
229 | next character; it could be any of @samp{cfilrs}. So it does not add | |
230 | any characters; instead, @key{TAB} displays a list of all possible | |
231 | completions in another window. | |
232 | ||
233 | Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The | |
234 | only command name starting with that is @code{auto-fill-mode}, so | |
235 | completion fills in the rest of that. You have been able to enter | |
236 | @samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. | |
6bf7aab6 DL |
237 | |
238 | @node Completion Commands | |
239 | @subsection Completion Commands | |
240 | ||
241 | Here is a list of the completion commands defined in the minibuffer | |
3c8c279c | 242 | when completion is allowed. |
6bf7aab6 DL |
243 | |
244 | @table @kbd | |
245 | @item @key{TAB} | |
3c8c279c | 246 | @findex minibuffer-complete |
285b48ff | 247 | Complete the text before point in the minibuffer as much as possible |
6bf7aab6 DL |
248 | (@code{minibuffer-complete}). |
249 | @item @key{SPC} | |
3c8c279c RS |
250 | Complete up to one word from the minibuffer text before point |
251 | (@code{minibuffer-complete-word}). @key{SPC} for completion is not | |
252 | available when entering a file name, since file names often include | |
253 | spaces. | |
6bf7aab6 DL |
254 | @item @key{RET} |
255 | Submit the text in the minibuffer as the argument, possibly completing | |
da4d9773 LT |
256 | first as described |
257 | @iftex | |
258 | in the next subsection (@code{minibuffer-complete-and-exit}). | |
259 | @end iftex | |
260 | @ifnottex | |
261 | in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict | |
262 | Completion}. | |
263 | @end ifnottex | |
6bf7aab6 | 264 | @item ? |
3c8c279c | 265 | Display a list of possible completions of the text before point |
8db30414 | 266 | (@code{minibuffer-completion-help}). |
6bf7aab6 DL |
267 | @end table |
268 | ||
269 | @kindex SPC | |
270 | @findex minibuffer-complete-word | |
3c8c279c RS |
271 | @key{SPC} completes like @key{TAB}, but only up to the next hyphen |
272 | or space. If you have @samp{auto-f} in the minibuffer and type | |
273 | @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but | |
274 | it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another | |
275 | @key{SPC} at this point completes all the way to | |
276 | @samp{auto-fill-mode}. The command that implements this behavior is | |
277 | called @code{minibuffer-complete-word}. | |
6bf7aab6 | 278 | |
3c8c279c RS |
279 | When you display a list of possible completions, you can choose |
280 | one from it: | |
6bf7aab6 DL |
281 | |
282 | @table @kbd | |
283 | @findex mouse-choose-completion | |
c0a5ac4a RS |
284 | @item Mouse-1 |
285 | @itemx Mouse-2 | |
3c8c279c RS |
286 | Clicking mouse button 1 or 2 on a completion possibility chooses that |
287 | completion (@code{mouse-choose-completion}). You must click in the | |
288 | list of completions, not in the minibuffer. | |
6bf7aab6 DL |
289 | |
290 | @findex switch-to-completions | |
291 | @item @key{PRIOR} | |
292 | @itemx M-v | |
293 | Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the | |
294 | minibuffer, selects the window showing the completion list buffer | |
295 | (@code{switch-to-completions}). This paves the way for using the | |
3c8c279c RS |
296 | commands below. (Selecting that window in other ways has the same |
297 | effect.) | |
6bf7aab6 DL |
298 | |
299 | @findex choose-completion | |
300 | @item @key{RET} | |
301 | Typing @key{RET} @emph{in the completion list buffer} chooses the | |
302 | completion that point is in or next to (@code{choose-completion}). To | |
3c8c279c | 303 | use this command, you must first switch to the completion list window. |
6bf7aab6 DL |
304 | |
305 | @findex next-completion | |
306 | @item @key{RIGHT} | |
307 | Typing the right-arrow key @key{RIGHT} @emph{in the completion list | |
3c8c279c RS |
308 | buffer} moves point to the following completion possibility |
309 | (@code{next-completion}). | |
6bf7aab6 DL |
310 | |
311 | @findex previous-completion | |
312 | @item @key{LEFT} | |
313 | Typing the left-arrow key @key{LEFT} @emph{in the completion list | |
3c8c279c RS |
314 | buffer} moves point to the previous completion possibility |
315 | (@code{previous-completion}). | |
6bf7aab6 DL |
316 | @end table |
317 | ||
318 | @node Strict Completion | |
319 | @subsection Strict Completion | |
320 | ||
3c8c279c RS |
321 | There are three different ways that @key{RET} can do completion, |
322 | depending on how the argument will be used. | |
6bf7aab6 DL |
323 | |
324 | @itemize @bullet | |
325 | @item | |
3c8c279c RS |
326 | @dfn{Strict} completion accepts only known completion candidates. For |
327 | example, when @kbd{C-x k} reads the name of a buffer to kill, only the | |
328 | name of an existing buffer makes sense. In strict completion, | |
329 | @key{RET} refuses to exit if the text in the minibuffer does not | |
330 | complete to an exact match. | |
6bf7aab6 DL |
331 | |
332 | @item | |
333 | @dfn{Cautious} completion is similar to strict completion, except that | |
3c8c279c RS |
334 | @key{RET} exits only if the text is an already exact match. |
335 | Otherwise, @key{RET} does not exit, but it does complete the text. If | |
336 | that completes to an exact match, a second @key{RET} will exit. | |
6bf7aab6 DL |
337 | |
338 | Cautious completion is used for reading file names for files that must | |
3c8c279c | 339 | already exist, for example. |
6bf7aab6 DL |
340 | |
341 | @item | |
3c8c279c RS |
342 | @dfn{Permissive} completion allows any input; the completion |
343 | candidates are just suggestions. For example, when @kbd{C-x C-f} | |
344 | reads the name of a file to visit, any file name is allowed, including | |
345 | nonexistent file (in case you want to create a file). In permissive | |
346 | completion, @key{RET} does not complete, it just submits the argument | |
347 | as you have entered it. | |
6bf7aab6 DL |
348 | @end itemize |
349 | ||
3c8c279c RS |
350 | The completion commands display a list of all possible completions |
351 | whenever they can't determine even one more character by completion. | |
352 | Also, typing @kbd{?} explicitly requests such a list. You can scroll | |
353 | the list with @kbd{C-M-v} (@pxref{Other Window}). | |
6bf7aab6 DL |
354 | |
355 | @node Completion Options | |
356 | @subsection Completion Options | |
357 | ||
358 | @vindex completion-ignored-extensions | |
89dc96ee | 359 | @cindex ignored file names, in completion |
3c8c279c RS |
360 | When completing file names, certain file names are usually ignored. |
361 | The variable @code{completion-ignored-extensions} contains a list of | |
362 | strings; a file name ending in any of those strings is ignored as a | |
363 | completion candidate. The standard value of this variable has several | |
364 | elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and | |
365 | @code{"~"}. The effect is that, for example, @samp{foo} can complete | |
366 | to @samp{foo.c} even though @samp{foo.o} exists as well. However, if | |
367 | @emph{all} the possible completions end in ``ignored'' strings, then | |
368 | they are not ignored. Displaying a list of possible completions | |
369 | disregards @code{completion-ignored-extensions}; it shows them all. | |
370 | ||
371 | If an element of @code{completion-ignored-extensions} ends in a | |
372 | slash (@file{/}), it's a subdirectory name; then that directory and | |
373 | its contents are ignored. Elements of | |
44829d96 | 374 | @code{completion-ignored-extensions} which do not end in a slash are |
3c8c279c | 375 | ordinary file names, and do not apply to names of directories. |
44829d96 | 376 | |
6bf7aab6 | 377 | @vindex completion-auto-help |
3c8c279c RS |
378 | If @code{completion-auto-help} is set to @code{nil}, the completion |
379 | commands never display a list of possibilities; you must type @kbd{?} | |
380 | to display the list. | |
6bf7aab6 | 381 | |
8efd3a2b DL |
382 | @cindex Partial Completion mode |
383 | @vindex partial-completion-mode | |
384 | @findex partial-completion-mode | |
79529b12 RS |
385 | Partial Completion mode implements a more powerful kind of |
386 | completion that can complete multiple words in parallel. For example, | |
387 | it can complete the command name abbreviation @code{p-b} into | |
3c8c279c RS |
388 | @code{print-buffer} if no other command starts with two words whose |
389 | initials are @samp{p} and @samp{b}. | |
390 | ||
391 | To enable this mode, use @kbd{M-x partial-completion-mode}, or | |
392 | customize the variable @code{partial-completion-mode}. This mode | |
393 | binds special partial completion commands to @key{TAB}, @key{SPC}, | |
394 | @key{RET}, and @kbd{?} in the minibuffer. The usual completion | |
395 | commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}), | |
396 | @kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}. | |
79529b12 RS |
397 | |
398 | Partial completion of directories in file names uses @samp{*} to | |
399 | indicate the places for completion; thus, @file{/u*/b*/f*} might | |
3c8c279c RS |
400 | complete to @file{/usr/bin/foo}. For remote files, partial completion |
401 | enables completion of methods, user names and host names. | |
402 | @xref{Remote Files}. | |
79529b12 | 403 | |
8efd3a2b DL |
404 | @vindex PC-include-file-path |
405 | @vindex PC-disable-includes | |
3c8c279c RS |
406 | Partial Completion mode also extends @code{find-file} so that |
407 | @samp{<@var{include}>} looks for the file named @var{include} in the | |
408 | directories in the path @code{PC-include-file-path}. If you set | |
409 | @code{PC-disable-includes} to non-@code{nil}, this feature is | |
410 | disabled. | |
6bf7aab6 DL |
411 | |
412 | @cindex Icomplete mode | |
8efd3a2b | 413 | @findex icomplete-mode |
6bf7aab6 DL |
414 | Icomplete mode presents a constantly-updated display that tells you |
415 | what completions are available for the text you've entered so far. The | |
416 | command to enable or disable this minor mode is @kbd{M-x | |
417 | icomplete-mode}. | |
418 | ||
419 | @node Minibuffer History | |
420 | @section Minibuffer History | |
421 | @cindex minibuffer history | |
422 | @cindex history of minibuffer input | |
423 | ||
424 | Every argument that you enter with the minibuffer is saved on a | |
3c8c279c RS |
425 | @dfn{minibuffer history list} so you can easily use it again later. |
426 | Special commands fetch the text of an earlier argument into the | |
427 | minibuffer, replacing the old minibuffer contents. You can think of | |
428 | them as moving through the history of previous arguments. | |
6bf7aab6 DL |
429 | |
430 | @table @kbd | |
431 | @item @key{UP} | |
432 | @itemx M-p | |
3c8c279c | 433 | Move to the previous item in the minibuffer history, an earlier argument |
6bf7aab6 DL |
434 | (@code{previous-history-element}). |
435 | @item @key{DOWN} | |
436 | @itemx M-n | |
3c8c279c | 437 | Move to the next item in the minibuffer history |
6bf7aab6 DL |
438 | (@code{next-history-element}). |
439 | @item M-r @var{regexp} @key{RET} | |
3c8c279c RS |
440 | Move to an earlier item in the minibuffer history that |
441 | matches @var{regexp} (@code{previous-matching-history-element}). | |
6bf7aab6 | 442 | @item M-s @var{regexp} @key{RET} |
3c8c279c RS |
443 | Move to a later item in the minibuffer history that matches |
444 | @var{regexp} (@code{next-matching-history-element}). | |
6bf7aab6 DL |
445 | @end table |
446 | ||
447 | @kindex M-p @r{(minibuffer history)} | |
448 | @kindex M-n @r{(minibuffer history)} | |
449 | @findex next-history-element | |
450 | @findex previous-history-element | |
3c8c279c RS |
451 | To move through the minibuffer history list one item at a time, use |
452 | @kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the | |
453 | next earlier minibuffer input, and use @kbd{M-n} or down-arrow | |
454 | (@code{next-history-element}) to fetch the next later input. These | |
455 | commands don't move the cursor, they pull different saved strings into | |
456 | the minibuffer. But you can think of them as ``moving'' through the | |
457 | history list. | |
458 | ||
459 | The input that you fetch from the history entirely replaces the | |
460 | contents of the minibuffer. To use it again unchanged, just type | |
461 | @key{RET}. You can also edit the text before you reuse it; this does | |
462 | not change the history element that you ``moved'' to, but your new | |
463 | argument does go at the end of the history list in its own right. | |
464 | ||
465 | For many minibuffer arguments there is a ``default'' value. You can | |
466 | insert the default value into the minibuffer as text by using | |
467 | @kbd{M-n}. You can think of this as moving ``into the future'' in the | |
468 | history. | |
6bf7aab6 DL |
469 | |
470 | @findex previous-matching-history-element | |
471 | @findex next-matching-history-element | |
472 | @kindex M-r @r{(minibuffer history)} | |
473 | @kindex M-s @r{(minibuffer history)} | |
474 | There are also commands to search forward or backward through the | |
475 | history; they search for history elements that match a regular | |
3c8c279c RS |
476 | expression. @kbd{M-r} (@code{previous-matching-history-element}) |
477 | searches older elements in the history, while @kbd{M-s} | |
478 | (@code{next-matching-history-element}) searches newer elements. These | |
479 | commands are unusual; they use the minibuffer to read the regular | |
480 | expression even though they are invoked from the minibuffer. As with | |
481 | incremental searching, an upper-case letter in the regular expression | |
482 | makes the search case-sensitive (@pxref{Search Case}). | |
6bf7aab6 DL |
483 | |
484 | @ignore | |
485 | We may change the precise way these commands read their arguments. | |
486 | Perhaps they will search for a match for the string given so far in the | |
487 | minibuffer; perhaps they will search for a literal match rather than a | |
488 | regular expression match; perhaps they will only accept matches at the | |
489 | beginning of a history element; perhaps they will read the string to | |
490 | search for incrementally like @kbd{C-s}. To find out what interface is | |
491 | actually available, type @kbd{C-h f previous-matching-history-element}. | |
492 | @end ignore | |
493 | ||
494 | All uses of the minibuffer record your input on a history list, but | |
3c8c279c RS |
495 | there are separate history lists for different kinds of arguments. |
496 | For example, there is a list for file names, used by all the commands | |
497 | that read file names. (As a special feature, this history list | |
498 | records the absolute file name, even if the name you entered was not | |
499 | absolute.) | |
500 | ||
501 | There are several other specific history lists, including one for | |
502 | buffer names, one for arguments of commands like @code{query-replace}, | |
503 | one used by @kbd{M-x} for command names, and one used by | |
504 | @code{compile} for compilation commands. Finally, there is one | |
505 | ``miscellaneous'' history list that most minibuffer arguments use. | |
6bf7aab6 DL |
506 | |
507 | @vindex history-length | |
508 | The variable @code{history-length} specifies the maximum length of a | |
3c8c279c RS |
509 | minibuffer history list; adding a new element deletes the oldest |
510 | element if the list gets too long. If the value of | |
511 | @code{history-length} is @code{t}, though, there is no maximum length. | |
6bf7aab6 | 512 | |
fbb2f03d JL |
513 | @vindex history-delete-duplicates |
514 | The variable @code{history-delete-duplicates} specifies whether to | |
3c8c279c RS |
515 | delete duplicates in history. If it is @code{t}, adding a new element |
516 | deletes from the list all other elements that are equal to it. | |
fbb2f03d | 517 | |
6bf7aab6 DL |
518 | @node Repetition |
519 | @section Repeating Minibuffer Commands | |
520 | @cindex command history | |
521 | @cindex history of commands | |
522 | ||
3c8c279c RS |
523 | Every command that uses the minibuffer once is recorded on a special |
524 | history list, the @dfn{command history}, together with the values of | |
525 | its arguments, so that you can repeat the entire command. In | |
526 | particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} | |
527 | uses the minibuffer to read the command name. | |
6bf7aab6 DL |
528 | |
529 | @findex list-command-history | |
6bf7aab6 DL |
530 | @table @kbd |
531 | @item C-x @key{ESC} @key{ESC} | |
3c8c279c RS |
532 | Re-execute a recent minibuffer command from the command history |
533 | (@code{repeat-complex-command}). | |
6bf7aab6 DL |
534 | @item M-x list-command-history |
535 | Display the entire command history, showing all the commands | |
536 | @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. | |
537 | @end table | |
538 | ||
539 | @kindex C-x ESC ESC | |
540 | @findex repeat-complex-command | |
3c8c279c RS |
541 | @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command |
542 | that used the minibuffer. With no argument, it repeats the last such | |
543 | command. A numeric argument specifies which command to repeat; 1 | |
544 | means the last one, 2 the previous, and so on. | |
6bf7aab6 DL |
545 | |
546 | @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command | |
547 | into a Lisp expression and then entering a minibuffer initialized with | |
3c8c279c RS |
548 | the text for that expression. Even if you don't understand Lisp |
549 | syntax, it will probably be obvious which command is displayed for | |
550 | repetition. If you type just @key{RET}, that repeats the command | |
551 | unchanged. You can also change the command by editing the Lisp | |
552 | expression before you execute it. The repeated command is added to | |
553 | the front of the command history unless it is identical to the most | |
554 | recently item. | |
6bf7aab6 DL |
555 | |
556 | Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can | |
557 | use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, | |
558 | @kbd{M-s}; @pxref{Minibuffer History}) to move through the history list | |
559 | of saved entire commands. After finding the desired previous command, | |
3c8c279c RS |
560 | you can edit its expression as usual and then repeat it by typing |
561 | @key{RET}. | |
6bf7aab6 | 562 | |
3cfa7873 | 563 | @vindex isearch-resume-in-command-history |
3c8c279c RS |
564 | Incremental search does not, strictly speaking, use the minibuffer. |
565 | Therefore, although it behaves like a complex command, it normally | |
566 | does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. | |
567 | You can make incremental search commands appear in the history by | |
3cfa7873 | 568 | setting @code{isearch-resume-in-command-history} to a non-@code{nil} |
c0a5ac4a | 569 | value. @xref{Incremental Search}. |
285b48ff | 570 | |
6bf7aab6 DL |
571 | @vindex command-history |
572 | The list of previous minibuffer-using commands is stored as a Lisp | |
573 | list in the variable @code{command-history}. Each element is a Lisp | |
574 | expression which describes one command and its arguments. Lisp programs | |
575 | can re-execute a command by calling @code{eval} with the | |
576 | @code{command-history} element. | |
ab5796a9 MB |
577 | |
578 | @ignore | |
579 | arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f | |
580 | @end ignore |