*** empty log message ***
[emacs.git] / man / dired.texi
blob88e994ed0273b646be09ca985bf157d273f1fd5a
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001
3 @c   Free Software Foundation, Inc.
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 @cindex file management
10   Dired makes an Emacs buffer containing a listing of a directory, and
11 optionally some of its subdirectories as well.  You can use the normal
12 Emacs commands to move around in this buffer, and special Dired commands
13 to operate on the files listed.
15     The Dired buffer is ``read-only,'' and inserting text in it is not
16 useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are
17 used for special Dired commands.  Some Dired commands @dfn{mark} or
18 @dfn{flag} the @dfn{current file} (that is, the file on the current
19 line); other commands operate on the marked files or on the flagged
20 files.
22   The Dired-X package provides various extra features for Dired mode.
23 @xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
25 @menu
26 * Enter: Dired Enter.         How to invoke Dired.
27 * Navigation: Dired Navigation.   Special motion commands in the Dired buffer.
28 * Deletion: Dired Deletion.   Deleting files with Dired.
29 * Flagging Many Files::       Flagging files based on their names.
30 * Visit: Dired Visiting.      Other file operations through Dired.
31 * Marks vs Flags::            Flagging for deletion vs marking.
32 * Operating on Files::        How to copy, rename, print, compress, etc.
33                                 either one file or several files.
34 * Shell Commands in Dired::   Running a shell command on the marked files.
35 * Transforming File Names::   Using patterns to rename multiple files.
36 * Comparison in Dired::       Running `diff' by way of Dired.
37 * Subdirectories in Dired::   Adding subdirectories to the Dired buffer.
38 * Subdirectory Motion::       Moving across subdirectories, and up and down.
39 * Hiding Subdirectories::     Making subdirectories visible or invisible.
40 * Updating: Dired Updating.   Discarding lines for files of no interest.
41 * Find: Dired and Find.       Using `find' to choose the files for Dired.
42 * Misc: Misc Dired Commands.  Various other features.
43 @end menu
45 @node Dired Enter
46 @section Entering Dired
48 @findex dired
49 @kindex C-x d
50 @vindex dired-listing-switches
51   To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}.  The command reads
52 a directory name or wildcard file name pattern as a minibuffer argument
53 to specify which files to list.  Where @code{dired} differs from
54 @code{list-directory} is in putting the buffer into Dired mode so that
55 the special commands of Dired are available.
57   The variable @code{dired-listing-switches} specifies the options to
58 give to @code{ls} for listing directory; this string @emph{must} contain
59 @samp{-l}.  If you use a numeric prefix argument with the @code{dired}
60 command, you can specify the @code{ls} switches with the minibuffer
61 before you enter the directory specification.
63 @findex dired-other-window
64 @kindex C-x 4 d
65 @findex dired-other-frame
66 @kindex C-x 5 d
67   To display the Dired buffer in another window rather than in the
68 selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead
69 of @kbd{C-x d}.  @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
70 separate frame to display the Dired buffer.
72 @node Dired Navigation
73 @section Navigation in the Dired Buffer
75 @kindex C-n @r{(Dired)}
76 @kindex C-p @r{(Dired)}
77   All the usual Emacs cursor motion commands are available in Dired
78 buffers.  Some special-purpose cursor motion commands are also
79 provided.  The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
80 cursor at the beginning of the file name on the line, rather than at the
81 beginning of the line.
83 @kindex SPC @r{(Dired)}
84   For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
85 to @kbd{C-n}.  @kbd{p} is equivalent to @kbd{C-p}.  (Moving by lines is
86 so common in Dired that it deserves to be easy to type.)  @key{DEL}
87 (move up and unflag) is often useful simply for moving up.
89 @findex dired-goto-file
90 @kindex M-g
91   @kbd{M-g} (@code{dired-goto-file}) moves point to the line that
92 describes a specified file or directory.
94   Some additional navigation commands are available when the Dired
95 buffer includes several directories.  @xref{Subdirectory Motion}.
97 @node Dired Deletion
98 @section Deleting Files with Dired
99 @cindex flagging files (in Dired)
100 @cindex deleting files (in Dired)
102   One of the most frequent uses of Dired is to first @dfn{flag} files for
103 deletion, then delete the files that were flagged.
105 @table @kbd
106 @item d
107 Flag this file for deletion.
108 @item u
109 Remove deletion flag on this line.
110 @item @key{DEL}
111 Move point to previous line and remove the deletion flag on that line.
112 @item x
113 Delete the files that are flagged for deletion.
114 @end table
116 @kindex d @r{(Dired)}
117 @findex dired-flag-file-deletion
118   You can flag a file for deletion by moving to the line describing the
119 file and typing @kbd{d} (@code{dired-flag-file-deletion}).  The deletion flag is visible as a @samp{D} at
120 the beginning of the line.  This command moves point to the next line,
121 so that repeated @kbd{d} commands flag successive files.  A numeric
122 argument serves as a repeat count.
124 @cindex recursive deletion
125 @vindex dired-recursive-deletes
126   The variable @code{dired-recursive-deletes} controls whether the
127 delete command will delete non-empty directories (including their
128 contents).  The default is to delete only empty directories.
130 @kindex u @r{(Dired deletion)}
131 @kindex DEL @r{(Dired)}
132   The files are flagged for deletion rather than deleted immediately to
133 reduce the danger of deleting a file accidentally.  Until you direct
134 Dired to delete the flagged files, you can remove deletion flags using
135 the commands @kbd{u} and @key{DEL}.  @kbd{u} (@code{dired-unmark}) works
136 just like @kbd{d}, but removes flags rather than making flags.
137 @key{DEL} (@code{dired-unmark-backward}) moves upward, removing flags;
138 it is like @kbd{u} with argument @minus{}1.
140 @kindex x @r{(Dired)}
141 @findex dired-do-flagged-delete
142 @cindex expunging (Dired)
143   To delete the flagged files, type @kbd{x} (@code{dired-do-flagged-delete}).
144 (This is also known as @dfn{expunging}.)
145 This command first displays a list of all the file names flagged for
146 deletion, and requests confirmation with @kbd{yes}.  If you confirm,
147 Dired deletes the flagged files, then deletes their lines from the text
148 of the Dired buffer.  The shortened Dired buffer remains selected.
150   If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
151 return immediately to Dired, with the deletion flags still present in
152 the buffer, and no files actually deleted.
154 @node Flagging Many Files
155 @section Flagging Many Files at Once
156 @cindex flagging many files for deletion (in Dired)
158 @table @kbd
159 @item #
160 Flag all auto-save files (files whose names start and end with @samp{#})
161 for deletion (@pxref{Auto Save}).
163 @item ~
164 Flag all backup files (files whose names end with @samp{~}) for deletion
165 (@pxref{Backup}).
167 @item &
168 Flag for deletion all files with certain kinds of names, names that
169 suggest you could easily create the files again.
171 @item .@: @r{(Period)}
172 Flag excess numeric backup files for deletion.  The oldest and newest
173 few backup files of any one file are exempt; the middle ones are
174 flagged.
176 @item % d @var{regexp} @key{RET}
177 Flag for deletion all files whose names match the regular expression
178 @var{regexp}.
179 @end table
181   The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for
182 deletion, based on their file names.  These commands are useful
183 precisely because they do not themselves delete any files; you can
184 remove the deletion flags from any flagged files that you really wish to
185 keep.@refill
187 @kindex & @r{(Dired)}
188 @findex dired-flag-garbage-files
189 @vindex dired-garbage-files-regexp
190 @cindex deleting some backup files
191   @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
192 match the regular expression specified by the variable
193 @code{dired-garbage-files-regexp}.  By default, this matches certain
194 files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and
195 @samp{.rej} files produced by @code{patch}.
197 @kindex # @r{(Dired)}
198 @findex dired-flag-auto-save-files
199 @cindex deleting auto-save files
200   @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all
201 files whose names look like auto-save files (@pxref{Auto Save})---that
202 is, files whose names begin and end with @samp{#}.
204 @kindex ~ @r{(Dired)}
205 @findex dired-flag-backup-files
206   @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all files
207 whose names say they are backup files (@pxref{Backup})---that is, files
208 whose names end in @samp{~}.
210 @kindex . @r{(Dired)}
211 @vindex dired-kept-versions
212 @findex dired-clean-directory
213   @kbd{.} (period, @code{dired-clean-directory}) flags just some of the
214 backup files for deletion: all but the oldest few and newest few backups
215 of any one file.  Normally @code{dired-kept-versions} (@strong{not}
216 @code{kept-new-versions}; that applies only when saving) specifies the
217 number of newest versions of each file to keep, and
218 @code{kept-old-versions} specifies the number of oldest versions to
219 keep.
221   Period with a positive numeric argument, as in @kbd{C-u 3 .},
222 specifies the number of newest versions to keep, overriding
223 @code{dired-kept-versions}.  A negative numeric argument overrides
224 @code{kept-old-versions}, using minus the value of the argument to
225 specify the number of oldest versions of each file to keep.
227 @findex dired-flag-files-regexp
228 @kindex % d @r{(Dired)}
229   The @kbd{% d} command flags all files whose names match a specified
230 regular expression (@code{dired-flag-files-regexp}).  Only the
231 non-directory part of the file name is used in matching.  You can use
232 @samp{^} and @samp{$} to anchor matches.  You can exclude subdirectories
233 by hiding them (@pxref{Hiding Subdirectories}).
235 @node Dired Visiting
236 @section Visiting Files in Dired
238   There are several Dired commands for visiting or examining the files
239 listed in the Dired buffer.  All of them apply to the current line's
240 file; if that file is really a directory, these commands invoke Dired on
241 that subdirectory (making a separate Dired buffer).
243 @table @kbd
244 @item f
245 @kindex f @r{(Dired)}
246 @findex dired-find-file
247 Visit the file described on the current line, like typing @kbd{C-x C-f}
248 and supplying that file name (@code{dired-find-file}).  @xref{Visiting}.
250 @item @key{RET}
251 @itemx e
252 @kindex RET @r{(Dired)}
253 @kindex e @r{(Dired)}
254 Equivalent to @kbd{f}.
256 @item a
257 @kindex a @r{(Dired)}
258 @findex dired-find-alternate-file
259 Like @kbd{f}, but replaces the contents of the Dired buffer with
260 that of an alternate file or directory (@code{dired-find-alternate-file}).
262 @item o
263 @kindex o @r{(Dired)}
264 @findex dired-find-file-other-window
265 Like @kbd{f}, but uses another window to display the file's buffer
266 (@code{dired-find-file-other-window}).  The Dired buffer remains visible
267 in the first window.  This is like using @kbd{C-x 4 C-f} to visit the
268 file.  @xref{Windows}.
270 @item C-o
271 @kindex C-o @r{(Dired)}
272 @findex dired-display-file
273 Visit the file described on the current line, and display the buffer in
274 another window, but do not select that window (@code{dired-display-file}).
276 @item Mouse-2
277 @findex dired-mouse-find-file-other-window
278 Visit the file named by the line you click on
279 (@code{dired-mouse-find-file-other-window}).  This uses another window
280 to display the file, like the @kbd{o} command.
282 @item v
283 @kindex v @r{(Dired)}
284 @findex dired-view-file
285 View the file described on the current line, using either an external
286 viewing program or @kbd{M-x view-file} (@code{dired-view-file}).
288 @vindex dired-view-command-alist
289 External viewers are used for certain file types under the control of
290 @code{dired-view-command-alist}.  Viewing a file with @code{view-file}
291 is like visiting it, but is slanted toward moving around in the file
292 conveniently and does not allow changing the file.  @xref{Misc File
293 Ops,View File, Miscellaneous File Operations}.
295 @item ^
296 @kindex ^ @r{(Dired)}
297 @findex dired-up-directory
298 Visit the parent directory of the current directory
299 (@code{dired-up-directory}).  This is more convenient than moving to
300 the parent directory's line and typing @kbd{f} there.
301 @end table
303 @node Marks vs Flags
304 @section Dired Marks vs. Flags
306 @cindex marking many files (in Dired)
307   Instead of flagging a file with @samp{D}, you can @dfn{mark} the
308 file with some other character (usually @samp{*}).  Most Dired
309 commands to operate on files use the files marked with @samp{*}, the
310 exception being @kbd{x} which deletes the flagged files.
312   Here are some commands for marking with @samp{*}, or for unmarking or
313 operating on marks.  (@xref{Dired Deletion}, for commands to flag and
314 unflag files.)
316 @table @kbd
317 @item m
318 @itemx * m
319 @kindex m @r{(Dired)}
320 @kindex * m @r{(Dired)}
321 @findex dired-mark
322 Mark the current file with @samp{*} (@code{dired-mark}).  With a numeric
323 argument @var{n}, mark the next @var{n} files starting with the current
324 file.  (If @var{n} is negative, mark the previous @minus{}@var{n}
325 files.)
327 @item * *
328 @kindex * * @r{(Dired)}
329 @findex dired-mark-executables
330 @cindex marking executable files (in Dired)
331 Mark all executable files with @samp{*}
332 (@code{dired-mark-executables}).  With a numeric argument, unmark all
333 those files.
335 @item * @@
336 @kindex * @@ @r{(Dired)}
337 @findex dired-mark-symlinks
338 @cindex marking symbolic links (in Dired)
339 Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
340 With a numeric argument, unmark all those files.
342 @item * /
343 @kindex * / @r{(Dired)}
344 @findex dired-mark-directories
345 @cindex marking subdirectories (in Dired)
346 Mark with @samp{*} all files which are actually directories, except for
347 @file{.} and @file{..} (@code{dired-mark-directories}).  With a numeric
348 argument, unmark all those files.
350 @item * s
351 @kindex * s @r{(Dired)}
352 @findex dired-mark-subdir-files
353 Mark all the files in the current subdirectory, aside from @file{.}
354 and @file{..} (@code{dired-mark-subdir-files}).
356 @item u
357 @itemx * u
358 @kindex u @r{(Dired)}
359 @kindex * u @r{(Dired)}
360 @findex dired-unmark
361 Remove any mark on this line (@code{dired-unmark}).
363 @item @key{DEL}
364 @itemx * @key{DEL}
365 @kindex * DEL @r{(Dired)}
366 @findex dired-unmark-backward
367 @cindex unmarking files (in Dired)
368 Move point to previous line and remove any mark on that line
369 (@code{dired-unmark-backward}).
371 @item * !
372 @kindex * ! @r{(Dired)}
373 @findex dired-unmark-all-marks
374 Remove all marks from all the files in this Dired buffer
375 (@code{dired-unmark-all-marks}).
377 @item * ? @var{markchar}
378 @kindex * ? @r{(Dired)}
379 @findex dired-unmark-all-files
380 Remove all marks that use the character @var{markchar}
381 (@code{dired-unmark-all-files}).  The argument is a single
382 character---do not use @key{RET} to terminate it.  See the description
383 of the @kbd{* c} command below, which lets you replace one mark
384 character with another.
386 With a numeric argument, this command queries about each marked file,
387 asking whether to remove its mark.  You can answer @kbd{y} meaning yes,
388 @kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining
389 files without asking about them.
391 @item * C-n
392 @findex dired-next-marked-file
393 @kindex * C-n @r{(Dired)}
394 Move down to the next marked file (@code{dired-next-marked-file})
395 A file is ``marked'' if it has any kind of mark.
397 @item * C-p
398 @findex dired-prev-marked-file
399 @kindex * C-p @r{(Dired)}
400 Move up to the previous marked file (@code{dired-prev-marked-file})
402 @item * t
403 @kindex * t @r{(Dired)}
404 @findex dired-toggle-marks
405 @cindex toggling marks (in Dired)
406 Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*}
407 become unmarked, and unmarked files are marked with @samp{*}.  Files
408 marked in any other way are not affected.
410 @item * c @var{old-markchar} @var{new-markchar}
411 @kindex * c @r{(Dired)}
412 @findex dired-change-marks
413 Replace all marks that use the character @var{old-markchar} with marks
414 that use the character @var{new-markchar} (@code{dired-change-marks}).
415 This command is the primary way to create or use marks other than
416 @samp{*} or @samp{D}.  The arguments are single characters---do not use
417 @key{RET} to terminate them.
419 You can use almost any character as a mark character by means of this
420 command, to distinguish various classes of files.  If @var{old-markchar}
421 is a space (@samp{ }), then the command operates on all unmarked files;
422 if @var{new-markchar} is a space, then the command unmarks the files it
423 acts on.
425 To illustrate the power of this command, here is how to put @samp{D}
426 flags on all the files that have no marks, while unflagging all those
427 that already have @samp{D} flags:
429 @example
430 * c D t  * c SPC D  * c t SPC
431 @end example
433 This assumes that no files were already marked with @samp{t}.
435 @item % m @var{regexp} @key{RET}
436 @itemx * % @var{regexp} @key{RET}
437 @findex dired-mark-files-regexp
438 @kindex % m @r{(Dired)}
439 @kindex * % @r{(Dired)}
440 Mark (with @samp{*}) all files whose names match the regular expression
441 @var{regexp} (@code{dired-mark-files-regexp}).  This command is like
442 @kbd{% d}, except that it marks files with @samp{*} instead of flagging
443 with @samp{D}.  @xref{Flagging Many Files}.
445 Only the non-directory part of the file name is used in matching.  Use
446 @samp{^} and @samp{$} to anchor matches.  Exclude subdirectories by
447 hiding them (@pxref{Hiding Subdirectories}).
449 @item % g @var{regexp} @key{RET}
450 @findex dired-mark-files-containing-regexp
451 @kindex % g @r{(Dired)}
452 @cindex finding files containing regexp matches (in Dired)
453 Mark (with @samp{*}) all files whose @emph{contents} contain a match for
454 the regular expression @var{regexp}
455 (@code{dired-mark-files-containing-regexp}).  This command is like
456 @kbd{% m}, except that it searches the file contents instead of the file
457 name.
459 @item C-_
460 @kindex C-_ @r{(Dired)}
461 @findex dired-undo
462 Undo changes in the Dired buffer, such as adding or removing
463 marks (@code{dired-undo}).  @emph{This command does not revert the
464 actual file operations, nor recover lost files!}  It just undoes
465 changes in the buffer itself.  For example, if used after renaming one
466 or more files, @code{dired-undo} restores the original names, which
467 will get the Dired buffer out of sync with the actual contents of the
468 directory.
469 @end table
471 @node Operating on Files
472 @section Operating on Files
473 @cindex operating on files in Dired
475   This section describes the basic Dired commands to operate on one file
476 or several files.  All of these commands are capital letters; all of
477 them use the minibuffer, either to read an argument or to ask for
478 confirmation, before they act.  All of them give you several ways to
479 specify which files to manipulate:
481 @itemize @bullet
482 @item
483 If you give the command a numeric prefix argument @var{n}, it operates
484 on the next @var{n} files, starting with the current file.  (If @var{n}
485 is negative, the command operates on the @minus{}@var{n} files preceding
486 the current line.)
488 @item
489 Otherwise, if some files are marked with @samp{*}, the command operates
490 on all those files.
492 @item
493 Otherwise, the command operates on the current file only.
494 @end itemize
496 @vindex dired-dwim-target
497 @cindex two directories (in Dired)
498   Commands which ask for a destination directory, such as those which
499 copy and rename files or create links for them, try to guess the default
500 target directory for the operation.  Normally, they suggest the Dired
501 buffer's default directory, but if the variable @code{dired-dwim-target}
502 is non-@code{nil}, and if there is another Dired buffer displayed in the
503 next window, that other buffer's directory is suggested instead.
505   Here are the file-manipulating commands that operate on files in this
506 way.  (Some other Dired commands, such as @kbd{!} and the @samp{%}
507 commands, also use these conventions to decide which files to work on.)
509 @table @kbd
510 @findex dired-do-copy
511 @kindex C @r{(Dired)}
512 @cindex copying files (in Dired)
513 @item C @var{new} @key{RET}
514 Copy the specified files (@code{dired-do-copy}).  The argument @var{new}
515 is the directory to copy into, or (if copying a single file) the new
516 name.
518 @vindex dired-copy-preserve-time
519 If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with
520 this command sets the modification time of the new file to be the same
521 as that of the old file.
523 @vindex dired-recursive-copies
524 @cindex recursive copying
525 The variable @code{dired-recursive-copies} controls whether
526 directories are copied recursively.  The default is to not copy
527 recursively, which means that directories cannot be copied.
529 @item D
530 @findex dired-do-delete
531 @kindex D @r{(Dired)}
532 Delete the specified files (@code{dired-do-delete}).  Like the other
533 commands in this section, this command operates on the @emph{marked}
534 files, or the next @var{n} files.  By contrast, @kbd{x}
535 (@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files.
537 @findex dired-do-rename
538 @kindex R @r{(Dired)}
539 @cindex renaming files (in Dired)
540 @item R @var{new} @key{RET}
541 Rename the specified files (@code{dired-do-rename}).  The argument
542 @var{new} is the directory to rename into, or (if renaming a single
543 file) the new name.
545 Dired automatically changes the visited file name of buffers associated
546 with renamed files so that they refer to the new names.
548 @findex dired-do-hardlink
549 @kindex H @r{(Dired)}
550 @cindex hard links (in Dired)
551 @item H @var{new} @key{RET}
552 Make hard links to the specified files (@code{dired-do-hardlink}).  The
553 argument @var{new} is the directory to make the links in, or (if making
554 just one link) the name to give the link.
556 @findex dired-do-symlink
557 @kindex S @r{(Dired)}
558 @cindex symbolic links (creation in Dired)
559 @item S @var{new} @key{RET}
560 Make symbolic links to the specified files (@code{dired-do-symlink}).
561 The argument @var{new} is the directory to make the links in, or (if
562 making just one link) the name to give the link.
564 @findex dired-do-chmod
565 @kindex M @r{(Dired)}
566 @cindex changing file permissions (in Dired)
567 @item M @var{modespec} @key{RET}
568 Change the mode (also called ``permission bits'') of the specified files
569 (@code{dired-do-chmod}).  This uses the @code{chmod} program, so
570 @var{modespec} can be any argument that @code{chmod} can handle.
572 @findex dired-do-chgrp
573 @kindex G @r{(Dired)}
574 @cindex changing file group (in Dired)
575 @item G @var{newgroup} @key{RET}
576 Change the group of the specified files to @var{newgroup}
577 (@code{dired-do-chgrp}).
579 @findex dired-do-chown
580 @kindex O @r{(Dired)}
581 @cindex changing file owner (in Dired)
582 @item O @var{newowner} @key{RET}
583 Change the owner of the specified files to @var{newowner}
584 (@code{dired-do-chown}).  (On most systems, only the superuser can do
585 this.)
587 @vindex dired-chown-program
588 The variable @code{dired-chown-program} specifies the name of the
589 program to use to do the work (different systems put @code{chown} in
590 different places).
592 @findex dired-do-print
593 @kindex P @r{(Dired)}
594 @cindex printing files (in Dired)
595 @item P @var{command} @key{RET}
596 Print the specified files (@code{dired-do-print}).  You must specify the
597 command to print them with, but the minibuffer starts out with a
598 suitable guess made using the variables @code{lpr-command} and
599 @code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
600 @pxref{Hardcopy}).
602 @findex dired-do-compress
603 @kindex Z @r{(Dired)}
604 @cindex compressing files (in Dired)
605 @item Z
606 Compress the specified files (@code{dired-do-compress}).  If the file
607 appears to be a compressed file already, it is uncompressed instead.
609 @findex dired-do-load
610 @kindex L @r{(Dired)}
611 @cindex loading several files (in Dired)
612 @item L
613 Load the specified Emacs Lisp files (@code{dired-do-load}).
614 @xref{Lisp Libraries}.
616 @findex dired-do-byte-compile
617 @kindex B @r{(Dired)}
618 @cindex byte-compiling several files (in Dired)
619 @item B
620 Byte compile the specified Emacs Lisp files
621 (@code{dired-do-byte-compile}).  @xref{Byte Compilation,, Byte
622 Compilation, elisp, The Emacs Lisp Reference Manual}.
624 @kindex A @r{(Dired)}
625 @findex dired-do-search
626 @cindex search multiple files (in Dired)
627 @item A @var{regexp} @key{RET}
628 Search all the specified files for the regular expression @var{regexp}
629 (@code{dired-do-search}).
631 This command is a variant of @code{tags-search}.  The search stops at
632 the first match it finds; use @kbd{M-,} to resume the search and find
633 the next match.  @xref{Tags Search}.
635 @kindex Q @r{(Dired)}
636 @findex dired-do-query-replace-regexp
637 @cindex search and replace in multiple files (in Dired)
638 @item Q @var{regexp} @key{RET} @var{to} @key{RET}
639 Perform @code{query-replace-regexp} on each of the specified files,
640 replacing matches for @var{regexp} with the string
641 @var{to} (@code{dired-do-query-replace-regexp}).
643 This command is a variant of @code{tags-query-replace}.  If you exit the
644 query replace loop, you can use @kbd{M-,} to resume the scan and replace
645 more matches.  @xref{Tags Search}.
646 @end table
648 @kindex + @r{(Dired)}
649 @findex dired-create-directory
650   One special file-operation command is @kbd{+}
651 (@code{dired-create-directory}).  This command reads a directory name and
652 creates the directory if it does not already exist.
654 @node Shell Commands in Dired
655 @section Shell Commands in Dired
656 @cindex shell commands, Dired
658 @findex dired-do-shell-command
659 @kindex ! @r{(Dired)}
660 @kindex X @r{(Dired)}
661 The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell
662 command string in the minibuffer and runs that shell command on all the
663 specified files.  @kbd{X} is a synonym for @kbd{!}.  You can specify the
664 files to operate on in the usual ways for Dired commands
665 (@pxref{Operating on Files}).  There are two ways of applying a shell
666 command to multiple files:
668 @itemize @bullet
669 @item
670 If you use @samp{*} surrounded by whitespace in the shell command,
671 then the command runs just once, with the list of file names
672 substituted for the @samp{*}.  The order of file names is the order of
673 appearance in the Dired buffer.
675 Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
676 list of file names, putting them into one tar file @file{foo.tar}.
678 If you want to use @samp{*} as a shell wildcard with whitespace around
679 it, write @samp{*""}.  In the shell, this is equivalent to @samp{*};
680 but since the @samp{*} is not surrounded by whitespace, Dired does
681 not treat it specially.
683 @item
684 If the command string doesn't contain @samp{*} surrounded by
685 whitespace, then it runs once @emph{for each file}.  Normally the file
686 name is added at the end.
688 For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
689 file.
691 @item
692 If the command string contains @samp{?} surrounded by whitespace, the
693 current file name is substituted for @samp{?}.  You can use @samp{?}
694 this way more than once in the command, and each occurrence is
695 replaced.  For instance, here is how to uuencode each file, making the
696 output file name by appending @samp{.uu} to the input file name:
698 @example
699 uuencode ? ? > ?.uu
700 @end example
701 @end itemize
703 To iterate over the file names in a more complicated fashion, use an
704 explicit shell loop.  For example, this shell command is another way
705 to uuencode each file:
707 @example
708 for file in * ; do uuencode "$file" "$file" >"$file".uu; done
709 @end example
711 @noindent
712 This simple example doesn't require a shell loop (you can do it
713 with @samp{?}, but it illustrates the technique.
715 The working directory for the shell command is the top-level directory
716 of the Dired buffer.
718 The @kbd{!} command does not attempt to update the Dired buffer to show
719 new or modified files, because it doesn't really understand shell
720 commands, and does not know what files the shell command changed.  Use
721 the @kbd{g} command to update the Dired buffer (@pxref{Dired
722 Updating}).
724 @node Transforming File Names
725 @section Transforming File Names in Dired
727   This section describes Dired commands which alter file names in a
728 systematic way.
730   Like the basic Dired file-manipulation commands (@pxref{Operating on
731 Files}), the commands described here operate either on the next
732 @var{n} files, or on all files marked with @samp{*}, or on the current
733 file.  (To mark files, use the commands described in @ref{Marks vs
734 Flags}.)
736   All of the commands described in this section work
737 @emph{interactively}: they ask you to confirm the operation for each
738 candidate file.  Thus, you can select more files than you actually
739 need to operate on (e.g., with a regexp that matches many files), and
740 then refine the selection by typing @kbd{y} or @kbd{n} when the
741 command prompts for confirmation.
743 @table @kbd
744 @findex dired-upcase
745 @kindex % u @r{(Dired)}
746 @cindex upcase file names
747 @item % u
748 Rename each of the selected files to an upper-case name
749 (@code{dired-upcase}).  If the old file names are @file{Foo}
750 and @file{bar}, the new names are @file{FOO} and @file{BAR}.
752 @item % l
753 @findex dired-downcase
754 @kindex % l @r{(Dired)}
755 @cindex downcase file names
756 Rename each of the selected files to a lower-case name
757 (@code{dired-downcase}).  If the old file names are @file{Foo} and
758 @file{bar}, the new names are @file{foo} and @file{bar}.
760 @item % R @var{from} @key{RET} @var{to} @key{RET}
761 @kindex % R @r{(Dired)}
762 @findex dired-do-rename-regexp
763 @itemx % C @var{from} @key{RET} @var{to} @key{RET}
764 @kindex % C @r{(Dired)}
765 @findex dired-do-copy-regexp
766 @itemx % H @var{from} @key{RET} @var{to} @key{RET}
767 @kindex % H @r{(Dired)}
768 @findex dired-do-hardlink-regexp
769 @itemx % S @var{from} @key{RET} @var{to} @key{RET}
770 @kindex % S @r{(Dired)}
771 @findex dired-do-symlink-regexp
772 These four commands rename, copy, make hard links and make soft links,
773 in each case computing the new name by regular-expression substitution
774 from the name of the old file.
775 @end table
777   The four regular-expression substitution commands effectively perform
778 a search-and-replace on the selected file names in the Dired buffer.
779 They read two arguments: a regular expression @var{from}, and a
780 substitution pattern @var{to}.
782   The commands match each ``old'' file name against the regular
783 expression @var{from}, and then replace the matching part with @var{to}.
784 You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to
785 all or part of what the pattern matched in the old file name, as in
786 @code{replace-regexp} (@pxref{Regexp Replace}).  If the regular expression
787 matches more than once in a file name, only the first match is replaced.
789   For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
790 selected file by prepending @samp{x-} to its name.  The inverse of this,
791 removing @samp{x-} from the front of each file name, is also possible:
792 one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is
793 @kbd{% R ^x- @key{RET} @key{RET}}.  (Use @samp{^} and @samp{$} to anchor
794 matches that should span the whole filename.)
796   Normally, the replacement process does not consider the files'
797 directory names; it operates on the file name within the directory.  If
798 you specify a numeric argument of zero, then replacement affects the
799 entire absolute file name including directory name.  (Non-zero
800 argument specifies the number of files to operate on.)
802   Often you will want to select the set of files to operate on using the
803 same @var{regexp} that you will use to operate on them.  To do this,
804 mark those files with @kbd{% m @var{regexp} @key{RET}}, then use the
805 same regular expression in the command to operate on the files.  To make
806 this easier, the @kbd{%} commands to operate on files use the last
807 regular expression specified in any @kbd{%} command as a default.
809 @node Comparison in Dired
810 @section File Comparison with Dired
811 @cindex file comparison (in Dired)
812 @cindex compare files (in Dired)
814   Here are two Dired commands that compare specified files using
815 @code{diff}.
817 @table @kbd
818 @item =
819 @findex dired-diff
820 @kindex = @r{(Dired)}
821 Compare the current file (the file at point) with another file (the file
822 at the mark) using the @code{diff} program (@code{dired-diff}).  The
823 file at the mark is the first argument of @code{diff}, and the file at
824 point is the second argument.  Use @kbd{C-@key{SPC}}
825 (@code{set-mark-command}) to set the mark at the first file's line
826 (@pxref{Setting Mark}), since @code{dired-diff} ignores the files marked
827 with the Dired's @kbd{m} command.
829 @findex dired-backup-diff
830 @kindex M-= @r{(Dired)}
831 @item M-=
832 Compare the current file with its latest backup file
833 (@code{dired-backup-diff}).  If the current file is itself a backup,
834 compare it with the file it is a backup of; this way, you can compare
835 a file with any backup version of your choice.
837 The backup file is the first file given to @code{diff}.
838 @end table
840 @node Subdirectories in Dired
841 @section Subdirectories in Dired
842 @cindex subdirectories in Dired
843 @cindex expanding subdirectories in Dired
845   A Dired buffer displays just one directory in the normal case;
846 but you can optionally include its subdirectories as well.
848   The simplest way to include multiple directories in one Dired buffer is
849 to specify the options @samp{-lR} for running @code{ls}.  (If you give a
850 numeric argument when you run Dired, then you can specify these options
851 in the minibuffer.)  That produces a recursive directory listing showing
852 all subdirectories at all levels.
854   But usually all the subdirectories are too many; usually you will
855 prefer to include specific subdirectories only.  You can do this with
856 the @kbd{i} command:
858 @table @kbd
859 @findex dired-maybe-insert-subdir
860 @kindex i @r{(Dired)}
861 @item i
862 @cindex inserted subdirectory (Dired)
863 @cindex in-situ subdirectory (Dired)
864 Insert the contents of a subdirectory later in the buffer.
865 @end table
867 Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
868 that describes a file which is a directory.  It inserts the contents of
869 that directory into the same Dired buffer, and moves there.  Inserted
870 subdirectory contents follow the top-level directory of the Dired
871 buffer, just as they do in @samp{ls -lR} output.
873 If the subdirectory's contents are already present in the buffer, the
874 @kbd{i} command just moves to it.
876 In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u
877 C-@key{SPC}} takes you back to the old position in the buffer (the line
878 describing that subdirectory).
880 Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
881 subdirectory's contents.  Use @kbd{C-u k} on the subdirectory header
882 line to delete the subdirectory.  @xref{Dired Updating}.
884 @node Subdirectory Motion
885 @section Moving Over Subdirectories
887   When a Dired buffer lists subdirectories, you can use the page motion
888 commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories
889 (@pxref{Pages}).
891 @cindex header line (Dired)
892 @cindex directory header lines
893   The following commands move across, up and down in the tree of
894 directories within one Dired buffer.  They move to @dfn{directory header
895 lines}, which are the lines that give a directory's name, at the
896 beginning of the directory's contents.
898 @table @kbd
899 @findex dired-next-subdir
900 @kindex C-M-n @r{(Dired)}
901 @item C-M-n
902 Go to next subdirectory header line, regardless of level
903 (@code{dired-next-subdir}).
905 @findex dired-prev-subdir
906 @kindex C-M-p @r{(Dired)}
907 @item C-M-p
908 Go to previous subdirectory header line, regardless of level
909 (@code{dired-prev-subdir}).
911 @findex dired-tree-up
912 @kindex C-M-u @r{(Dired)}
913 @item C-M-u
914 Go up to the parent directory's header line (@code{dired-tree-up}).
916 @findex dired-tree-down
917 @kindex C-M-d @r{(Dired)}
918 @item C-M-d
919 Go down in the directory tree, to the first subdirectory's header line
920 (@code{dired-tree-down}).
922 @findex dired-prev-dirline
923 @kindex < @r{(Dired)}
924 @item <
925 Move up to the previous directory-file line (@code{dired-prev-dirline}).
926 These lines are the ones that describe a directory as a file in its
927 parent directory.
929 @findex dired-next-dirline
930 @kindex > @r{(Dired)}
931 @item >
932 Move down to the next directory-file line (@code{dired-prev-dirline}).
933 @end table
935 @node Hiding Subdirectories
936 @section Hiding Subdirectories
938 @cindex hiding in Dired (Dired)
939   @dfn{Hiding} a subdirectory means to make it invisible, except for its
940 header line, via selective display (@pxref{Selective Display}).
942 @table @kbd
943 @item $
944 @findex dired-hide-subdir
945 @kindex $ @r{(Dired)}
946 Hide or reveal the subdirectory that point is in, and move point to the
947 next subdirectory (@code{dired-hide-subdir}).  A numeric argument serves
948 as a repeat count.
950 @item M-$
951 @findex dired-hide-all
952 @kindex M-$ @r{(Dired)}
953 Hide all subdirectories in this Dired buffer, leaving only their header
954 lines (@code{dired-hide-all}).  Or, if any subdirectory is currently
955 hidden, make all subdirectories visible again.  You can use this command
956 to get an overview in very deep directory trees or to move quickly to
957 subdirectories far away.
958 @end table
960   Ordinary Dired commands never consider files inside a hidden
961 subdirectory.  For example, the commands to operate on marked files
962 ignore files in hidden directories even if they are marked.  Thus you
963 can use hiding to temporarily exclude subdirectories from operations
964 without having to remove the markers.
966   The subdirectory hiding commands toggle; that is, they hide what was
967 visible, and show what was hidden.
969 @node Dired Updating
970 @section Updating the Dired Buffer
971 @cindex updating Dired buffer
972 @cindex refreshing displayed files
974   This section describes commands to update the Dired buffer to reflect
975 outside (non-Dired) changes in the directories and files, and to delete
976 part of the Dired buffer.
978 @table @kbd
979 @item g
980 Update the entire contents of the Dired buffer (@code{revert-buffer}).
982 @item l
983 Update the specified files (@code{dired-do-redisplay}).
985 @item k
986 Delete the specified @emph{file lines}---not the files, just the lines
987 (@code{dired-do-kill-lines}).
989 @item s
990 Toggle between alphabetical order and date/time order
991 (@code{dired-sort-toggle-or-edit}).
993 @item C-u s @var{switches} @key{RET}
994 Refresh the Dired buffer using @var{switches} as
995 @code{dired-listing-switches}.
996 @end table
998 @kindex g @r{(Dired)}
999 @findex revert-buffer @r{(Dired)}
1000   Type @kbd{g} (@code{revert-buffer}) to update the contents of the
1001 Dired buffer, based on changes in the files and directories listed.
1002 This preserves all marks except for those on files that have vanished.
1003 Hidden subdirectories are updated but remain hidden.
1005 @kindex l @r{(Dired)}
1006 @findex dired-do-redisplay
1007   To update only some of the files, type @kbd{l}
1008 (@code{dired-do-redisplay}).  Like the Dired file-operating commands,
1009 this command operates on the next @var{n} files (or previous
1010 @minus{}@var{n} files), or on the marked files if any, or on the
1011 current file.  Updating the files means reading their current status,
1012 then updating their lines in the buffer to indicate that status.
1014   If you use @kbd{l} on a subdirectory header line, it updates the
1015 contents of the corresponding subdirectory.
1017 @kindex k @r{(Dired)}
1018 @findex dired-do-kill-lines
1019   To delete the specified @emph{file lines} from the buffer---not
1020 delete the files---type @kbd{k} (@code{dired-do-kill-lines}).  Like
1021 the file-operating commands, this command operates on the next @var{n}
1022 files, or on the marked files if any; but it does not operate on the
1023 current file as a last resort.
1025   If you kill the line for a file that is a directory, the directory's
1026 contents are also deleted from the buffer.  Typing @kbd{C-u k} on the
1027 header line for a subdirectory is another way to delete a subdirectory
1028 from the Dired buffer.
1030   The @kbd{g} command brings back any individual lines that you have
1031 killed in this way, but not subdirectories---you must use @kbd{i} to
1032 reinsert a subdirectory.
1034 @cindex Dired sorting
1035 @cindex sorting Dired buffer
1036 @kindex s @r{(Dired)}
1037 @findex dired-sort-toggle-or-edit
1038   The files in a Dired buffers are normally listed in alphabetical order
1039 by file names.  Alternatively Dired can sort them by date/time.  The
1040 Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches
1041 between these two sorting modes.  The mode line in a Dired buffer
1042 indicates which way it is currently sorted---by name, or by date.
1044   @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for
1045 @code{dired-listing-switches}.
1047 @node Dired and Find
1048 @section Dired and @code{find}
1049 @cindex @code{find} and Dired
1051   You can select a set of files for display in a Dired buffer more
1052 flexibly by using the @code{find} utility to choose the files.
1054 @findex find-name-dired
1055   To search for files with names matching a wildcard pattern use
1056 @kbd{M-x find-name-dired}.  It reads arguments @var{directory} and
1057 @var{pattern}, and chooses all the files in @var{directory} or its
1058 subdirectories whose individual names match @var{pattern}.
1060   The files thus chosen are displayed in a Dired buffer in which the
1061 ordinary Dired commands are available.
1063 @findex find-grep-dired
1064   If you want to test the contents of files, rather than their names,
1065 use @kbd{M-x find-grep-dired}.  This command reads two minibuffer
1066 arguments, @var{directory} and @var{regexp}; it chooses all the files in
1067 @var{directory} or its subdirectories that contain a match for
1068 @var{regexp}.  It works by running the programs @code{find} and
1069 @code{grep}.  See also @kbd{M-x grep-find}, in @ref{Compilation}.
1070 Remember to write the regular expression for @code{grep}, not for Emacs.
1071 (An alternative method of showing files whose contents match a given
1072 regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.)
1074 @findex find-dired
1075   The most general command in this series is @kbd{M-x find-dired}, which
1076 lets you specify any condition that @code{find} can test.  It takes two
1077 minibuffer arguments, @var{directory} and @var{find-args}; it runs
1078 @code{find} in @var{directory}, passing @var{find-args} to tell
1079 @code{find} what condition to test.  To use this command, you need to
1080 know how to use @code{find}.
1082 @findex locate
1083 @findex locate-with-filter
1084 @cindex file database (locate)
1085 @vindex locate-command
1086   @kbd{M-x locate} provides a similar interface to the @code{locate}
1087 program.  @kbd{M-x locate-with-filter} is similar, but keeps only lines
1088 matching a given regular expression.
1090 @vindex find-ls-option
1091   The format of listing produced by these commands is controlled by the
1092 variable @code{find-ls-option}, whose default value specifies using
1093 options @samp{-ld} for @code{ls}.  If your listings are corrupted, you
1094 may need to change the value of this variable.
1096 @node Misc Dired Commands
1097 @section Other Dired Commands
1099 @table @kbd
1100 @item w
1101 @cindex Adding to the kill ring in Dired.
1102 @kindex w
1103 @findex dired-copy-filename-as-kill
1104 The @kbd{w} command (@code{dired-copy-filename-as-kill}) puts the
1105 names of the marked (or next @var{n}) files into the kill ring, as if
1106 you had killed them with @kbd{C-w}.  With a zero prefix argument
1107 @var{n}=0, use the absolute file name of each marked file.  With just
1108 @kbd{C-u} as the prefix argument, use the relative file name of each
1109 marked file.  As a special case, if no prefix argument is given and
1110 point is on a directory headerline, @kbd{w} gives you the name of that
1111 directory without looking for marked files.
1113 @vindex dired-marked-files
1114 The main purpose of the @kbd{w} command is so that you can yank the
1115 file names into arguments for other Emacs commands.  It also displays
1116 what was pushed onto the kill ring, so you can use it to display the
1117 list of currently marked files in the echo area.  It also stores the
1118 list of names in the variable @code{dired-marked-files}, for use in
1119 Lisp expressions.
1120 @end table
1122 @ignore
1123    arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1
1124 @end ignore