Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
6ca0edfe DL |
2 | @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 |
3 | @c Free Software Foundation, Inc. | |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Dired, Calendar/Diary, Rmail, Top | |
6 | @chapter Dired, the Directory Editor | |
7 | @cindex Dired | |
8 | ||
9 | Dired makes an Emacs buffer containing a listing of a directory, and | |
10 | optionally some of its subdirectories as well. You can use the normal | |
11 | Emacs commands to move around in this buffer, and special Dired commands | |
12 | to operate on the files listed. | |
13 | ||
14 | @menu | |
15 | * Enter: Dired Enter. How to invoke Dired. | |
16 | * Commands: Dired Commands. Commands in the Dired buffer. | |
17 | * Deletion: Dired Deletion. Deleting files with Dired. | |
18 | * Flagging Many Files:: Flagging files based on their names. | |
19 | * Visit: Dired Visiting. Other file operations through Dired. | |
20 | * Marks vs Flags:: Flagging for deletion vs marking. | |
21 | * Operating on Files:: How to copy, rename, print, compress, etc. | |
22 | either one file or several files. | |
23 | * Shell Commands in Dired:: Running a shell command on the marked files. | |
24 | * Transforming File Names:: Using patterns to rename multiple files. | |
25 | * Comparison in Dired:: Running `diff' by way of Dired. | |
26 | * Subdirectories in Dired:: Adding subdirectories to the Dired buffer. | |
27 | * Subdirectory Motion:: Moving across subdirectories, and up and down. | |
28 | * Hiding Subdirectories:: Making subdirectories visible or invisible. | |
29 | * Updating: Dired Updating. Discarding lines for files of no interest. | |
30 | * Find: Dired and Find. Using `find' to choose the files for Dired. | |
4bce911c | 31 | * Extra Features for Dired:: Dired-X provides more features. |
6bf7aab6 DL |
32 | @end menu |
33 | ||
34 | @node Dired Enter | |
35 | @section Entering Dired | |
36 | ||
37 | @findex dired | |
38 | @kindex C-x d | |
39 | @vindex dired-listing-switches | |
40 | To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads | |
41 | a directory name or wildcard file name pattern as a minibuffer argument | |
42 | to specify which files to list. Where @code{dired} differs from | |
43 | @code{list-directory} is in putting the buffer into Dired mode so that | |
44 | the special commands of Dired are available. | |
45 | ||
46 | The variable @code{dired-listing-switches} specifies the options to | |
47 | give to @code{ls} for listing directory; this string @emph{must} contain | |
48 | @samp{-l}. If you use a numeric prefix argument with the @code{dired} | |
49 | command, you can specify the @code{ls} switches with the minibuffer | |
50 | before you enter the directory specification. | |
51 | ||
52 | @findex dired-other-window | |
53 | @kindex C-x 4 d | |
54 | @findex dired-other-frame | |
55 | @kindex C-x 5 d | |
56 | To display the Dired buffer in another window rather than in the | |
57 | selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead | |
58 | of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a | |
59 | separate frame to display the Dired buffer. | |
60 | ||
61 | @node Dired Commands | |
62 | @section Commands in the Dired Buffer | |
63 | ||
64 | The Dired buffer is ``read-only,'' and inserting text in it is not | |
65 | useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are | |
66 | used for special Dired commands. Some Dired commands @dfn{mark} or | |
67 | @dfn{flag} the @dfn{current file} (that is, the file on the current | |
68 | line); other commands operate on the marked files or on the flagged | |
69 | files. | |
70 | ||
71 | @kindex C-n @r{(Dired)} | |
72 | @kindex C-p @r{(Dired)} | |
73 | All the usual Emacs cursor motion commands are available in Dired | |
74 | buffers. Some special-purpose cursor motion commands are also | |
75 | provided. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the | |
76 | cursor at the beginning of the file name on the line, rather than at the | |
77 | beginning of the line. | |
78 | ||
79 | @kindex SPC @r{(Dired)} | |
80 | For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent | |
81 | to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is | |
82 | so common in Dired that it deserves to be easy to type.) @key{DEL} | |
83 | (move up and unflag) is often useful simply for moving up. | |
84 | ||
85 | @node Dired Deletion | |
86 | @section Deleting Files with Dired | |
87 | @cindex flagging files (in Dired) | |
88 | @cindex deleting files (in Dired) | |
89 | ||
90 | The primary use of Dired is to @dfn{flag} files for deletion and then | |
91 | delete the files previously flagged. | |
92 | ||
93 | @table @kbd | |
94 | @item d | |
95 | Flag this file for deletion. | |
96 | @item u | |
97 | Remove deletion flag on this line. | |
98 | @item @key{DEL} | |
99 | Move point to previous line and remove the deletion flag on that line. | |
100 | @item x | |
101 | Delete the files that are flagged for deletion. | |
102 | @end table | |
103 | ||
104 | @kindex d @r{(Dired)} | |
105 | @findex dired-flag-file-deletion | |
106 | You can flag a file for deletion by moving to the line describing the | |
107 | file and typing @kbd{d} (@code{dired-flag-file-deletion}). The deletion flag is visible as a @samp{D} at | |
108 | the beginning of the line. This command moves point to the next line, | |
109 | so that repeated @kbd{d} commands flag successive files. A numeric | |
110 | argument serves as a repeat count. | |
4bce911c DL |
111 | @vindex dired-recursive-deletes |
112 | The variable @code{dired-recursive-deletes} determines if the delete | |
113 | command will delete non-empty directories recursively. The default | |
114 | is to delete only empty directories. | |
6bf7aab6 DL |
115 | |
116 | @kindex u @r{(Dired deletion)} | |
117 | @kindex DEL @r{(Dired)} | |
118 | The files are flagged for deletion rather than deleted immediately to | |
119 | reduce the danger of deleting a file accidentally. Until you direct | |
120 | Dired to expunge the flagged files, you can remove deletion flags using | |
121 | the commands @kbd{u} and @key{DEL}. @kbd{u} (@code{dired-unmark}) works | |
122 | just like @kbd{d}, but removes flags rather than making flags. | |
123 | @key{DEL} (@code{dired-unmark-backward}) moves upward, removing flags; | |
124 | it is like @kbd{u} with argument @minus{}1. | |
125 | ||
126 | @kindex x @r{(Dired)} | |
127 | @findex dired-expunge | |
128 | @cindex expunging (Dired) | |
129 | To delete the flagged files, type @kbd{x} (@code{dired-expunge}). | |
130 | This command first displays a list of all the file names flagged for | |
131 | deletion, and requests confirmation with @kbd{yes}. If you confirm, | |
132 | Dired deletes the flagged files, then deletes their lines from the text | |
133 | of the Dired buffer. The shortened Dired buffer remains selected. | |
134 | ||
135 | If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you | |
136 | return immediately to Dired, with the deletion flags still present in | |
137 | the buffer, and no files actually deleted. | |
138 | ||
139 | @node Flagging Many Files | |
140 | @section Flagging Many Files at Once | |
141 | ||
142 | @table @kbd | |
143 | @item # | |
144 | Flag all auto-save files (files whose names start and end with @samp{#}) | |
145 | for deletion (@pxref{Auto Save}). | |
146 | ||
147 | @item ~ | |
148 | Flag all backup files (files whose names end with @samp{~}) for deletion | |
149 | (@pxref{Backup}). | |
150 | ||
151 | @item & | |
152 | Flag for deletion all files with certain kinds of names, names that | |
153 | suggest you could easily create the files again. | |
154 | ||
155 | @item .@: @r{(Period)} | |
156 | Flag excess numeric backup files for deletion. The oldest and newest | |
157 | few backup files of any one file are exempt; the middle ones are | |
158 | flagged. | |
159 | ||
160 | @item % d @var{regexp} @key{RET} | |
161 | Flag for deletion all files whose names match the regular expression | |
162 | @var{regexp}. | |
163 | @end table | |
164 | ||
165 | The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for | |
166 | deletion, based on their file names. These commands are useful | |
167 | precisely because they do not themselves delete any files; you can | |
168 | remove the deletion flags from any flagged files that you really wish to | |
169 | keep.@refill | |
170 | ||
171 | @kindex & @r{(Dired)} | |
172 | @findex dired-flag-garbage-files | |
173 | @vindex dired-garbage-files-regexp | |
174 | @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names | |
175 | match the regular expression specified by the variable | |
176 | @code{dired-garbage-files-regexp}. By default, this matches certain | |
177 | files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files | |
178 | produced by @code{patch}. | |
179 | ||
180 | @kindex # @r{(Dired)} | |
181 | @kindex ~ @r{(Dired)} | |
182 | @findex dired-flag-auto-save-files | |
183 | @findex dired-flag-backup-files | |
184 | @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all | |
185 | files whose names look like auto-save files (@pxref{Auto Save})---that | |
186 | is, files whose names begin and end with @samp{#}. @kbd{~} | |
187 | (@code{dired-flag-backup-files}) flags for deletion all files whose | |
188 | names say they are backup files (@pxref{Backup})---that is, whose names | |
189 | end in @samp{~}. | |
190 | ||
191 | @kindex . @r{(Dired)} | |
192 | @vindex dired-kept-versions | |
193 | @findex dired-clean-directory | |
194 | @kbd{.} (period, @code{dired-clean-directory}) flags just some of the | |
195 | backup files for deletion: all but the oldest few and newest few backups | |
196 | of any one file. Normally @code{dired-kept-versions} (@strong{not} | |
197 | @code{kept-new-versions}; that applies only when saving) specifies the | |
198 | number of newest versions of each file to keep, and | |
199 | @code{kept-old-versions} specifies the number of oldest versions to | |
200 | keep. | |
201 | ||
202 | Period with a positive numeric argument, as in @kbd{C-u 3 .}, | |
203 | specifies the number of newest versions to keep, overriding | |
204 | @code{dired-kept-versions}. A negative numeric argument overrides | |
205 | @code{kept-old-versions}, using minus the value of the argument to | |
206 | specify the number of oldest versions of each file to keep. | |
207 | ||
208 | @findex dired-flag-files-regexp | |
209 | @kindex % d @r{(Dired)} | |
210 | The @kbd{% d} command flags all files whose names match a specified | |
211 | regular expression (@code{dired-flag-files-regexp}). Only the | |
212 | non-directory part of the file name is used in matching. You can use | |
213 | @samp{^} and @samp{$} to anchor matches. You can exclude subdirectories | |
214 | by hiding them (@pxref{Hiding Subdirectories}). | |
215 | ||
216 | @node Dired Visiting | |
217 | @section Visiting Files in Dired | |
218 | ||
219 | There are several Dired commands for visiting or examining the files | |
220 | listed in the Dired buffer. All of them apply to the current line's | |
221 | file; if that file is really a directory, these commands invoke Dired on | |
222 | that subdirectory (making a separate Dired buffer). | |
223 | ||
224 | @table @kbd | |
225 | @item f | |
226 | @kindex f @r{(Dired)} | |
227 | @findex dired-find-file | |
228 | Visit the file described on the current line, like typing @kbd{C-x C-f} | |
229 | and supplying that file name (@code{dired-find-file}). @xref{Visiting}. | |
230 | ||
231 | @item @key{RET} | |
232 | @kindex RET @r{(Dired)} | |
233 | Equivalent to @kbd{f}. | |
234 | ||
f8a12fe7 GM |
235 | @item a |
236 | @kindex a @r{(Dired)} | |
237 | @findex dired-find-alternate-file | |
238 | Like @kbd{f}, but replaces the contents of the Dired buffer with | |
239 | that of an alternate file or directory. | |
240 | ||
6bf7aab6 DL |
241 | @item o |
242 | @kindex o @r{(Dired)} | |
243 | @findex dired-find-file-other-window | |
244 | Like @kbd{f}, but uses another window to display the file's buffer | |
245 | (@code{dired-find-file-other-window}). The Dired buffer remains visible | |
246 | in the first window. This is like using @kbd{C-x 4 C-f} to visit the | |
247 | file. @xref{Windows}. | |
248 | ||
249 | @item C-o | |
250 | @kindex C-o @r{(Dired)} | |
251 | @findex dired-display-file | |
252 | Visit the file described on the current line, and display the buffer in | |
253 | another window, but do not select that window (@code{dired-display-file}). | |
254 | ||
255 | @item Mouse-2 | |
256 | @findex dired-mouse-find-file-other-window | |
257 | Visit the file named by the line you click on | |
258 | (@code{dired-mouse-find-file-other-window}). This uses another window | |
259 | to display the file, like the @kbd{o} command. | |
260 | ||
261 | @item v | |
262 | @kindex v @r{(Dired)} | |
263 | @findex dired-view-file | |
264 | View the file described on the current line, using @kbd{M-x view-file} | |
265 | (@code{dired-view-file}). | |
266 | ||
267 | Viewing a file is like visiting it, but is slanted toward moving around | |
268 | in the file conveniently and does not allow changing the file. | |
269 | @xref{Misc File Ops,View File}. | |
270 | @end table | |
271 | ||
272 | @node Marks vs Flags | |
273 | @section Dired Marks vs. Flags | |
274 | ||
275 | @cindex marking in Dired | |
276 | Instead of flagging a file with @samp{D}, you can @dfn{mark} the file | |
277 | with some other character (usually @samp{*}). Most Dired commands to | |
278 | operate on files, aside from ``expunge'' (@kbd{x}), look for files | |
279 | marked with @samp{*}. | |
280 | ||
281 | Here are some commands for marking with @samp{*}, or for unmarking or | |
282 | operating on marks. (@xref{Dired Deletion}, for commands to flag and | |
283 | unflag files.) | |
284 | ||
285 | @table @kbd | |
286 | @item m | |
287 | @itemx * m | |
288 | @kindex m @r{(Dired)} | |
289 | @kindex * m @r{(Dired)} | |
290 | @findex dired-mark | |
291 | Mark the current file with @samp{*} (@code{dired-mark}). With a numeric | |
292 | argument @var{n}, mark the next @var{n} files starting with the current | |
293 | file. (If @var{n} is negative, mark the previous @minus{}@var{n} | |
294 | files.) | |
295 | ||
296 | @item * * | |
297 | @kindex * * @r{(Dired)} | |
298 | @findex dired-mark-executables | |
299 | Mark all executable files with @samp{*} | |
300 | (@code{dired-mark-executables}). With a numeric argument, unmark all | |
301 | those files. | |
302 | ||
303 | @item * @@ | |
304 | @kindex * @@ @r{(Dired)} | |
305 | @findex dired-mark-symlinks | |
306 | Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). | |
307 | With a numeric argument, unmark all those files. | |
308 | ||
309 | @item * / | |
310 | @kindex * / @r{(Dired)} | |
311 | @findex dired-mark-directories | |
312 | Mark with @samp{*} all files which are actually directories, except for | |
313 | @file{.} and @file{..} (@code{dired-mark-directories}). With a numeric | |
314 | argument, unmark all those files. | |
315 | ||
316 | @item * s | |
317 | @kindex * s @r{(Dired)} | |
318 | @findex dired-mark-subdir-files | |
319 | Mark all the files in the current subdirectory, aside from @file{.} | |
320 | and @file{..} (@code{dired-mark-subdir-files}). | |
321 | ||
322 | @item u | |
323 | @itemx * u | |
324 | @kindex u @r{(Dired)} | |
325 | @kindex * u @r{(Dired)} | |
326 | @findex dired-unmark | |
327 | Remove any mark on this line (@code{dired-unmark}). | |
328 | ||
329 | @item @key{DEL} | |
330 | @itemx * @key{DEL} | |
331 | @kindex * DEL @r{(Dired)} | |
332 | @findex dired-unmark-backward | |
333 | Move point to previous line and remove any mark on that line | |
334 | (@code{dired-unmark-backward}). | |
335 | ||
336 | @item * ! | |
337 | @kindex * ! @r{(Dired)} | |
338 | @findex dired-unmark-all-files-no-query | |
339 | Remove all marks from all the files in this Dired buffer | |
340 | (@code{dired-unmark-all-files-no-query}). | |
341 | ||
342 | @item * ? @var{markchar} | |
343 | @kindex * ? @r{(Dired)} | |
344 | @findex dired-unmark-all-files | |
345 | Remove all marks that use the character @var{markchar} | |
346 | (@code{dired-unmark-all-files}). The argument is a single | |
347 | character---do not use @key{RET} to terminate it. | |
348 | ||
349 | With a numeric argument, this command queries about each marked file, | |
350 | asking whether to remove its mark. You can answer @kbd{y} meaning yes, | |
351 | @kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining | |
352 | files without asking about them. | |
353 | ||
354 | @item * C-n | |
355 | @findex dired-next-marked-file | |
356 | @kindex * C-n @r{(Dired)} | |
357 | Move down to the next marked file (@code{dired-next-marked-file}) | |
358 | A file is ``marked'' if it has any kind of mark. | |
359 | ||
360 | @item * C-p | |
361 | @findex dired-prev-marked-file | |
362 | @kindex * C-p @r{(Dired)} | |
363 | Move up to the previous marked file (@code{dired-prev-marked-file}) | |
364 | ||
365 | @item * t | |
366 | @kindex * t @r{(Dired)} | |
367 | @findex dired-do-toggle | |
368 | Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*} | |
369 | become unmarked, and unmarked files are marked with @samp{*}. Files | |
370 | marked in any other way are not affected. | |
371 | ||
372 | @item * c @var{old} @var{new} | |
373 | @kindex * c @r{(Dired)} | |
374 | @findex dired-change-marks | |
375 | Replace all marks that use the character @var{old} with marks that use | |
376 | the character @var{new} (@code{dired-change-marks}). This command is | |
377 | the primary way to create or use marks other than @samp{*} or @samp{D}. | |
378 | The arguments are single characters---do not use @key{RET} to terminate | |
379 | them. | |
380 | ||
381 | You can use almost any character as a mark character by means of this | |
382 | command, to distinguish various classes of files. If @var{old} is a | |
383 | space (@samp{ }), then the command operates on all unmarked files; if | |
384 | @var{new} is a space, then the command unmarks the files it acts on. | |
385 | ||
386 | To illustrate the power of this command, here is how to put @samp{D} | |
387 | flags on all the files that have no marks, while unflagging all those | |
388 | that already have @samp{D} flags: | |
389 | ||
390 | @example | |
391 | * c D t * c SPC D * c t SPC | |
392 | @end example | |
393 | ||
394 | This assumes that no files are marked with @samp{t}. | |
395 | ||
396 | @item % m @var{regexp} @key{RET} | |
397 | @itemx * % @var{regexp} @key{RET} | |
398 | @findex dired-mark-files-regexp | |
399 | @kindex % m @r{(Dired)} | |
400 | @kindex * % @r{(Dired)} | |
401 | Mark (with @samp{*}) all files whose names match the regular expression | |
402 | @var{regexp} (@code{dired-mark-files-regexp}). This command is like | |
403 | @kbd{% d}, except that it marks files with @samp{*} instead of flagging | |
404 | with @samp{D}. @xref{Flagging Many Files}. | |
405 | ||
406 | Only the non-directory part of the file name is used in matching. Use | |
407 | @samp{^} and @samp{$} to anchor matches. Exclude subdirectories by | |
408 | hiding them (@pxref{Hiding Subdirectories}). | |
409 | ||
410 | @item % g @var{regexp} @key{RET} | |
411 | @findex dired-mark-files-containing-regexp | |
412 | @kindex % m @r{(Dired)} | |
413 | Mark (with @samp{*}) all files whose @emph{contents} contain a match for | |
414 | the regular expression @var{regexp} | |
415 | (@code{dired-mark-files-containing-regexp}). This command is like | |
416 | @kbd{% m}, except that it searches the file contents instead of the file | |
417 | name. | |
418 | ||
419 | @item C-_ | |
420 | @kindex C-_ @r{(Dired)} | |
421 | @findex dired-undo | |
422 | Undo changes in the Dired buffer, such as adding or removing | |
423 | marks (@code{dired-undo}). | |
424 | @end table | |
425 | ||
426 | @node Operating on Files | |
427 | @section Operating on Files | |
428 | @cindex operating on files in Dired | |
429 | ||
430 | This section describes the basic Dired commands to operate on one file | |
431 | or several files. All of these commands are capital letters; all of | |
432 | them use the minibuffer, either to read an argument or to ask for | |
433 | confirmation, before they act. All of them give you several ways to | |
434 | specify which files to manipulate: | |
435 | ||
436 | @itemize @bullet | |
437 | @item | |
438 | If you give the command a numeric prefix argument @var{n}, it operates | |
439 | on the next @var{n} files, starting with the current file. (If @var{n} | |
440 | is negative, the command operates on the @minus{}@var{n} files preceding | |
441 | the current line.) | |
442 | ||
443 | @item | |
444 | Otherwise, if some files are marked with @samp{*}, the command operates | |
445 | on all those files. | |
446 | ||
447 | @item | |
448 | Otherwise, the command operates on the current file only. | |
449 | @end itemize | |
450 | ||
451 | Here are the file-manipulating commands that operate on files in this | |
452 | way. (Some other Dired commands, such as @kbd{!} and the @samp{%} | |
453 | commands, also use these conventions to decide which files to work on.) | |
454 | ||
455 | @table @kbd | |
456 | @findex dired-do-copy | |
457 | @kindex C @r{(Dired)} | |
458 | @item C @var{new} @key{RET} | |
459 | Copy the specified files (@code{dired-do-copy}). The argument @var{new} | |
460 | is the directory to copy into, or (if copying a single file) the new | |
461 | name. | |
4bce911c DL |
462 | @vindex dired-recursive-copies |
463 | The variable @code{dired-recursive-copies} determines if directories are | |
464 | copied recursively. The default is to not copy recursively. | |
6bf7aab6 DL |
465 | |
466 | @vindex dired-copy-preserve-time | |
467 | If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with | |
468 | this command sets the modification time of the new file to be the same | |
469 | as that of the old file. | |
470 | ||
471 | @item D | |
472 | @findex dired-do-delete | |
473 | @kindex D @r{(Dired)} | |
474 | Delete the specified files (@code{dired-do-delete}). Like the other | |
475 | commands in this section, this command operates on the @emph{marked} | |
476 | files, or the next @var{n} files. By contrast, @kbd{x} | |
477 | (@code{dired-expunge}) deletes all @dfn{flagged} files. | |
478 | ||
479 | @findex dired-do-rename | |
480 | @kindex R @r{(Dired)} | |
481 | @item R @var{new} @key{RET} | |
482 | Rename the specified files (@code{dired-do-rename}). The argument | |
483 | @var{new} is the directory to rename into, or (if renaming a single | |
484 | file) the new name. | |
485 | ||
486 | Dired automatically changes the visited file name of buffers associated | |
487 | with renamed files so that they refer to the new names. | |
488 | ||
489 | @findex dired-do-hardlink | |
490 | @kindex H @r{(Dired)} | |
491 | @item H @var{new} @key{RET} | |
492 | Make hard links to the specified files (@code{dired-do-hardlink}). The | |
493 | argument @var{new} is the directory to make the links in, or (if making | |
494 | just one link) the name to give the link. | |
495 | ||
496 | @findex dired-do-symlink | |
497 | @kindex S @r{(Dired)} | |
498 | @item S @var{new} @key{RET} | |
499 | Make symbolic links to the specified files (@code{dired-do-symlink}). | |
500 | The argument @var{new} is the directory to make the links in, or (if | |
501 | making just one link) the name to give the link. | |
502 | ||
503 | @findex dired-do-chmod | |
504 | @kindex M @r{(Dired)} | |
505 | @item M @var{modespec} @key{RET} | |
506 | Change the mode (also called ``permission bits'') of the specified files | |
507 | (@code{dired-do-chmod}). This uses the @code{chmod} program, so | |
508 | @var{modespec} can be any argument that @code{chmod} can handle. | |
509 | ||
510 | @findex dired-do-chgrp | |
511 | @kindex G @r{(Dired)} | |
512 | @item G @var{newgroup} @key{RET} | |
513 | Change the group of the specified files to @var{newgroup} | |
514 | (@code{dired-do-chgrp}). | |
515 | ||
516 | @findex dired-do-chown | |
517 | @kindex O @r{(Dired)} | |
518 | @item O @var{newowner} @key{RET} | |
519 | Change the owner of the specified files to @var{newowner} | |
520 | (@code{dired-do-chown}). (On most systems, only the superuser can do | |
521 | this.) | |
522 | ||
523 | @vindex dired-chown-program | |
524 | The variable @code{dired-chown-program} specifies the name of the | |
525 | program to use to do the work (different systems put @code{chown} in | |
526 | different places). | |
527 | ||
528 | @findex dired-do-print | |
529 | @kindex P @r{(Dired)} | |
530 | @item P @var{command} @key{RET} | |
531 | Print the specified files (@code{dired-do-print}). You must specify the | |
532 | command to print them with, but the minibuffer starts out with a | |
533 | suitable guess made using the variables @code{lpr-command} and | |
534 | @code{lpr-switches} (the same variables that @code{lpr-buffer} uses; | |
535 | @pxref{Hardcopy}). | |
536 | ||
537 | @findex dired-do-compress | |
538 | @kindex Z @r{(Dired)} | |
539 | @item Z | |
540 | Compress the specified files (@code{dired-do-compress}). If the file | |
541 | appears to be a compressed file already, it is uncompressed instead. | |
542 | ||
543 | @findex dired-do-load | |
544 | @kindex L @r{(Dired)} | |
545 | @item L | |
546 | Load the specified Emacs Lisp files (@code{dired-do-load}). | |
547 | @xref{Lisp Libraries}. | |
548 | ||
549 | @findex dired-do-byte-compile | |
550 | @kindex B @r{(Dired)} | |
551 | @item B | |
552 | Byte compile the specified Emacs Lisp files | |
553 | (@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte | |
554 | Compilation, elisp, The Emacs Lisp Reference Manual}. | |
555 | ||
556 | @kindex A @r{(Dired)} | |
557 | @findex dired-do-search | |
558 | @item A @var{regexp} @key{RET} | |
559 | Search all the specified files for the regular expression @var{regexp} | |
560 | (@code{dired-do-search}). | |
561 | ||
562 | This command is a variant of @code{tags-search}. The search stops at | |
563 | the first match it finds; use @kbd{M-,} to resume the search and find | |
564 | the next match. @xref{Tags Search}. | |
565 | ||
566 | @kindex Q @r{(Dired)} | |
567 | @findex dired-do-query-replace | |
568 | @item Q @var{from} @key{RET} @var{to} @key{RET} | |
569 | Perform @code{query-replace-regexp} on each of the specified files, | |
570 | replacing matches for @var{from} (a regular expression) with the string | |
571 | @var{to} (@code{dired-do-query-replace}). | |
572 | ||
573 | This command is a variant of @code{tags-query-replace}. If you exit the | |
574 | query replace loop, you can use @kbd{M-,} to resume the scan and replace | |
575 | more matches. @xref{Tags Search}. | |
4bce911c DL |
576 | |
577 | @kindex a @r{(Dired)} | |
578 | @findex dired-do-apply | |
579 | @item a @var{function} @kbd{RET} | |
580 | Apply an arbitrary Lisp function to the name of each marked file | |
581 | (@code{dired-do-apply}). | |
6bf7aab6 DL |
582 | @end table |
583 | ||
584 | @kindex + @r{(Dired)} | |
585 | @findex dired-create-directory | |
586 | One special file-operation command is @kbd{+} | |
587 | (@code{dired-create-directory}). This command reads a directory name and | |
588 | creates the directory if it does not already exist. | |
589 | ||
590 | @node Shell Commands in Dired | |
591 | @section Shell Commands in Dired | |
592 | @cindex shell commands, Dired | |
593 | ||
594 | @findex dired-do-shell-command | |
595 | @kindex ! @r{(Dired)} | |
596 | The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell | |
597 | command string in the minibuffer and runs that shell command on all the | |
598 | specified files. You can specify the files to operate on in the usual | |
599 | ways for Dired commands (@pxref{Operating on Files}). There are two | |
600 | ways of applying a shell command to multiple files: | |
601 | ||
602 | @itemize @bullet | |
603 | @item | |
604 | If you use @samp{*} in the shell command, then it runs just once, with | |
605 | the list of file names substituted for the @samp{*}. The order of file | |
606 | names is the order of appearance in the Dired buffer. | |
607 | ||
608 | Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire | |
609 | list of file names, putting them into one tar file @file{foo.tar}. | |
610 | ||
611 | @item | |
612 | If the command string doesn't contain @samp{*}, then it runs once | |
613 | @emph{for each file}, with the file name added at the end. | |
614 | ||
615 | For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each | |
616 | file. | |
617 | @end itemize | |
618 | ||
619 | What if you want to run the shell command once for each file but with | |
620 | the file name inserted in the middle? Or if you want to use the file | |
621 | names in a more complicated fashion? Use a shell loop. For example, | |
622 | this shell command would run @code{uuencode} on each of the specified | |
623 | files, writing the output into a corresponding @file{.uu} file: | |
624 | ||
625 | @example | |
626 | for file in *; do uuencode $file $file >$file.uu; done | |
627 | @end example | |
628 | ||
4bce911c DL |
629 | @noindent |
630 | In simple cases you can instead use @samp{?} in the command. This is | |
631 | similar to @samp{*} but the command will be run on each file | |
632 | individually. | |
633 | ||
6bf7aab6 DL |
634 | The working directory for the shell command is the top-level directory |
635 | of the Dired buffer. | |
636 | ||
637 | The @kbd{!} command does not attempt to update the Dired buffer to show | |
638 | new or modified files, because it doesn't really understand shell | |
639 | commands, and does not know what files the shell command changed. Use | |
640 | the @kbd{g} command to update the Dired buffer (@pxref{Dired | |
641 | Updating}). | |
642 | ||
643 | @node Transforming File Names | |
644 | @section Transforming File Names in Dired | |
645 | ||
646 | Here are commands that alter file names in a systematic way: | |
647 | ||
648 | @table @kbd | |
649 | @findex dired-upcase | |
650 | @kindex % u @r{(Dired)} | |
651 | @item % u | |
652 | Rename each of the selected files to an upper-case name | |
653 | (@code{dired-upcase}). If the old file names are @file{Foo} | |
654 | and @file{bar}, the new names are @file{FOO} and @file{BAR}. | |
655 | ||
656 | @item % l | |
657 | @findex dired-downcase | |
658 | @kindex % l @r{(Dired)} | |
659 | Rename each of the selected files to a lower-case name | |
660 | (@code{dired-downcase}). If the old file names are @file{Foo} and | |
661 | @file{bar}, the new names are @file{foo} and @file{bar}. | |
662 | ||
663 | @item % R @var{from} @key{RET} @var{to} @key{RET} | |
664 | @kindex % R @r{(Dired)} | |
665 | @findex dired-do-rename-regexp | |
666 | @itemx % C @var{from} @key{RET} @var{to} @key{RET} | |
667 | @kindex % C @r{(Dired)} | |
668 | @findex dired-do-copy-regexp | |
669 | @itemx % H @var{from} @key{RET} @var{to} @key{RET} | |
670 | @kindex % H @r{(Dired)} | |
671 | @findex dired-do-hardlink-regexp | |
672 | @itemx % S @var{from} @key{RET} @var{to} @key{RET} | |
673 | @kindex % S @r{(Dired)} | |
674 | @findex dired-do-symlink-regexp | |
675 | These four commands rename, copy, make hard links and make soft links, | |
676 | in each case computing the new name by regular-expression substitution | |
677 | from the name of the old file. | |
678 | @end table | |
679 | ||
680 | The four regular-expression substitution commands effectively perform | |
681 | a search-and-replace on the selected file names in the Dired buffer. | |
682 | They read two arguments: a regular expression @var{from}, and a | |
683 | substitution pattern @var{to}. | |
684 | ||
685 | The commands match each ``old'' file name against the regular | |
686 | expression @var{from}, and then replace the matching part with @var{to}. | |
687 | You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to | |
688 | all or part of what the pattern matched in the old file name, as in | |
689 | @code{replace-regexp} (@pxref{Regexp Replace}). If the regular expression | |
690 | matches more than once in a file name, only the first match is replaced. | |
691 | ||
692 | For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each | |
693 | selected file by prepending @samp{x-} to its name. The inverse of this, | |
694 | removing @samp{x-} from the front of each file name, is also possible: | |
695 | one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is | |
696 | @kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor | |
697 | matches that should span the whole filename.) | |
698 | ||
699 | Normally, the replacement process does not consider the files' | |
700 | directory names; it operates on the file name within the directory. If | |
701 | you specify a numeric argument of zero, then replacement affects the | |
702 | entire absolute file name including directory name. | |
703 | ||
704 | Often you will want to select the set of files to operate on using the | |
705 | same @var{regexp} that you will use to operate on them. To do this, | |
706 | mark those files with @kbd{% m @var{regexp} @key{RET}}, then use the | |
707 | same regular expression in the command to operate on the files. To make | |
708 | this easier, the @kbd{%} commands to operate on files use the last | |
709 | regular expression specified in any @kbd{%} command as a default. | |
710 | ||
711 | @node Comparison in Dired | |
712 | @section File Comparison with Dired | |
713 | ||
714 | Here are two Dired commands that compare specified files using | |
715 | @code{diff}. | |
716 | ||
717 | @table @kbd | |
718 | @item = | |
719 | @findex dired-diff | |
720 | @kindex = @r{(Dired)} | |
721 | Compare the current file (the file at point) with another file (the file | |
722 | at the mark) using the @code{diff} program (@code{dired-diff}). The | |
723 | file at the mark is the first argument of @code{diff}, and the file at | |
724 | point is the second argument. | |
725 | ||
726 | @findex dired-backup-diff | |
727 | @kindex M-= @r{(Dired)} | |
728 | @item M-= | |
729 | Compare the current file with its latest backup file | |
730 | (@code{dired-backup-diff}). If the current file is itself a backup, | |
731 | compare it with the file it is a backup of; this way, you can compare | |
732 | a file with any backup version of your choice. | |
733 | ||
734 | The backup file is the first file given to @code{diff}. | |
735 | @end table | |
736 | ||
737 | @node Subdirectories in Dired | |
738 | @section Subdirectories in Dired | |
739 | @cindex subdirectories in Dired | |
740 | @cindex expanding subdirectories in Dired | |
741 | ||
742 | A Dired buffer displays just one directory in the normal case; | |
743 | but you can optionally include its subdirectories as well. | |
744 | ||
745 | The simplest way to include multiple directories in one Dired buffer is | |
746 | to specify the options @samp{-lR} for running @code{ls}. (If you give a | |
747 | numeric argument when you run Dired, then you can specify these options | |
748 | in the minibuffer.) That produces a recursive directory listing showing | |
749 | all subdirectories at all levels. | |
750 | ||
751 | But usually all the subdirectories are too many; usually you will | |
752 | prefer to include specific subdirectories only. You can do this with | |
753 | the @kbd{i} command: | |
754 | ||
755 | @table @kbd | |
756 | @findex dired-maybe-insert-subdir | |
757 | @kindex i @r{(Dired)} | |
758 | @item i | |
759 | @cindex inserted subdirectory (Dired) | |
760 | @cindex in-situ subdirectory (Dired) | |
761 | Insert the contents of a subdirectory later in the buffer. | |
762 | @end table | |
763 | ||
764 | Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line | |
765 | that describes a file which is a directory. It inserts the contents of | |
766 | that directory into the same Dired buffer, and moves there. Inserted | |
767 | subdirectory contents follow the top-level directory of the Dired | |
768 | buffer, just as they do in @samp{ls -lR} output. | |
769 | ||
770 | If the subdirectory's contents are already present in the buffer, the | |
771 | @kbd{i} command just moves to it. | |
772 | ||
773 | In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u | |
774 | C-@key{SPC}} takes you back to the old position in the buffer (the line | |
775 | describing that subdirectory). | |
776 | ||
777 | Use the @kbd{l} command (@code{dired-do-redisplay}) to update the | |
778 | subdirectory's contents. Use @kbd{k} to delete the subdirectory. | |
779 | @xref{Dired Updating}. | |
780 | ||
781 | @node Subdirectory Motion | |
782 | @section Moving Over Subdirectories | |
783 | ||
784 | When a Dired buffer lists subdirectories, you can use the page motion | |
785 | commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories. | |
786 | ||
787 | @cindex header line (Dired) | |
788 | @cindex directory header lines | |
789 | The following commands move across, up and down in the tree of | |
790 | directories within one Dired buffer. They move to @dfn{directory header | |
791 | lines}, which are the lines that give a directory's name, at the | |
792 | beginning of the directory's contents. | |
793 | ||
794 | @table @kbd | |
795 | @findex dired-next-subdir | |
796 | @kindex C-M-n @r{(Dired)} | |
797 | @item C-M-n | |
798 | Go to next subdirectory header line, regardless of level | |
799 | (@code{dired-next-subdir}). | |
800 | ||
801 | @findex dired-prev-subdir | |
802 | @kindex C-M-p @r{(Dired)} | |
803 | @item C-M-p | |
804 | Go to previous subdirectory header line, regardless of level | |
805 | (@code{dired-prev-subdir}). | |
806 | ||
807 | @findex dired-tree-up | |
808 | @kindex C-M-u @r{(Dired)} | |
809 | @item C-M-u | |
810 | Go up to the parent directory's header line (@code{dired-tree-up}). | |
811 | ||
812 | @findex dired-tree-down | |
813 | @kindex C-M-d @r{(Dired)} | |
814 | @item C-M-d | |
815 | Go down in the directory tree, to the first subdirectory's header line | |
816 | (@code{dired-tree-down}). | |
817 | ||
818 | @findex dired-prev-dirline | |
819 | @kindex < @r{(Dired)} | |
820 | @item < | |
821 | Move up to the previous directory-file line (@code{dired-prev-dirline}). | |
822 | These lines are the ones that describe a directory as a file in its | |
823 | parent directory. | |
824 | ||
825 | @findex dired-next-dirline | |
826 | @kindex > @r{(Dired)} | |
827 | @item > | |
828 | Move down to the next directory-file line (@code{dired-prev-dirline}). | |
829 | @end table | |
830 | ||
831 | @node Hiding Subdirectories | |
832 | @section Hiding Subdirectories | |
833 | ||
834 | @cindex hiding in Dired (Dired) | |
835 | @dfn{Hiding} a subdirectory means to make it invisible, except for its | |
836 | header line, via selective display (@pxref{Selective Display}). | |
837 | ||
838 | @table @kbd | |
839 | @item $ | |
840 | @findex dired-hide-subdir | |
841 | @kindex $ @r{(Dired)} | |
842 | Hide or reveal the subdirectory that point is in, and move point to the | |
843 | next subdirectory (@code{dired-hide-subdir}). A numeric argument serves | |
844 | as a repeat count. | |
845 | ||
846 | @item M-$ | |
847 | @findex dired-hide-all | |
848 | @kindex M-$ @r{(Dired)} | |
849 | Hide all subdirectories in this Dired buffer, leaving only their header | |
850 | lines (@code{dired-hide-all}). Or, if any subdirectory is currently | |
851 | hidden, make all subdirectories visible again. You can use this command | |
852 | to get an overview in very deep directory trees or to move quickly to | |
853 | subdirectories far away. | |
854 | @end table | |
855 | ||
856 | Ordinary Dired commands never consider files inside a hidden | |
857 | subdirectory. For example, the commands to operate on marked files | |
858 | ignore files in hidden directories even if they are marked. Thus you | |
859 | can use hiding to temporarily exclude subdirectories from operations | |
860 | without having to remove the markers. | |
861 | ||
862 | The subdirectory hiding commands toggle; that is, they hide what was | |
863 | visible, and show what was hidden. | |
864 | ||
865 | @node Dired Updating | |
866 | @section Updating the Dired Buffer | |
867 | ||
868 | This section describes commands to update the Dired buffer to reflect | |
869 | outside (non-Dired) changes in the directories and files, and to delete | |
870 | part of the Dired buffer. | |
871 | ||
872 | @table @kbd | |
873 | @item g | |
874 | Update the entire contents of the Dired buffer (@code{revert-buffer}). | |
875 | ||
876 | @item l | |
877 | Update the specified files (@code{dired-do-redisplay}). | |
878 | ||
879 | @item k | |
880 | Delete the specified @emph{file lines}---not the files, just the lines | |
881 | (@code{dired-do-kill-lines}). | |
882 | ||
883 | @item s | |
884 | Toggle between alphabetical order and date/time order | |
885 | (@code{dired-sort-toggle-or-edit}). | |
886 | ||
887 | @item C-u s @var{switches} @key{RET} | |
888 | Refresh the Dired buffer using @var{switches} as | |
889 | @code{dired-listing-switches}. | |
890 | @end table | |
891 | ||
892 | @kindex g @r{(Dired)} | |
893 | @findex revert-buffer @r{(Dired)} | |
894 | Type @kbd{g} (@code{revert-buffer}) to update the contents of the | |
895 | Dired buffer, based on changes in the files and directories listed. | |
896 | This preserves all marks except for those on files that have vanished. | |
897 | Hidden subdirectories are updated but remain hidden. | |
898 | ||
899 | @kindex l @r{(Dired)} | |
900 | @findex dired-do-redisplay | |
901 | To update only some of the files, type @kbd{l} | |
902 | (@code{dired-do-redisplay}). This command applies to the next @var{n} | |
903 | files, or to the marked files if any, or to the current file. Updating | |
904 | them means reading their current status from the file system and | |
905 | changing the buffer to reflect it properly. | |
906 | ||
907 | If you use @kbd{l} on a subdirectory header line, it updates the | |
908 | contents of the corresponding subdirectory. | |
909 | ||
910 | @kindex k @r{(Dired)} | |
911 | @findex dired-do-kill-lines | |
912 | To delete the specified @emph{file lines}---not the files, just the | |
913 | lines---type @kbd{k} (@code{dired-do-kill-lines}). With a numeric | |
914 | argument @var{n}, this command applies to the next @var{n} files; | |
915 | otherwise, it applies to the marked files. | |
916 | ||
917 | If you kill the line for a file that is a directory, the directory's | |
918 | contents are also deleted from the buffer. Typing @kbd{C-u k} on the | |
919 | header line for a subdirectory is another way to delete a subdirectory | |
920 | from the Dired buffer. | |
921 | ||
922 | The @kbd{g} command brings back any individual lines that you have | |
923 | killed in this way, but not subdirectories---you must use @kbd{i} to | |
924 | reinsert each subdirectory. | |
925 | ||
926 | @cindex Dired sorting | |
927 | @cindex sorting Dired buffer | |
928 | @kindex s @r{(Dired)} | |
929 | @findex dired-sort-toggle-or-edit | |
930 | The files in a Dired buffers are normally listed in alphabetical order | |
931 | by file names. Alternatively Dired can sort them by date/time. The | |
932 | Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches | |
933 | between these two sorting modes. The mode line in a Dired buffer | |
934 | indicates which way it is currently sorted---by name, or by date. | |
935 | ||
936 | @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for | |
937 | @code{dired-listing-switches}. | |
938 | ||
939 | @node Dired and Find | |
940 | @section Dired and @code{find} | |
941 | @cindex @code{find} and Dired | |
942 | ||
943 | You can select a set of files for display in a Dired buffer more | |
944 | flexibly by using the @code{find} utility to choose the files. | |
945 | ||
946 | @findex find-name-dired | |
947 | To search for files with names matching a wildcard pattern use | |
948 | @kbd{M-x find-name-dired}. It reads arguments @var{directory} and | |
949 | @var{pattern}, and chooses all the files in @var{directory} or its | |
950 | subdirectories whose individual names match @var{pattern}. | |
951 | ||
952 | The files thus chosen are displayed in a Dired buffer in which the | |
953 | ordinary Dired commands are available. | |
954 | ||
955 | @findex find-grep-dired | |
956 | If you want to test the contents of files, rather than their names, | |
957 | use @kbd{M-x find-grep-dired}. This command reads two minibuffer | |
958 | arguments, @var{directory} and @var{regexp}; it chooses all the files in | |
959 | @var{directory} or its subdirectories that contain a match for | |
960 | @var{regexp}. It works by running the programs @code{find} and | |
961 | @code{grep}. See also @kbd{M-x grep-find}, in @ref{Compilation}. | |
962 | Remember to write the regular expression for @code{grep}, not for Emacs. | |
963 | ||
964 | @findex find-dired | |
965 | The most general command in this series is @kbd{M-x find-dired}, which | |
966 | lets you specify any condition that @code{find} can test. It takes two | |
967 | minibuffer arguments, @var{directory} and @var{find-args}; it runs | |
968 | @code{find} in @var{directory}, passing @var{find-args} to tell | |
969 | @code{find} what condition to test. To use this command, you need to | |
970 | know how to use @code{find}. | |
971 | ||
972 | @vindex find-ls-option | |
973 | The format of listing produced by these commands is controlled by the | |
974 | variable @code{find-ls-option}, whose default value specifies using | |
975 | options @samp{-ld} for @code{ls}. If your listings are corrupted, you | |
976 | may need to change the value of this variable. | |
4bce911c DL |
977 | |
978 | @node Extra Features for Dired | |
979 | @section Extra Features for Dired---The Dired-X Package | |
980 | ||
981 | The Dired-X package provides various extra features for Dired mode. You | |
982 | can load it with @code{M-x load-library} or customize | |
983 | @code{dired-load-hook} to add @samp{(require@w{ }'dired-x)}. | |
7fb91890 | 984 | @xref{Top, Introduction, Dired Extra Version 2 User's Manual, dired-x}. |