1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
4 @c See file emacs.texi for copying conditions.
6 @chapter Dired, the Directory Editor
7 @c This node is referenced in the tutorial. When renaming or deleting
8 @c it, the tutorial needs to be adjusted.
10 @cindex file management
12 Dired makes an Emacs buffer containing a listing of a directory, and
13 optionally some of its subdirectories as well. You can use the normal
14 Emacs commands to move around in this buffer, and special Dired
15 commands to operate on the listed files.
17 The Dired buffer is ``read-only'', and inserting text in it is not
18 allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are
19 redefined for special Dired commands. Some Dired commands @dfn{mark}
20 or @dfn{flag} the @dfn{current file} (that is, the file on the current
21 line); other commands operate on the marked files or on the flagged
22 files. You first mark certain files in order to operate on all of
23 them with one command.
25 The Dired-X package provides various extra features for Dired mode.
26 @xref{Top, Dired-X,,dired-x, Dired Extra User's Manual}.
28 You can also view a list of files in a directory with @kbd{C-x C-d}
29 (@code{list-directory}). Unlike Dired, this command does not allow
30 you to operate on the listed files. @xref{Directories}.
33 * Enter: Dired Enter. How to invoke Dired.
34 * Navigation: Dired Navigation. Special motion commands in the Dired buffer.
35 * Deletion: Dired Deletion. Deleting files with Dired.
36 * Flagging Many Files:: Flagging files based on their names.
37 * Visit: Dired Visiting. Other file operations through Dired.
38 * Marks vs Flags:: Flagging for deletion vs marking.
39 * Operating on Files:: How to copy, rename, print, compress, etc.
40 either one file or several files.
41 * Shell Commands in Dired:: Running a shell command on the marked files.
42 * Transforming File Names:: Using patterns to rename multiple files.
43 * Comparison in Dired:: Running @code{diff} by way of Dired.
44 * Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
46 * Subdir Switches:: Subdirectory switches in Dired.
48 * Subdirectory Motion:: Moving across subdirectories, and up and down.
49 * Hiding Subdirectories:: Making subdirectories visible or invisible.
50 * Updating: Dired Updating. Discarding lines for files of no interest.
51 * Find: Dired and Find. Using @code{find} to choose the files for Dired.
52 * Wdired:: Operating on files by editing the Dired buffer.
53 * Image-Dired:: Viewing image thumbnails in Dired.
54 * Misc: Misc Dired Features. Various other features.
58 @section Entering Dired
62 @vindex dired-listing-switches
63 To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a
64 directory name using the minibuffer, and opens a @dfn{Dired buffer}
65 listing the files in that directory. You can also supply a wildcard
66 file name pattern as the minibuffer argument, in which case the Dired
67 buffer lists all files matching that pattern. The usual history and
68 completion commands can be used in the minibuffer; in particular,
69 @kbd{M-n} puts the name of the visited file (if any) in the minibuffer
70 (@pxref{Minibuffer History}).
72 You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file})
75 The variable @code{dired-listing-switches} specifies the options to
76 give to @command{ls} for listing the directory; this string
77 @emph{must} contain @samp{-l}. If you use a prefix argument with the
78 @code{dired} command, you can specify the @command{ls} switches with the
79 minibuffer before you enter the directory specification. No matter
80 how they are specified, the @command{ls} switches can include short
81 options (that is, single characters) requiring no arguments, and long
82 options (starting with @samp{--}) whose arguments are specified with
85 @vindex dired-use-ls-dired
86 If your @command{ls} program supports the @samp{--dired} option,
87 Dired automatically passes it that option; this causes @command{ls} to
88 emit special escape sequences for certain unusual file names, without
89 which Dired will not be able to parse those names. The first time you
90 run Dired in an Emacs session, it checks whether @command{ls} supports
91 the @samp{--dired} option by calling it once with that option. If the
92 exit code is 0, Dired will subsequently use the @samp{--dired} option;
93 otherwise it will not. You can inhibit this check by customizing the
94 variable @code{dired-use-ls-dired}. The value @code{unspecified} (the
95 default) means to perform the check; any other non-@code{nil} value
96 means to use the @samp{--dired} option; and @code{nil} means not to
97 use the @samp{--dired} option.
99 On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}.
100 @xref{ls in Lisp}, for options and peculiarities of this emulation.
102 @findex dired-other-window
104 @findex dired-other-frame
106 To display the Dired buffer in another window, use @kbd{C-x 4 d}
107 (@code{dired-other-window}). @kbd{C-x 5 d}
108 (@code{dired-other-frame}) displays the Dired buffer in a separate
111 @kindex q @r{(Dired)}
113 Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and
114 deletes its window if the window was created just for that buffer.
116 @node Dired Navigation
117 @section Navigation in the Dired Buffer
119 @kindex C-n @r{(Dired)}
120 @kindex C-p @r{(Dired)}
121 All the usual Emacs cursor motion commands are available in Dired
122 buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
123 cursor at the beginning of the file name on the line, rather than at
124 the beginning of the line.
126 @kindex SPC @r{(Dired)}
127 For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
128 to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines
129 is so common in Dired that it deserves to be easy to type.) @key{DEL}
130 (move up and unflag) is also often useful simply for moving up
131 (@pxref{Dired Deletion}).
133 @findex dired-goto-file
134 @kindex j @r{(Dired)}
135 @kbd{j} (@code{dired-goto-file}) prompts for a file name using the
136 minibuffer, and moves point to the line in the Dired buffer describing
139 @cindex searching Dired buffers
140 @findex dired-isearch-filenames
141 @vindex dired-isearch-filenames
142 @findex dired-isearch-filenames-regexp
143 @kindex M-s f C-s @r{(Dired)}
144 @kindex M-s f M-C-s @r{(Dired)}
145 @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward
146 incremental search in the Dired buffer, looking for matches only
147 amongst the file names and ignoring the rest of the text in the
148 buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp})
149 does the same, using a regular expression search. If you change the
150 variable @code{dired-isearch-filenames} to @code{t}, then the
151 usual search commands also limit themselves to the file names; for
152 instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. If the value is
153 @code{dwim}, then search commands match the file names only when point
154 was on a file name initially. @xref{Search}, for information about
157 Some additional navigation commands are available when the Dired
158 buffer includes several directories. @xref{Subdirectory Motion}.
161 @section Deleting Files with Dired
162 @cindex flagging files (in Dired)
163 @cindex deleting files (in Dired)
165 One of the most frequent uses of Dired is to first @dfn{flag} files for
166 deletion, then delete the files that were flagged.
170 Flag this file for deletion (@code{dired-flag-file-deletion}).
172 Remove the deletion flag (@code{dired-unmark}).
174 Move point to previous line and remove the deletion flag on that line
175 (@code{dired-unmark-backward}).
177 Delete files flagged for deletion (@code{dired-do-flagged-delete}).
180 @kindex d @r{(Dired)}
181 @findex dired-flag-file-deletion
182 You can flag a file for deletion by moving to the line describing
183 the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The
184 deletion flag is visible as a @samp{D} at the beginning of the line.
185 This command moves point to the next line, so that repeated @kbd{d}
186 commands flag successive files. A numeric prefix argument serves as a
187 repeat count; a negative count means to flag preceding files.
189 If the region is active, the @kbd{d} command flags all files in the
190 region for deletion; in this case, the command does not move point,
191 and ignores any prefix argument.
193 @kindex u @r{(Dired deletion)}
194 @kindex DEL @r{(Dired)}
195 The reason for flagging files for deletion, rather than deleting
196 files immediately, is to reduce the danger of deleting a file
197 accidentally. Until you direct Dired to delete the flagged files, you
198 can remove deletion flags using the commands @kbd{u} and @key{DEL}.
199 @kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes
200 flags rather than making flags. @key{DEL}
201 (@code{dired-unmark-backward}) moves upward, removing flags; it is
202 like @kbd{u} with argument @minus{}1. A numeric prefix argument to
203 either command serves as a repeat count, with a negative count meaning
204 to unflag in the opposite direction. If the region is active, these
205 commands instead unflag all files in the region, without moving point.
207 @kindex x @r{(Dired)}
208 @findex dired-do-flagged-delete
209 To delete flagged files, type @kbd{x}
210 (@code{dired-do-flagged-delete}). This command displays a list of all
211 the file names flagged for deletion, and requests confirmation with
212 @kbd{yes}. If you confirm, Dired deletes the flagged files, then
213 deletes their lines from the text of the Dired buffer. The Dired
214 buffer, with somewhat fewer lines, remains selected.
216 If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
217 return immediately to Dired, with the deletion flags still present in
218 the buffer, and no files actually deleted.
220 @cindex recursive deletion
221 @vindex dired-recursive-deletes
222 You can delete empty directories just like other files, but normally
223 Dired cannot delete directories that are nonempty. If the variable
224 @code{dired-recursive-deletes} is non-@code{nil}, then Dired can
225 delete nonempty directories including all their contents. That can
228 @vindex delete-by-moving-to-trash
229 If you change the variable @code{delete-by-moving-to-trash} to
230 @code{t}, the above deletion commands will move the affected files or
231 directories into the operating system's Trash, instead of deleting
232 them outright. @xref{Misc File Ops}.
234 @node Flagging Many Files
235 @section Flagging Many Files at Once
236 @cindex flagging many files for deletion (in Dired)
238 The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands
239 flag many files for deletion, based on their file names:
243 Flag all auto-save files (files whose names start and end with @samp{#})
244 for deletion (@pxref{Auto Save}).
247 Flag all backup files (files whose names end with @samp{~}) for deletion
250 @item .@: @r{(Period)}
251 Flag excess numeric backup files for deletion. The oldest and newest
252 few backup files of any one file are exempt; the middle ones are
256 Flag for deletion all files with certain kinds of names which suggest
257 you could easily create those files again.
259 @item % d @var{regexp} @key{RET}
260 Flag for deletion all files whose names match the regular expression
264 @kindex # @r{(Dired)}
265 @findex dired-flag-auto-save-files
266 @cindex deleting auto-save files
267 @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose
268 names look like auto-save files---that is, files whose names begin and
269 end with @samp{#}. @xref{Auto Save}.
271 @kindex ~ @r{(Dired)}
272 @findex dired-flag-backup-files
273 @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names
274 say they are backup files---that is, files whose names end in
275 @samp{~}. @xref{Backup}.
277 @kindex . @r{(Dired)}
278 @vindex dired-kept-versions
279 @findex dired-clean-directory
280 @kbd{.} (period, @code{dired-clean-directory}) flags just some of
281 the backup files for deletion: all but the oldest few and newest few
282 backups of any one file. Normally, the number of newest versions kept
283 for each file is given by the variable @code{dired-kept-versions}
284 (@emph{not} @code{kept-new-versions}; that applies only when saving).
285 The number of oldest versions to keep is given by the variable
286 @code{kept-old-versions}.
288 Period with a positive numeric argument, as in @kbd{C-u 3 .},
289 specifies the number of newest versions to keep, overriding
290 @code{dired-kept-versions}. A negative numeric argument overrides
291 @code{kept-old-versions}, using minus the value of the argument to
292 specify the number of oldest versions of each file to keep.
294 @kindex % & @r{(Dired)}
295 @findex dired-flag-garbage-files
296 @vindex dired-garbage-files-regexp
297 @cindex deleting some backup files
298 @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names
299 match the regular expression specified by the variable
300 @code{dired-garbage-files-regexp}. By default, this matches certain
301 files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and
302 @samp{.rej} files produced by @code{patch}.
304 @findex dired-flag-files-regexp
305 @kindex % d @r{(Dired)}
306 @kbd{% d} flags all files whose names match a specified regular
307 expression (@code{dired-flag-files-regexp}). Only the non-directory
308 part of the file name is used in matching. You can use @samp{^} and
309 @samp{$} to anchor matches. You can exclude certain subdirectories
310 from marking by hiding them while you use @kbd{% d}. @xref{Hiding
314 @section Visiting Files in Dired
316 There are several Dired commands for visiting or examining the files
317 listed in the Dired buffer. All of them apply to the current line's
318 file; if that file is really a directory, these commands invoke Dired on
319 that subdirectory (making a separate Dired buffer).
323 @kindex f @r{(Dired)}
324 @findex dired-find-file
325 Visit the file described on the current line, like typing @kbd{C-x C-f}
326 and supplying that file name (@code{dired-find-file}). @xref{Visiting}.
330 @kindex RET @r{(Dired)}
331 @kindex e @r{(Dired)}
332 Equivalent to @kbd{f}.
334 @ignore @c This command seems too risky to document at all.
336 @kindex a @r{(Dired)}
337 @findex dired-find-alternate-file
338 Like @kbd{f}, but replaces the contents of the Dired buffer with
339 that of an alternate file or directory (@code{dired-find-alternate-file}).
343 @kindex o @r{(Dired)}
344 @findex dired-find-file-other-window
345 Like @kbd{f}, but uses another window to display the file's buffer
346 (@code{dired-find-file-other-window}). The Dired buffer remains visible
347 in the first window. This is like using @kbd{C-x 4 C-f} to visit the
348 file. @xref{Windows}.
351 @kindex C-o @r{(Dired)}
352 @findex dired-display-file
353 Visit the file described on the current line, and display the buffer in
354 another window, but do not select that window (@code{dired-display-file}).
358 @findex dired-mouse-find-file-other-window
359 Visit the file whose name you clicked on
360 (@code{dired-mouse-find-file-other-window}). This uses another window
361 to display the file, like the @kbd{o} command.
364 @kindex v @r{(Dired)}
365 @findex dired-view-file
366 View the file described on the current line, with View mode
367 (@code{dired-view-file}). View mode provides convenient commands to
368 navigate the buffer but forbids changing it; @xref{View Mode}.
371 @kindex ^ @r{(Dired)}
372 @findex dired-up-directory
373 Visit the parent directory of the current directory
374 (@code{dired-up-directory}). This is equivalent to moving to the line
375 for @file{..} and typing @kbd{f} there.
379 @section Dired Marks vs. Flags
381 @cindex marking many files (in Dired)
382 Instead of flagging a file with @samp{D}, you can @dfn{mark} the
383 file with some other character (usually @samp{*}). Most Dired
384 commands to operate on files use the files marked with @samp{*}. The
385 only command that operates on flagged files is @kbd{x}, which deletes
388 Here are some commands for marking with @samp{*}, for unmarking, and
389 for operating on marks. (@xref{Dired Deletion}, for commands to flag
395 @kindex m @r{(Dired)}
396 @kindex * m @r{(Dired)}
398 Mark the current file with @samp{*} (@code{dired-mark}). If the
399 region is active, mark all files in the region instead; otherwise, if
400 a numeric argument @var{n} is supplied, mark the next @var{n} files
401 instead, starting with the current file (if @var{n} is negative, mark
402 the previous @minus{}@var{n} files).
405 @kindex * * @r{(Dired)}
406 @findex dired-mark-executables
407 @cindex marking executable files (in Dired)
408 Mark all executable files with @samp{*}
409 (@code{dired-mark-executables}). With a numeric argument, unmark all
413 @kindex * @@ @r{(Dired)}
414 @findex dired-mark-symlinks
415 @cindex marking symbolic links (in Dired)
416 Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
417 With a numeric argument, unmark all those files.
420 @kindex * / @r{(Dired)}
421 @findex dired-mark-directories
422 @cindex marking subdirectories (in Dired)
423 Mark with @samp{*} all files which are directories, except for
424 @file{.} and @file{..} (@code{dired-mark-directories}). With a numeric
425 argument, unmark all those files.
428 @kindex * s @r{(Dired)}
429 @findex dired-mark-subdir-files
430 Mark all the files in the current subdirectory, aside from @file{.}
431 and @file{..} (@code{dired-mark-subdir-files}).
435 @kindex u @r{(Dired)}
436 @kindex * u @r{(Dired)}
438 Remove any mark on this line (@code{dired-unmark}). If the region is
439 active, unmark all files in the region instead; otherwise, if a
440 numeric argument @var{n} is supplied, unmark the next @var{n} files
441 instead, starting with the current file (if @var{n} is negative,
442 unmark the previous @minus{}@var{n} files).
446 @kindex * DEL @r{(Dired)}
447 @findex dired-unmark-backward
448 @cindex unmarking files (in Dired)
449 Move point to previous line and remove any mark on that line
450 (@code{dired-unmark-backward}). If the region is active, unmark all
451 files in the region instead; otherwise, if a numeric argument @var{n}
452 is supplied, unmark the @var{n} preceding files instead, starting with
453 the current file (if @var{n} is negative, unmark the next
454 @minus{}@var{n} files).
458 @kindex * ! @r{(Dired)}
459 @kindex U @r{(Dired)}
460 @findex dired-unmark-all-marks
461 Remove all marks from all the files in this Dired buffer
462 (@code{dired-unmark-all-marks}).
464 @item * ? @var{markchar}
466 @kindex * ? @r{(Dired)}
467 @kindex M-DEL @r{(Dired)}
468 @findex dired-unmark-all-files
469 Remove all marks that use the character @var{markchar}
470 (@code{dired-unmark-all-files}). The argument is a single
471 character---do not use @key{RET} to terminate it. See the description
472 of the @kbd{* c} command below, which lets you replace one mark
473 character with another.
475 With a numeric argument, this command queries about each marked file,
476 asking whether to remove its mark. You can answer @kbd{y} meaning yes,
477 @kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining
478 files without asking about them.
482 @findex dired-next-marked-file
483 @kindex * C-n @r{(Dired)}
484 @kindex M-@} @r{(Dired)}
485 Move down to the next marked file (@code{dired-next-marked-file})
486 A file is ``marked'' if it has any kind of mark.
490 @findex dired-prev-marked-file
491 @kindex * C-p @r{(Dired)}
492 @kindex M-@{ @r{(Dired)}
493 Move up to the previous marked file (@code{dired-prev-marked-file})
497 @kindex t @r{(Dired)}
498 @kindex * t @r{(Dired)}
499 @findex dired-toggle-marks
500 @cindex toggling marks (in Dired)
501 Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*}
502 become unmarked, and unmarked files are marked with @samp{*}. Files
503 marked in any other way are not affected.
505 @item * c @var{old-markchar} @var{new-markchar}
506 @kindex * c @r{(Dired)}
507 @findex dired-change-marks
508 Replace all marks that use the character @var{old-markchar} with marks
509 that use the character @var{new-markchar} (@code{dired-change-marks}).
510 This command is the primary way to create or use marks other than
511 @samp{*} or @samp{D}. The arguments are single characters---do not use
512 @key{RET} to terminate them.
514 You can use almost any character as a mark character by means of this
515 command, to distinguish various classes of files. If @var{old-markchar}
516 is a space (@samp{ }), then the command operates on all unmarked files;
517 if @var{new-markchar} is a space, then the command unmarks the files it
520 To illustrate the power of this command, here is how to put @samp{D}
521 flags on all the files that have no marks, while unflagging all those
522 that already have @samp{D} flags:
525 * c D t * c @key{SPC} D * c t @key{SPC}
528 This assumes that no files were already marked with @samp{t}.
530 @item % m @var{regexp} @key{RET}
531 @itemx * % @var{regexp} @key{RET}
532 @findex dired-mark-files-regexp
533 @kindex % m @r{(Dired)}
534 @kindex * % @r{(Dired)}
535 Mark (with @samp{*}) all files whose names match the regular expression
536 @var{regexp} (@code{dired-mark-files-regexp}). This command is like
537 @kbd{% d}, except that it marks files with @samp{*} instead of flagging
540 Only the non-directory part of the file name is used in matching. Use
541 @samp{^} and @samp{$} to anchor matches. You can exclude
542 subdirectories by temporarily hiding them (@pxref{Hiding
545 @item % g @var{regexp} @key{RET}
546 @findex dired-mark-files-containing-regexp
547 @kindex % g @r{(Dired)}
548 @cindex finding files containing regexp matches (in Dired)
549 Mark (with @samp{*}) all files whose @emph{contents} contain a match for
550 the regular expression @var{regexp}
551 (@code{dired-mark-files-containing-regexp}). This command is like
552 @kbd{% m}, except that it searches the file contents instead of the file
558 @kindex C-_ @r{(Dired)}
560 Undo changes in the Dired buffer, such as adding or removing
561 marks (@code{dired-undo}). @emph{This command does not revert the
562 actual file operations, nor recover lost files!} It just undoes
563 changes in the buffer itself.
565 In some cases, using this after commands that operate on files can
566 cause trouble. For example, after renaming one or more files,
567 @code{dired-undo} restores the original names in the Dired buffer,
568 which gets the Dired buffer out of sync with the actual contents of
572 @node Operating on Files
573 @section Operating on Files
574 @cindex operating on files in Dired
576 This section describes the basic Dired commands to operate on one file
577 or several files. All of these commands are capital letters; all of
578 them use the minibuffer, either to read an argument or to ask for
579 confirmation, before they act. All of them let you specify the
580 files to manipulate in these ways:
584 If you give the command a numeric prefix argument @var{n}, it operates
585 on the next @var{n} files, starting with the current file. (If @var{n}
586 is negative, the command operates on the @minus{}@var{n} files preceding
590 Otherwise, if some files are marked with @samp{*}, the command operates
594 Otherwise, the command operates on the current file only.
598 Certain other Dired commands, such as @kbd{!} and the @samp{%}
599 commands, use the same conventions to decide which files to work on.
601 @vindex dired-dwim-target
602 @cindex two directories (in Dired)
603 Commands which ask for a destination directory, such as those which
604 copy and rename files or create links for them, try to guess the default
605 target directory for the operation. Normally, they suggest the Dired
606 buffer's default directory, but if the variable @code{dired-dwim-target}
607 is non-@code{nil}, and if there is another Dired buffer displayed in the
608 next window, that other buffer's directory is suggested instead.
610 Here are the file-manipulating Dired commands that operate on files.
613 @findex dired-do-copy
614 @kindex C @r{(Dired)}
615 @cindex copying files (in Dired)
616 @item C @var{new} @key{RET}
617 Copy the specified files (@code{dired-do-copy}). The argument @var{new}
618 is the directory to copy into, or (if copying a single file) the new
619 name. This is like the shell command @code{cp}.
621 @vindex dired-copy-preserve-time
622 If @code{dired-copy-preserve-time} is non-@code{nil}, then copying
623 with this command preserves the modification time of the old file in
624 the copy, like @samp{cp -p}.
626 @vindex dired-recursive-copies
627 @cindex recursive copying
628 The variable @code{dired-recursive-copies} controls whether to copy
629 directories recursively (like @samp{cp -r}). The default is
630 @code{top}, which means to ask before recursively copying a directory.
633 @findex dired-do-delete
634 @kindex D @r{(Dired)}
635 Delete the specified files (@code{dired-do-delete}). This is like the
636 shell command @code{rm}.
638 Like the other commands in this section, this command operates on the
639 @emph{marked} files, or the next @var{n} files. By contrast, @kbd{x}
640 (@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files.
642 @findex dired-do-rename
643 @kindex R @r{(Dired)}
644 @cindex renaming files (in Dired)
645 @cindex moving files (in Dired)
646 @item R @var{new} @key{RET}
647 Rename the specified files (@code{dired-do-rename}). If you rename a
648 single file, the argument @var{new} is the new name of the file. If
649 you rename several files, the argument @var{new} is the directory into
650 which to move the files (this is like the shell command @command{mv}).
652 Dired automatically changes the visited file name of buffers associated
653 with renamed files so that they refer to the new names.
655 @findex dired-do-hardlink
656 @kindex H @r{(Dired)}
657 @cindex hard links (in Dired)
658 @item H @var{new} @key{RET}
659 Make hard links to the specified files (@code{dired-do-hardlink}).
660 This is like the shell command @command{ln}. The argument @var{new} is
661 the directory to make the links in, or (if making just one link) the
662 name to give the link.
664 @findex dired-do-symlink
665 @kindex S @r{(Dired)}
666 @cindex symbolic links (creation in Dired)
667 @item S @var{new} @key{RET}
668 Make symbolic links to the specified files (@code{dired-do-symlink}).
669 This is like @samp{ln -s}. The argument @var{new} is the directory to
670 make the links in, or (if making just one link) the name to give the
673 @findex dired-do-chmod
674 @kindex M @r{(Dired)}
675 @cindex changing file permissions (in Dired)
676 @item M @var{modespec} @key{RET}
677 Change the mode (also called @dfn{permission bits}) of the specified
678 files (@code{dired-do-chmod}). @var{modespec} can be in octal or
679 symbolic notation, like arguments handled by the @command{chmod}
682 @findex dired-do-chgrp
683 @kindex G @r{(Dired)}
684 @cindex changing file group (in Dired)
685 @item G @var{newgroup} @key{RET}
686 Change the group of the specified files to @var{newgroup}
687 (@code{dired-do-chgrp}).
689 @findex dired-do-chown
690 @kindex O @r{(Dired)}
691 @cindex changing file owner (in Dired)
692 @item O @var{newowner} @key{RET}
693 Change the owner of the specified files to @var{newowner}
694 (@code{dired-do-chown}). (On most systems, only the superuser can do
697 @vindex dired-chown-program
698 The variable @code{dired-chown-program} specifies the name of the
699 program to use to do the work (different systems put @command{chown}
700 in different places).
702 @findex dired-do-touch
703 @kindex T @r{(Dired)}
704 @cindex changing file time (in Dired)
705 @item T @var{timestamp} @key{RET}
706 Touch the specified files (@code{dired-do-touch}). This means
707 updating their modification times to the present time. This is like
708 the shell command @code{touch}.
710 @findex dired-do-print
711 @kindex P @r{(Dired)}
712 @cindex printing files (in Dired)
713 @item P @var{command} @key{RET}
714 Print the specified files (@code{dired-do-print}). You must specify the
715 command to print them with, but the minibuffer starts out with a
716 suitable guess made using the variables @code{lpr-command} and
717 @code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
720 @findex dired-do-compress
721 @kindex Z @r{(Dired)}
722 @cindex compressing files (in Dired)
724 Compress the specified files (@code{dired-do-compress}). If the file
725 appears to be a compressed file already, uncompress it instead.
727 @findex epa-dired-do-decrypt
728 @kindex :d @r{(Dired)}
729 @cindex decrypting files (in Dired)
731 Decrypt the specified files (@code{epa-dired-do-decrypt}).
732 @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
734 @findex epa-dired-do-verify
735 @kindex :v @r{(Dired)}
736 @cindex verifying digital signatures on files (in Dired)
738 Verify digital signatures on the specified files (@code{epa-dired-do-verify}).
739 @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
741 @findex epa-dired-do-sign
742 @kindex :s @r{(Dired)}
743 @cindex signing files (in Dired)
745 Digitally sign the specified files (@code{epa-dired-do-sign}).
746 @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
748 @findex epa-dired-do-encrypt
749 @kindex :e @r{(Dired)}
750 @cindex encrypting files (in Dired)
752 Encrypt the specified files (@code{epa-dired-do-encrypt}).
753 @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
755 @findex dired-do-load
756 @kindex L @r{(Dired)}
757 @cindex loading several files (in Dired)
759 Load the specified Emacs Lisp files (@code{dired-do-load}).
760 @xref{Lisp Libraries}.
762 @findex dired-do-byte-compile
763 @kindex B @r{(Dired)}
764 @cindex byte-compiling several files (in Dired)
766 Byte compile the specified Emacs Lisp files
767 (@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte
768 Compilation, elisp, The Emacs Lisp Reference Manual}.
770 @kindex A @r{(Dired)}
771 @findex dired-do-search
772 @cindex search multiple files (in Dired)
773 @item A @var{regexp} @key{RET}
774 Search all the specified files for the regular expression @var{regexp}
775 (@code{dired-do-search}).
777 This command is a variant of @code{tags-search}. The search stops at
778 the first match it finds; use @kbd{M-,} to resume the search and find
779 the next match. @xref{Tags Search}.
781 @kindex Q @r{(Dired)}
782 @findex dired-do-query-replace-regexp
783 @cindex search and replace in multiple files (in Dired)
784 @item Q @var{regexp} @key{RET} @var{to} @key{RET}
785 Perform @code{query-replace-regexp} on each of the specified files,
786 replacing matches for @var{regexp} with the string
787 @var{to} (@code{dired-do-query-replace-regexp}).
789 This command is a variant of @code{tags-query-replace}. If you exit the
790 query replace loop, you can use @kbd{M-,} to resume the scan and replace
791 more matches. @xref{Tags Search}.
794 @node Shell Commands in Dired
795 @section Shell Commands in Dired
796 @cindex shell commands, Dired
798 @findex dired-do-shell-command
799 @kindex ! @r{(Dired)}
800 @kindex X @r{(Dired)}
801 The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a
802 shell command string in the minibuffer, and runs that shell command on
803 one or more files. The files that the shell command operates on are
804 determined in the usual way for Dired commands (@pxref{Operating on
805 Files}). The command @kbd{X} is a synonym for @kbd{!}.
807 The command @kbd{&} (@code{dired-do-async-shell-command}) does the
808 same, except that it runs the shell command asynchronously. (You can
809 also do this with @kbd{!}, by appending a @samp{&} character to the
810 end of the shell command.) When the command operates on more than one
811 file, it runs multiple parallel copies of the specified shell command,
812 one for each file. As an exception, if the specified shell command
813 ends in @samp{;} or @samp{;&}, the shell command is run in the
814 background on each file sequentially; Emacs waits for each invoked
815 shell command to terminate before running the next one.
817 For both @kbd{!} and @kbd{&}, the working directory for the shell
818 command is the top-level directory of the Dired buffer.
820 If you tell @kbd{!} or @kbd{&} to operate on more than one file, the
821 shell command string determines how those files are passed to the
826 If you use @samp{*} surrounded by whitespace in the command string,
827 then the command runs just once, with the list of file names
828 substituted for the @samp{*}. The order of file names is the order of
829 appearance in the Dired buffer.
831 Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
832 list of file names, putting them into one tar file @file{foo.tar}.
834 If you want to use @samp{*} as a shell wildcard with whitespace around
835 it, write @samp{*""}. In the shell, this is equivalent to @samp{*};
836 but since the @samp{*} is not surrounded by whitespace, Dired does not
840 Otherwise, if the command string contains @samp{?} surrounded by
841 whitespace, Emacs runs the shell command once @emph{for each file},
842 substituting the current file name for @samp{?} each time. You can
843 use @samp{?} more than once in the command; the same file name
844 replaces each occurrence.
847 If the command string contains neither @samp{*} nor @samp{?}, Emacs
848 runs the shell command once for each file, adding the file name at the
849 end. For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on
853 To iterate over the file names in a more complicated fashion, use an
854 explicit shell loop. For example, here is how to uuencode each file,
855 making the output file name by appending @samp{.uu} to the input file
859 for file in * ; do uuencode "$file" "$file" >"$file".uu; done
862 The @kbd{!} and @kbd{&} commands do not attempt to update the Dired
863 buffer to show new or modified files, because they don't know what
864 files will be changed. Use the @kbd{g} command to update the Dired
865 buffer (@pxref{Dired Updating}).
867 @xref{Single Shell}, for information about running shell commands
870 @node Transforming File Names
871 @section Transforming File Names in Dired
873 This section describes Dired commands which alter file names in a
874 systematic way. Each command operates on some or all of the marked
875 files, using a new name made by transforming the existing name.
877 Like the basic Dired file-manipulation commands (@pxref{Operating on
878 Files}), the commands described here operate either on the next
879 @var{n} files, or on all files marked with @samp{*}, or on the current
880 file. (To mark files, use the commands described in @ref{Marks vs
883 All of the commands described in this section work
884 @emph{interactively}: they ask you to confirm the operation for each
885 candidate file. Thus, you can select more files than you actually
886 need to operate on (e.g., with a regexp that matches many files), and
887 then filter the selected names by typing @kbd{y} or @kbd{n} when the
888 command prompts for confirmation.
892 @kindex % u @r{(Dired)}
893 @cindex upcase file names
895 Rename each of the selected files to an upper-case name
896 (@code{dired-upcase}). If the old file names are @file{Foo}
897 and @file{bar}, the new names are @file{FOO} and @file{BAR}.
900 @findex dired-downcase
901 @kindex % l @r{(Dired)}
902 @cindex downcase file names
903 Rename each of the selected files to a lower-case name
904 (@code{dired-downcase}). If the old file names are @file{Foo} and
905 @file{bar}, the new names are @file{foo} and @file{bar}.
907 @item % R @var{from} @key{RET} @var{to} @key{RET}
908 @kindex % R @r{(Dired)}
909 @findex dired-do-rename-regexp
910 @itemx % C @var{from} @key{RET} @var{to} @key{RET}
911 @kindex % C @r{(Dired)}
912 @findex dired-do-copy-regexp
913 @itemx % H @var{from} @key{RET} @var{to} @key{RET}
914 @kindex % H @r{(Dired)}
915 @findex dired-do-hardlink-regexp
916 @itemx % S @var{from} @key{RET} @var{to} @key{RET}
917 @kindex % S @r{(Dired)}
918 @findex dired-do-symlink-regexp
919 These four commands rename, copy, make hard links and make soft links,
920 in each case computing the new name by regular-expression substitution
921 from the name of the old file.
924 The four regular-expression substitution commands effectively
925 perform a search-and-replace on the selected file names. They read
926 two arguments: a regular expression @var{from}, and a substitution
927 pattern @var{to}; they match each ``old'' file name against
928 @var{from}, and then replace the matching part with @var{to}. You can
929 use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or
930 part of what the pattern matched in the old file name, as in
931 @code{replace-regexp} (@pxref{Regexp Replace}). If the regular
932 expression matches more than once in a file name, only the first match
935 For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
936 selected file by prepending @samp{x-} to its name. The inverse of this,
937 removing @samp{x-} from the front of each file name, is also possible:
938 one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is
939 @kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor
940 matches that should span the whole file name.)
942 Normally, the replacement process does not consider the files'
943 directory names; it operates on the file name within the directory. If
944 you specify a numeric argument of zero, then replacement affects the
945 entire absolute file name including directory name. (A non-zero
946 argument specifies the number of files to operate on.)
948 You may want to select the set of files to operate on using the same
949 regexp @var{from} that you will use to operate on them. To do this,
950 mark those files with @kbd{% m @var{from} @key{RET}}, then use the
951 same regular expression in the command to operate on the files. To
952 make this more convenient, the @kbd{%} commands to operate on files
953 use the last regular expression specified in any @kbd{%} command as a
956 @node Comparison in Dired
957 @section File Comparison with Dired
958 @cindex file comparison (in Dired)
959 @cindex compare files (in Dired)
962 @kindex = @r{(Dired)}
963 The @kbd{=} (@code{dired-diff}) command compares the current file
964 (the file at point) with another file (read using the minibuffer)
965 using the @command{diff} program. The file specified with the
966 minibuffer is the first argument of @command{diff}, and file at point
967 is the second argument. The output of the @command{diff} program is
968 shown in a buffer using Diff mode (@pxref{Comparing Files}).
970 If the region is active, the default for the file read using the
971 minibuffer is the file at the mark (i.e., the ordinary Emacs mark,
972 not a Dired mark; @pxref{Setting Mark}). Otherwise, if the file at
973 point has a backup file (@pxref{Backup}), that is the default.
975 @node Subdirectories in Dired
976 @section Subdirectories in Dired
977 @cindex subdirectories in Dired
978 @cindex expanding subdirectories in Dired
980 A Dired buffer usually displays just one directory, but you can
981 optionally include its subdirectories as well.
983 The simplest way to include multiple directories in one Dired buffer is
984 to specify the options @samp{-lR} for running @command{ls}. (If you give a
985 numeric argument when you run Dired, then you can specify these options
986 in the minibuffer.) That produces a recursive directory listing showing
987 all subdirectories at all levels.
989 More often, you will want to show only specific subdirectories. You
990 can do this with @kbd{i} (@code{dired-maybe-insert-subdir}):
993 @findex dired-maybe-insert-subdir
994 @kindex i @r{(Dired)}
996 @cindex inserted subdirectory (Dired)
997 @cindex in-situ subdirectory (Dired)
998 Insert the contents of a subdirectory later in the buffer.
1002 If you use this command on a line that describes a file which is a
1003 directory, it inserts the contents of that directory into the same
1004 Dired buffer, and moves there. Inserted subdirectory contents follow
1005 the top-level directory of the Dired buffer, just as they do in
1006 @samp{ls -lR} output.
1008 If the subdirectory's contents are already present in the buffer,
1009 the @kbd{i} command just moves to it.
1011 In either case, @kbd{i} sets the Emacs mark before moving, so
1012 @kbd{C-u C-@key{SPC}} returns to your previous position in the Dired
1013 buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to
1014 the parent directory in the same Dired buffer (@pxref{Dired
1017 Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
1018 subdirectory's contents, and use @kbd{C-u k} on the subdirectory
1019 header line to remove the subdirectory listing (@pxref{Dired
1020 Updating}). You can also hide and show inserted subdirectories
1021 (@pxref{Hiding Subdirectories}).
1024 @include dired-xtra.texi
1027 @node Subdirectory Motion
1028 @section Moving Over Subdirectories
1030 When a Dired buffer lists subdirectories, you can use the page motion
1031 commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories
1034 @cindex header line (Dired)
1035 @cindex directory header lines
1036 The following commands move across, up and down in the tree of
1037 directories within one Dired buffer. They move to @dfn{directory header
1038 lines}, which are the lines that give a directory's name, at the
1039 beginning of the directory's contents.
1042 @findex dired-next-subdir
1043 @kindex C-M-n @r{(Dired)}
1045 Go to next subdirectory header line, regardless of level
1046 (@code{dired-next-subdir}).
1048 @findex dired-prev-subdir
1049 @kindex C-M-p @r{(Dired)}
1051 Go to previous subdirectory header line, regardless of level
1052 (@code{dired-prev-subdir}).
1054 @findex dired-tree-up
1055 @kindex C-M-u @r{(Dired)}
1057 Go up to the parent directory's header line (@code{dired-tree-up}).
1059 @findex dired-tree-down
1060 @kindex C-M-d @r{(Dired)}
1062 Go down in the directory tree, to the first subdirectory's header line
1063 (@code{dired-tree-down}).
1065 @findex dired-prev-dirline
1066 @kindex < @r{(Dired)}
1068 Move up to the previous directory-file line (@code{dired-prev-dirline}).
1069 These lines are the ones that describe a directory as a file in its
1072 @findex dired-next-dirline
1073 @kindex > @r{(Dired)}
1075 Move down to the next directory-file line (@code{dired-prev-dirline}).
1078 @node Hiding Subdirectories
1079 @section Hiding Subdirectories
1080 @cindex hiding subdirectories (Dired)
1081 @cindex showing hidden subdirectories (Dired)
1083 @dfn{Hiding} a subdirectory means to make it invisible, except for its
1088 @findex dired-hide-subdir
1089 @kindex $ @r{(Dired)}
1090 Hide or show the subdirectory that point is in, and move point to the
1091 next subdirectory (@code{dired-hide-subdir}). This is a toggle. A
1092 numeric argument serves as a repeat count.
1095 @findex dired-hide-all
1096 @kindex M-$ @r{(Dired)}
1097 Hide all subdirectories in this Dired buffer, leaving only their header
1098 lines (@code{dired-hide-all}). Or, if any subdirectory is currently
1099 hidden, make all subdirectories visible again. You can use this command
1100 to get an overview in very deep directory trees or to move quickly to
1101 subdirectories far away.
1104 Ordinary Dired commands never consider files inside a hidden
1105 subdirectory. For example, the commands to operate on marked files
1106 ignore files in hidden directories even if they are marked. Thus you
1107 can use hiding to temporarily exclude subdirectories from operations
1108 without having to remove the Dired marks on files in those
1111 @xref{Subdirectories in Dired}, for how to insert a subdirectory
1112 listing, and @pxref{Dired Updating} for how delete it.
1114 @node Dired Updating
1115 @section Updating the Dired Buffer
1116 @cindex updating Dired buffer
1117 @cindex refreshing displayed files
1119 This section describes commands to update the Dired buffer to reflect
1120 outside (non-Dired) changes in the directories and files, and to delete
1121 part of the Dired buffer.
1125 Update the entire contents of the Dired buffer (@code{revert-buffer}).
1128 Update the specified files (@code{dired-do-redisplay}). You specify the
1129 files for @kbd{l} in the same way as for file operations.
1132 Delete the specified @emph{file lines}---not the files, just the lines
1133 (@code{dired-do-kill-lines}).
1136 Toggle between alphabetical order and date/time order
1137 (@code{dired-sort-toggle-or-edit}).
1139 @item C-u s @var{switches} @key{RET}
1140 Refresh the Dired buffer using @var{switches} as
1141 @code{dired-listing-switches}.
1144 @kindex g @r{(Dired)}
1145 @findex revert-buffer @r{(Dired)}
1146 Type @kbd{g} (@code{revert-buffer}) to update the contents of the
1147 Dired buffer, based on changes in the files and directories listed.
1148 This preserves all marks except for those on files that have vanished.
1149 Hidden subdirectories are updated but remain hidden.
1151 @kindex l @r{(Dired)}
1152 @findex dired-do-redisplay
1153 To update only some of the files, type @kbd{l}
1154 (@code{dired-do-redisplay}). Like the Dired file-operating commands,
1155 this command operates on the next @var{n} files (or previous
1156 @minus{}@var{n} files), or on the marked files if any, or on the
1157 current file. Updating the files means reading their current status,
1158 then updating their lines in the buffer to indicate that status.
1160 If you use @kbd{l} on a subdirectory header line, it updates the
1161 contents of the corresponding subdirectory.
1163 @vindex dired-auto-revert-buffer
1164 If you use @kbd{C-x d} or some other Dired command to visit a
1165 directory that is already being shown in a Dired buffer, Dired
1166 switches to that buffer but does not update it. If the buffer is not
1167 up-to-date, Dired displays a warning telling you to type @key{g} to
1168 update it. You can also tell Emacs to revert each Dired buffer
1169 automatically when you revisit it, by setting the variable
1170 @code{dired-auto-revert-buffer} to a non-@code{nil} value.
1172 @kindex k @r{(Dired)}
1173 @findex dired-do-kill-lines
1174 To delete @emph{file lines} from the buffer---without actually
1175 deleting the files---type @kbd{k} (@code{dired-do-kill-lines}). Like
1176 the file-operating commands, this command operates on the next @var{n}
1177 files, or on the marked files if any. However, it does not operate on
1178 the current file, since otherwise mistyping @kbd{k} could be annoying.
1180 If you use @kbd{k} to kill the line for a directory file which you
1181 had inserted in the Dired buffer as a subdirectory
1182 (@pxref{Subdirectories in Dired}), it removes the subdirectory listing
1183 as well. Typing @kbd{C-u k} on the header line for a subdirectory
1184 also removes the subdirectory line from the Dired buffer.
1186 The @kbd{g} command brings back any individual lines that you have
1187 killed in this way, but not subdirectories---you must use @kbd{i} to
1188 reinsert a subdirectory.
1190 @cindex Dired sorting
1191 @cindex sorting Dired buffer
1192 @kindex s @r{(Dired)}
1193 @findex dired-sort-toggle-or-edit
1194 The files in a Dired buffers are normally listed in alphabetical order
1195 by file names. Alternatively Dired can sort them by date/time. The
1196 Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches
1197 between these two sorting modes. The mode line in a Dired buffer
1198 indicates which way it is currently sorted---by name, or by date.
1200 @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for
1201 @code{dired-listing-switches}.
1203 @node Dired and Find
1204 @section Dired and @code{find}
1205 @cindex @code{find} and Dired
1207 You can select a set of files for display in a Dired buffer more
1208 flexibly by using the @command{find} utility to choose the files.
1210 @findex find-name-dired
1211 To search for files with names matching a wildcard pattern use
1212 @kbd{M-x find-name-dired}. It reads arguments @var{directory} and
1213 @var{pattern}, and chooses all the files in @var{directory} or its
1214 subdirectories whose individual names match @var{pattern}.
1216 The files thus chosen are displayed in a Dired buffer, in which the
1217 ordinary Dired commands are available.
1219 @findex find-grep-dired
1220 If you want to test the contents of files, rather than their names,
1221 use @kbd{M-x find-grep-dired}. This command reads two minibuffer
1222 arguments, @var{directory} and @var{regexp}; it chooses all the files
1223 in @var{directory} or its subdirectories that contain a match for
1224 @var{regexp}. It works by running the programs @command{find} and
1225 @command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep
1226 Searching}. Remember to write the regular expression for
1227 @command{grep}, not for Emacs. (An alternative method of showing
1228 files whose contents match a given regexp is the @kbd{% g
1229 @var{regexp}} command, see @ref{Marks vs Flags}.)
1232 The most general command in this series is @kbd{M-x find-dired},
1233 which lets you specify any condition that @command{find} can test. It
1234 takes two minibuffer arguments, @var{directory} and @var{find-args};
1235 it runs @command{find} in @var{directory}, passing @var{find-args} to
1236 tell @command{find} what condition to test. To use this command, you
1237 need to know how to use @command{find}.
1239 @vindex find-ls-option
1240 The format of listing produced by these commands is controlled by
1241 the variable @code{find-ls-option}. This is a pair of options; the
1242 first specifying how to call @command{find} to produce the file listing,
1243 and the second telling Dired to parse the output.
1246 @findex locate-with-filter
1247 @cindex file database (locate)
1248 @vindex locate-command
1249 The command @kbd{M-x locate} provides a similar interface to the
1250 @command{locate} program. @kbd{M-x locate-with-filter} is similar, but
1251 keeps only files whose names match a given regular expression.
1253 These buffers don't work entirely like ordinary Dired buffers: file
1254 operations work, but do not always automatically update the buffer.
1255 Reverting the buffer with @kbd{g} deletes all inserted subdirectories,
1256 and erases all flags and marks.
1259 @section Editing the Dired Buffer
1262 @findex wdired-change-to-wdired-mode
1263 Wdired is a special mode that allows you to perform file operations
1264 by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands
1265 for ``writable''.) To enter Wdired mode, type @kbd{C-x C-q}
1266 (@code{dired-toggle-read-only}) while in a Dired buffer.
1267 Alternatively, use the @samp{Immediate / Edit File Names} menu item.
1269 @findex wdired-finish-edit
1270 While in Wdired mode, you can rename files by editing the file names
1271 displayed in the Dired buffer. All the ordinary Emacs editing
1272 commands, including rectangle operations and @code{query-replace}, are
1273 available for this. Once you are done editing, type @kbd{C-c C-c}
1274 (@code{wdired-finish-edit}). This applies your changes and switches
1275 back to ordinary Dired mode.
1277 Apart from simply renaming files, you can move a file to another
1278 directory by typing in the new file name (either absolute or
1279 relative). To mark a file for deletion, delete the entire file name.
1280 To change the target of a symbolic link, edit the link target name
1281 which appears next to the link name.
1283 The rest of the text in the buffer, such as the file sizes and
1284 modification dates, is marked read-only, so you can't edit it.
1285 However, if you set @code{wdired-allow-to-change-permissions} to
1286 @code{t}, you can edit the file permissions. For example, you can
1287 change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file
1288 world-writable. These changes also take effect when you type @kbd{C-c
1292 @section Viewing Image Thumbnails in Dired
1293 @cindex image-dired mode
1296 Image-Dired is a facility for browsing image files. It provides viewing
1297 the images either as thumbnails or in full size, either inside Emacs
1298 or through an external viewer.
1300 @kindex C-t d @r{(Image-Dired)}
1301 @findex image-dired-display-thumbs
1302 To enter Image-Dired, mark the image files you want to look at in
1303 the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d}
1304 (@code{image-dired-display-thumbs}). This creates and switches to a
1305 buffer containing image-dired, corresponding to the marked files.
1307 You can also enter Image-Dired directly by typing @kbd{M-x
1308 image-dired}. This prompts for a directory; specify one that has
1309 image files. This creates thumbnails for all the images in that
1310 directory, and displays them all in the ``thumbnail buffer''. This
1311 takes a long time if the directory contains many image files, and it
1312 asks for confirmation if the number of image files exceeds
1313 @code{image-dired-show-all-from-dir-max-files}.
1315 With point in the thumbnail buffer, you can type @key{RET}
1316 (@code{image-dired-display-thumbnail-original-image}) to display a
1317 sized version of it in another window. This sizes the image to fit
1318 the window. Use the arrow keys to move around in the buffer. For
1319 easy browsing, use @key{SPC}
1320 (@code{image-dired-display-next-thumbnail-original}) to advance and
1321 display the next image. Typing @key{DEL}
1322 (@code{image-dired-display-previous-thumbnail-original}) backs up to
1323 the previous thumbnail and displays that instead.
1325 @vindex image-dired-external-viewer
1326 To view and the image in its original size, either provide a prefix
1327 argument (@kbd{C-u}) before pressing @key{RET}, or type
1328 @kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to
1329 display the image in an external viewer. You must first configure
1330 @code{image-dired-external-viewer}.
1332 You can delete images through Image-Dired also. Type @kbd{d}
1333 (@code{image-dired-flag-thumb-original-file}) to flag the image file
1334 for deletion in the Dired buffer. You can also delete the thumbnail
1335 image from the thumbnail buffer with @kbd{C-d}
1336 (@code{image-dired-delete-char}).
1338 More advanced features include @dfn{image tags}, which are metadata
1339 used to categorize image files. The tags are stored in a plain text
1340 file configured by @code{image-dired-db-file}.
1342 To tag image files, mark them in the dired buffer (you can also mark
1343 files in Dired from the thumbnail buffer by typing @kbd{m}) and type
1344 @kbd{C-t t} (@code{image-dired-tag-files}). This reads the tag name
1345 in the minibuffer. To mark files having a certain tag, type @kbd{C-t f}
1346 (@code{image-dired-mark-tagged-files}). After marking image files
1347 with a certain tag, you can use @kbd{C-t d} to view them.
1349 You can also tag a file directly from the thumbnail buffer by typing
1350 @kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also
1351 a special ``tag'' called ``comment'' for each file (it is not a tag in
1352 the exact same sense as the other tags, it is handled slightly
1353 different). That is used to enter a comment or description about the
1354 image. You comment a file from the thumbnail buffer by typing
1355 @kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add
1356 a comment from Dired (@code{image-dired-dired-comment-files}).
1358 Image-Dired also provides simple image manipulation. In the
1359 thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees
1360 anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This
1361 rotation is lossless, and uses an external utility called JpegTRAN.
1363 @node Misc Dired Features
1364 @section Other Dired Features
1366 @kindex + @r{(Dired)}
1367 @findex dired-create-directory
1368 The command @kbd{+} (@code{dired-create-directory}) reads a
1369 directory name, and creates that directory. It signals an error if
1370 the directory already exists.
1372 @cindex searching multiple files via Dired
1373 @kindex M-s a C-s @r{(Dired)}
1374 @kindex M-s a M-C-s @r{(Dired)}
1375 @findex dired-do-isearch
1376 @findex dired-do-isearch-regexp
1377 The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a
1378 ``multi-file'' incremental search on the marked files. If a search
1379 fails at the end of a file, typing @kbd{C-s} advances to the next
1380 marked file and repeats the search; at the end of the last marked
1381 file, the search wraps around to the first marked file. The command
1382 @kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with
1383 a regular expression search. @xref{Repeat Isearch}, for information
1384 about search repetition.
1386 @cindex adding to the kill ring in Dired
1387 @kindex w @r{(Dired)}
1388 @findex dired-copy-filename-as-kill
1389 The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the
1390 names of the marked (or next @var{n}) files into the kill ring, as if
1391 you had killed them with @kbd{C-w}. The names are separated by a
1394 With a zero prefix argument, this uses the absolute file name of
1395 each marked file. With just @kbd{C-u} as the prefix argument, it uses
1396 file names relative to the Dired buffer's default directory. (This
1397 can still contain slashes if in a subdirectory.) As a special case,
1398 if point is on a directory headerline, @kbd{w} gives you the absolute
1399 name of that directory. Any prefix argument or marked files are
1400 ignored in this case.
1402 The main purpose of this command is so that you can yank the file
1403 names into arguments for other Emacs commands. It also displays what
1404 it added to the kill ring, so you can use it to display the list of
1405 currently marked files in the echo area.
1407 @kindex ( @r{(Dired)}
1408 @findex dired-hide-details-mode
1409 @vindex dired-hide-details-hide-symlink-targets
1410 @vindex dired-hide-details-hide-information-lines
1411 @cindex hiding details in Dired
1412 The command @kbd{(} (@code{dired-hide-details-mode}) toggles whether
1413 details, such as ownership or file permissions, are visible in the
1414 current Dired buffer. By default, it also hides the targets of
1415 symbolic links, and all lines other than the header line and
1416 file/directory listings. To change this, customize the options
1417 @code{dired-hide-details-hide-symlink-targets} and
1418 @code{dired-hide-details-hide-information-lines}, respectively.
1420 @cindex Dired and version control
1421 If the directory you are visiting is under version control
1422 (@pxref{Version Control}), then the normal VC diff and log commands
1423 will operate on the selected files.
1425 @findex dired-compare-directories
1426 The command @kbd{M-x dired-compare-directories} is used to compare
1427 the current Dired buffer with another directory. It marks all the files
1428 that are ``different'' between the two directories. It puts these marks
1429 in all Dired buffers where these files are listed, which of course includes
1432 The default comparison method (used if you type @key{RET} at the
1433 prompt) is to compare just the file names---each file name that does
1434 not appear in the other directory is ``different''. You can specify
1435 more stringent comparisons by entering a Lisp expression, which can
1436 refer to the variables @code{size1} and @code{size2}, the respective
1437 file sizes; @code{mtime1} and @code{mtime2}, the last modification
1438 times in seconds, as floating point numbers; and @code{fa1} and
1439 @code{fa2}, the respective file attribute lists (as returned by the
1440 function @code{file-attributes}). This expression is evaluated for
1441 each pair of like-named files, and if the expression's value is
1442 non-@code{nil}, those files are considered ``different''.
1444 For instance, the sequence @code{M-x dired-compare-directories
1445 @key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this
1446 directory than in the other, and marks files older in the other
1447 directory than in this one. It also marks files with no counterpart,
1448 in both directories, as always.
1450 @cindex drag and drop, Dired
1451 On the X Window System, Emacs supports the ``drag and drop''
1452 protocol. You can drag a file object from another program, and drop
1453 it onto a Dired buffer; this either moves, copies, or creates a link
1454 to the file in that directory. Precisely which action is taken is
1455 determined by the originating program. Dragging files out of a Dired
1456 buffer is currently not supported.