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