Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
b65d8176 | 2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
8d99e09d | 3 | @c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Dired, Calendar/Diary, Rmail, Top | |
6 | @chapter Dired, the Directory Editor | |
7 | @cindex Dired | |
a33b10b5 | 8 | @cindex file management |
6bf7aab6 DL |
9 | |
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. | |
14 | ||
c3149267 | 15 | The Dired buffer is ``read-only,'' and inserting text in it is not |
e01a5bb5 RS |
16 | useful, so ordinary printing characters such as @kbd{d} and @kbd{x} |
17 | are redefined for special Dired commands. Some Dired commands | |
18 | @dfn{mark} or @dfn{flag} the @dfn{current file} (that is, the file on | |
19 | the current line); other commands operate on the marked files or on | |
20 | the flagged files. You first mark certain files in order to operate | |
21 | on all of them with on command. | |
c3149267 | 22 | |
a8ef67ae | 23 | The Dired-X package provides various extra features for Dired mode. |
390a5b3c | 24 | @xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. |
a8ef67ae | 25 | |
6bf7aab6 DL |
26 | @menu |
27 | * Enter: Dired Enter. How to invoke Dired. | |
0ec1f115 | 28 | * Navigation: Dired Navigation. Special motion commands in the Dired buffer. |
6bf7aab6 DL |
29 | * Deletion: Dired Deletion. Deleting files with Dired. |
30 | * Flagging Many Files:: Flagging files based on their names. | |
31 | * Visit: Dired Visiting. Other file operations through Dired. | |
32 | * Marks vs Flags:: Flagging for deletion vs marking. | |
33 | * Operating on Files:: How to copy, rename, print, compress, etc. | |
34 | either one file or several files. | |
35 | * Shell Commands in Dired:: Running a shell command on the marked files. | |
36 | * Transforming File Names:: Using patterns to rename multiple files. | |
37 | * Comparison in Dired:: Running `diff' by way of Dired. | |
38 | * Subdirectories in Dired:: Adding subdirectories to the Dired buffer. | |
39 | * Subdirectory Motion:: Moving across subdirectories, and up and down. | |
40 | * Hiding Subdirectories:: Making subdirectories visible or invisible. | |
41 | * Updating: Dired Updating. Discarding lines for files of no interest. | |
42 | * Find: Dired and Find. Using `find' to choose the files for Dired. | |
9ae7d7af | 43 | * Wdired:: Operating on files by editing the Dired buffer. |
67bca9b2 | 44 | * Misc: Misc Dired Features. Various other features. |
6bf7aab6 DL |
45 | @end menu |
46 | ||
47 | @node Dired Enter | |
48 | @section Entering Dired | |
49 | ||
50 | @findex dired | |
51 | @kindex C-x d | |
52 | @vindex dired-listing-switches | |
065e46d0 RS |
53 | To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command |
54 | reads a directory name or wildcard file name pattern as a minibuffer | |
e01a5bb5 | 55 | argument to specify the files to list. @kbd{C-x C-f} given a |
065e46d0 RS |
56 | directory name also invokes Dired. Where @code{dired} differs from |
57 | @code{list-directory} is that it puts the buffer into Dired mode, so | |
58 | that the special commands of Dired are available. | |
6bf7aab6 DL |
59 | |
60 | The variable @code{dired-listing-switches} specifies the options to | |
e01a5bb5 RS |
61 | give to @code{ls} for listing the directory; this string @emph{must} |
62 | contain @samp{-l}. If you use a numeric prefix argument with the | |
63 | @code{dired} command, you can specify the @code{ls} switches with the | |
64 | minibuffer before you enter the directory specification. No matter | |
65 | how they are specified, the @code{ls} switches can include short | |
66 | options (that is, single characters) requiring no arguments, and long | |
67 | options (starting with @samp{--}) whose arguments are specified with | |
68 | @samp{=}. | |
6bf7aab6 DL |
69 | |
70 | @findex dired-other-window | |
71 | @kindex C-x 4 d | |
72 | @findex dired-other-frame | |
73 | @kindex C-x 5 d | |
74 | To display the Dired buffer in another window rather than in the | |
75 | selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead | |
76 | of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a | |
77 | separate frame to display the Dired buffer. | |
78 | ||
c3149267 EZ |
79 | @node Dired Navigation |
80 | @section Navigation in the Dired Buffer | |
6bf7aab6 DL |
81 | |
82 | @kindex C-n @r{(Dired)} | |
83 | @kindex C-p @r{(Dired)} | |
84 | All the usual Emacs cursor motion commands are available in Dired | |
e01a5bb5 RS |
85 | buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the |
86 | cursor at the beginning of the file name on the line, rather than at | |
87 | the beginning of the line. | |
6bf7aab6 DL |
88 | |
89 | @kindex SPC @r{(Dired)} | |
90 | For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent | |
91 | to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is | |
92 | so common in Dired that it deserves to be easy to type.) @key{DEL} | |
93 | (move up and unflag) is often useful simply for moving up. | |
94 | ||
9eae419d | 95 | @findex dired-goto-file |
27437d8b | 96 | @kindex M-g @r{(Dired)} |
9eae419d RS |
97 | @kbd{M-g} (@code{dired-goto-file}) moves point to the line that |
98 | describes a specified file or directory. | |
99 | ||
c3149267 EZ |
100 | Some additional navigation commands are available when the Dired |
101 | buffer includes several directories. @xref{Subdirectory Motion}. | |
102 | ||
6bf7aab6 DL |
103 | @node Dired Deletion |
104 | @section Deleting Files with Dired | |
105 | @cindex flagging files (in Dired) | |
106 | @cindex deleting files (in Dired) | |
107 | ||
0ec1f115 RS |
108 | One of the most frequent uses of Dired is to first @dfn{flag} files for |
109 | deletion, then delete the files that were flagged. | |
6bf7aab6 DL |
110 | |
111 | @table @kbd | |
112 | @item d | |
113 | Flag this file for deletion. | |
114 | @item u | |
115 | Remove deletion flag on this line. | |
116 | @item @key{DEL} | |
117 | Move point to previous line and remove the deletion flag on that line. | |
118 | @item x | |
119 | Delete the files that are flagged for deletion. | |
120 | @end table | |
121 | ||
122 | @kindex d @r{(Dired)} | |
123 | @findex dired-flag-file-deletion | |
e01a5bb5 RS |
124 | You can flag a file for deletion by moving to the line describing |
125 | the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The | |
126 | deletion flag is visible as a @samp{D} at the beginning of the line. | |
127 | This command moves point to the next line, so that repeated @kbd{d} | |
128 | commands flag successive files. A numeric argument serves as a repeat | |
129 | count. | |
6bf7aab6 DL |
130 | |
131 | @kindex u @r{(Dired deletion)} | |
132 | @kindex DEL @r{(Dired)} | |
e01a5bb5 RS |
133 | The reason for flagging files for deletion, rather than deleting |
134 | files immediately, is to reduce the danger of deleting a file | |
135 | accidentally. Until you direct Dired to delete the flagged files, you | |
136 | can remove deletion flags using the commands @kbd{u} and @key{DEL}. | |
137 | @kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes | |
138 | flags rather than making flags. @key{DEL} | |
139 | (@code{dired-unmark-backward}) moves upward, removing flags; it is | |
140 | like @kbd{u} with argument @minus{}1. | |
6bf7aab6 DL |
141 | |
142 | @kindex x @r{(Dired)} | |
5942fb80 | 143 | @findex dired-do-flagged-delete |
6bf7aab6 | 144 | @cindex expunging (Dired) |
e01a5bb5 RS |
145 | To delete the flagged files, type @kbd{x} |
146 | (@code{dired-do-flagged-delete}). (This is also known as | |
147 | @dfn{expunging}.) This command first displays a list of all the file | |
148 | names flagged for deletion, and requests confirmation with @kbd{yes}. | |
149 | If you confirm, Dired deletes the flagged files, then deletes their | |
150 | lines from the text of the Dired buffer. The Dired buffer, with | |
151 | somewhat fewer lines, remains selected. | |
6bf7aab6 DL |
152 | |
153 | If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you | |
154 | return immediately to Dired, with the deletion flags still present in | |
155 | the buffer, and no files actually deleted. | |
156 | ||
e01a5bb5 RS |
157 | @cindex recursive deletion |
158 | @vindex dired-recursive-deletes | |
159 | You can delete empty directories just like other files, but normally | |
160 | Dired cannot delete directories that are nonempty. If the variable | |
161 | @code{dired-recursive-deletes} is non-@code{nil}, then Dired can | |
162 | delete nonempty directories including all their contents. That can | |
163 | be somewhat risky. | |
164 | ||
6bf7aab6 DL |
165 | @node Flagging Many Files |
166 | @section Flagging Many Files at Once | |
a33b10b5 | 167 | @cindex flagging many files for deletion (in Dired) |
6bf7aab6 DL |
168 | |
169 | @table @kbd | |
170 | @item # | |
171 | Flag all auto-save files (files whose names start and end with @samp{#}) | |
172 | for deletion (@pxref{Auto Save}). | |
173 | ||
174 | @item ~ | |
175 | Flag all backup files (files whose names end with @samp{~}) for deletion | |
176 | (@pxref{Backup}). | |
177 | ||
178 | @item & | |
e01a5bb5 RS |
179 | Flag for deletion all files with certain kinds of names which suggest |
180 | you could easily create those files again. | |
6bf7aab6 DL |
181 | |
182 | @item .@: @r{(Period)} | |
183 | Flag excess numeric backup files for deletion. The oldest and newest | |
184 | few backup files of any one file are exempt; the middle ones are | |
185 | flagged. | |
186 | ||
187 | @item % d @var{regexp} @key{RET} | |
188 | Flag for deletion all files whose names match the regular expression | |
189 | @var{regexp}. | |
190 | @end table | |
191 | ||
192 | The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for | |
193 | deletion, based on their file names. These commands are useful | |
194 | precisely because they do not themselves delete any files; you can | |
195 | remove the deletion flags from any flagged files that you really wish to | |
196 | keep.@refill | |
197 | ||
198 | @kindex & @r{(Dired)} | |
199 | @findex dired-flag-garbage-files | |
200 | @vindex dired-garbage-files-regexp | |
a33b10b5 | 201 | @cindex deleting some backup files |
6bf7aab6 DL |
202 | @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names |
203 | match the regular expression specified by the variable | |
204 | @code{dired-garbage-files-regexp}. By default, this matches certain | |
5942fb80 RS |
205 | files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and |
206 | @samp{.rej} files produced by @code{patch}. | |
6bf7aab6 DL |
207 | |
208 | @kindex # @r{(Dired)} | |
6bf7aab6 | 209 | @findex dired-flag-auto-save-files |
a33b10b5 | 210 | @cindex deleting auto-save files |
6bf7aab6 | 211 | @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all |
e01a5bb5 RS |
212 | files whose names look like auto-save files---that is, files whose |
213 | names begin and end with @samp{#}. @xref{Auto Save}. | |
3a2aa1dc EZ |
214 | |
215 | @kindex ~ @r{(Dired)} | |
216 | @findex dired-flag-backup-files | |
e01a5bb5 RS |
217 | @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all |
218 | files whose names say they are backup files---that is, files whose | |
219 | names end in @samp{~}. @xref{Backup}. | |
6bf7aab6 DL |
220 | |
221 | @kindex . @r{(Dired)} | |
222 | @vindex dired-kept-versions | |
223 | @findex dired-clean-directory | |
224 | @kbd{.} (period, @code{dired-clean-directory}) flags just some of the | |
225 | backup files for deletion: all but the oldest few and newest few backups | |
226 | of any one file. Normally @code{dired-kept-versions} (@strong{not} | |
227 | @code{kept-new-versions}; that applies only when saving) specifies the | |
228 | number of newest versions of each file to keep, and | |
229 | @code{kept-old-versions} specifies the number of oldest versions to | |
230 | keep. | |
231 | ||
232 | Period with a positive numeric argument, as in @kbd{C-u 3 .}, | |
233 | specifies the number of newest versions to keep, overriding | |
234 | @code{dired-kept-versions}. A negative numeric argument overrides | |
235 | @code{kept-old-versions}, using minus the value of the argument to | |
236 | specify the number of oldest versions of each file to keep. | |
237 | ||
238 | @findex dired-flag-files-regexp | |
239 | @kindex % d @r{(Dired)} | |
240 | The @kbd{% d} command flags all files whose names match a specified | |
241 | regular expression (@code{dired-flag-files-regexp}). Only the | |
242 | non-directory part of the file name is used in matching. You can use | |
e01a5bb5 RS |
243 | @samp{^} and @samp{$} to anchor matches. You can exclude certain |
244 | subdirectories from marking by hiding them while you use @kbd{% d}. | |
245 | @xref{Hiding Subdirectories}. | |
6bf7aab6 DL |
246 | |
247 | @node Dired Visiting | |
248 | @section Visiting Files in Dired | |
249 | ||
250 | There are several Dired commands for visiting or examining the files | |
251 | listed in the Dired buffer. All of them apply to the current line's | |
252 | file; if that file is really a directory, these commands invoke Dired on | |
253 | that subdirectory (making a separate Dired buffer). | |
254 | ||
255 | @table @kbd | |
256 | @item f | |
257 | @kindex f @r{(Dired)} | |
258 | @findex dired-find-file | |
259 | Visit the file described on the current line, like typing @kbd{C-x C-f} | |
260 | and supplying that file name (@code{dired-find-file}). @xref{Visiting}. | |
261 | ||
262 | @item @key{RET} | |
c3149267 | 263 | @itemx e |
6bf7aab6 | 264 | @kindex RET @r{(Dired)} |
c3149267 | 265 | @kindex e @r{(Dired)} |
6bf7aab6 DL |
266 | Equivalent to @kbd{f}. |
267 | ||
065e46d0 | 268 | @ignore @c This command seems too risky to document at all. |
f8a12fe7 GM |
269 | @item a |
270 | @kindex a @r{(Dired)} | |
271 | @findex dired-find-alternate-file | |
272 | Like @kbd{f}, but replaces the contents of the Dired buffer with | |
38458147 | 273 | that of an alternate file or directory (@code{dired-find-alternate-file}). |
065e46d0 | 274 | @end ignore |
f8a12fe7 | 275 | |
6bf7aab6 DL |
276 | @item o |
277 | @kindex o @r{(Dired)} | |
278 | @findex dired-find-file-other-window | |
279 | Like @kbd{f}, but uses another window to display the file's buffer | |
280 | (@code{dired-find-file-other-window}). The Dired buffer remains visible | |
281 | in the first window. This is like using @kbd{C-x 4 C-f} to visit the | |
282 | file. @xref{Windows}. | |
283 | ||
284 | @item C-o | |
285 | @kindex C-o @r{(Dired)} | |
286 | @findex dired-display-file | |
287 | Visit the file described on the current line, and display the buffer in | |
288 | another window, but do not select that window (@code{dired-display-file}). | |
289 | ||
065e46d0 RS |
290 | @item Mouse-1 |
291 | @itemx Mouse-2 | |
6bf7aab6 DL |
292 | @findex dired-mouse-find-file-other-window |
293 | Visit the file named by the line you click on | |
294 | (@code{dired-mouse-find-file-other-window}). This uses another window | |
295 | to display the file, like the @kbd{o} command. | |
296 | ||
297 | @item v | |
298 | @kindex v @r{(Dired)} | |
299 | @findex dired-view-file | |
105fa3fb LT |
300 | View the file described on the current line, using @kbd{M-x view-file} |
301 | (@code{dired-view-file}). Viewing a file with @code{view-file} is | |
302 | like visiting it, but is slanted toward moving around in the file | |
eb18d007 | 303 | conveniently and does not allow changing the file. @xref{Misc File |
105fa3fb | 304 | Ops, View File, Miscellaneous File Operations}. |
c3149267 EZ |
305 | |
306 | @item ^ | |
307 | @kindex ^ @r{(Dired)} | |
308 | @findex dired-up-directory | |
309 | Visit the parent directory of the current directory | |
e01a5bb5 RS |
310 | (@code{dired-up-directory}). This is equivalent to moving to the line |
311 | for @file{..} and typing @kbd{f} there. | |
6bf7aab6 DL |
312 | @end table |
313 | ||
314 | @node Marks vs Flags | |
315 | @section Dired Marks vs. Flags | |
316 | ||
a33b10b5 | 317 | @cindex marking many files (in Dired) |
5942fb80 RS |
318 | Instead of flagging a file with @samp{D}, you can @dfn{mark} the |
319 | file with some other character (usually @samp{*}). Most Dired | |
e01a5bb5 RS |
320 | commands to operate on files use the files marked with @samp{*}. The |
321 | only command that operates on flagged flies is @kbd{x}, which expunges | |
322 | them. | |
6bf7aab6 | 323 | |
e01a5bb5 RS |
324 | Here are some commands for marking with @samp{*}, for unmarking, and |
325 | for operating on marks. (@xref{Dired Deletion}, for commands to flag | |
326 | and unflag files.) | |
6bf7aab6 DL |
327 | |
328 | @table @kbd | |
329 | @item m | |
330 | @itemx * m | |
331 | @kindex m @r{(Dired)} | |
332 | @kindex * m @r{(Dired)} | |
333 | @findex dired-mark | |
334 | Mark the current file with @samp{*} (@code{dired-mark}). With a numeric | |
335 | argument @var{n}, mark the next @var{n} files starting with the current | |
336 | file. (If @var{n} is negative, mark the previous @minus{}@var{n} | |
337 | files.) | |
338 | ||
339 | @item * * | |
340 | @kindex * * @r{(Dired)} | |
341 | @findex dired-mark-executables | |
a33b10b5 | 342 | @cindex marking executable files (in Dired) |
6bf7aab6 DL |
343 | Mark all executable files with @samp{*} |
344 | (@code{dired-mark-executables}). With a numeric argument, unmark all | |
345 | those files. | |
346 | ||
347 | @item * @@ | |
348 | @kindex * @@ @r{(Dired)} | |
349 | @findex dired-mark-symlinks | |
9eae419d | 350 | @cindex marking symbolic links (in Dired) |
6bf7aab6 DL |
351 | Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). |
352 | With a numeric argument, unmark all those files. | |
353 | ||
354 | @item * / | |
355 | @kindex * / @r{(Dired)} | |
356 | @findex dired-mark-directories | |
a33b10b5 | 357 | @cindex marking subdirectories (in Dired) |
e01a5bb5 | 358 | Mark with @samp{*} all files which are directories, except for |
6bf7aab6 DL |
359 | @file{.} and @file{..} (@code{dired-mark-directories}). With a numeric |
360 | argument, unmark all those files. | |
361 | ||
362 | @item * s | |
363 | @kindex * s @r{(Dired)} | |
364 | @findex dired-mark-subdir-files | |
365 | Mark all the files in the current subdirectory, aside from @file{.} | |
366 | and @file{..} (@code{dired-mark-subdir-files}). | |
367 | ||
368 | @item u | |
369 | @itemx * u | |
370 | @kindex u @r{(Dired)} | |
371 | @kindex * u @r{(Dired)} | |
372 | @findex dired-unmark | |
373 | Remove any mark on this line (@code{dired-unmark}). | |
374 | ||
375 | @item @key{DEL} | |
376 | @itemx * @key{DEL} | |
377 | @kindex * DEL @r{(Dired)} | |
378 | @findex dired-unmark-backward | |
a33b10b5 | 379 | @cindex unmarking files (in Dired) |
6bf7aab6 DL |
380 | Move point to previous line and remove any mark on that line |
381 | (@code{dired-unmark-backward}). | |
382 | ||
383 | @item * ! | |
105fa3fb | 384 | @itemx U |
6bf7aab6 | 385 | @kindex * ! @r{(Dired)} |
105fa3fb | 386 | @kindex U @r{(Dired)} |
5942fb80 | 387 | @findex dired-unmark-all-marks |
6bf7aab6 | 388 | Remove all marks from all the files in this Dired buffer |
5942fb80 | 389 | (@code{dired-unmark-all-marks}). |
6bf7aab6 DL |
390 | |
391 | @item * ? @var{markchar} | |
105fa3fb | 392 | @itemx M-@key{DEL} |
6bf7aab6 | 393 | @kindex * ? @r{(Dired)} |
105fa3fb | 394 | @kindex M-DEL @r{(Dired)} |
6bf7aab6 DL |
395 | @findex dired-unmark-all-files |
396 | Remove all marks that use the character @var{markchar} | |
397 | (@code{dired-unmark-all-files}). The argument is a single | |
38458147 | 398 | character---do not use @key{RET} to terminate it. See the description |
91dc757e RS |
399 | of the @kbd{* c} command below, which lets you replace one mark |
400 | character with another. | |
6bf7aab6 DL |
401 | |
402 | With a numeric argument, this command queries about each marked file, | |
403 | asking whether to remove its mark. You can answer @kbd{y} meaning yes, | |
404 | @kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining | |
405 | files without asking about them. | |
406 | ||
407 | @item * C-n | |
105fa3fb | 408 | @itemx M-@} |
6bf7aab6 DL |
409 | @findex dired-next-marked-file |
410 | @kindex * C-n @r{(Dired)} | |
105fa3fb | 411 | @kindex M-@} @r{(Dired)} |
6bf7aab6 DL |
412 | Move down to the next marked file (@code{dired-next-marked-file}) |
413 | A file is ``marked'' if it has any kind of mark. | |
414 | ||
415 | @item * C-p | |
105fa3fb | 416 | @itemx M-@{ |
6bf7aab6 DL |
417 | @findex dired-prev-marked-file |
418 | @kindex * C-p @r{(Dired)} | |
105fa3fb | 419 | @kindex M-@{ @r{(Dired)} |
6bf7aab6 DL |
420 | Move up to the previous marked file (@code{dired-prev-marked-file}) |
421 | ||
105fa3fb LT |
422 | @item t |
423 | @itemx * t | |
424 | @kindex t @r{(Dired)} | |
6bf7aab6 | 425 | @kindex * t @r{(Dired)} |
db6b2ec6 | 426 | @findex dired-toggle-marks |
a33b10b5 | 427 | @cindex toggling marks (in Dired) |
db6b2ec6 | 428 | Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} |
6bf7aab6 DL |
429 | become unmarked, and unmarked files are marked with @samp{*}. Files |
430 | marked in any other way are not affected. | |
431 | ||
38458147 | 432 | @item * c @var{old-markchar} @var{new-markchar} |
6bf7aab6 DL |
433 | @kindex * c @r{(Dired)} |
434 | @findex dired-change-marks | |
38458147 EZ |
435 | Replace all marks that use the character @var{old-markchar} with marks |
436 | that use the character @var{new-markchar} (@code{dired-change-marks}). | |
437 | This command is the primary way to create or use marks other than | |
438 | @samp{*} or @samp{D}. The arguments are single characters---do not use | |
439 | @key{RET} to terminate them. | |
6bf7aab6 DL |
440 | |
441 | You can use almost any character as a mark character by means of this | |
38458147 EZ |
442 | command, to distinguish various classes of files. If @var{old-markchar} |
443 | is a space (@samp{ }), then the command operates on all unmarked files; | |
444 | if @var{new-markchar} is a space, then the command unmarks the files it | |
445 | acts on. | |
6bf7aab6 DL |
446 | |
447 | To illustrate the power of this command, here is how to put @samp{D} | |
448 | flags on all the files that have no marks, while unflagging all those | |
449 | that already have @samp{D} flags: | |
450 | ||
451 | @example | |
452 | * c D t * c SPC D * c t SPC | |
453 | @end example | |
454 | ||
91dc757e | 455 | This assumes that no files were already marked with @samp{t}. |
6bf7aab6 DL |
456 | |
457 | @item % m @var{regexp} @key{RET} | |
458 | @itemx * % @var{regexp} @key{RET} | |
459 | @findex dired-mark-files-regexp | |
460 | @kindex % m @r{(Dired)} | |
461 | @kindex * % @r{(Dired)} | |
462 | Mark (with @samp{*}) all files whose names match the regular expression | |
463 | @var{regexp} (@code{dired-mark-files-regexp}). This command is like | |
464 | @kbd{% d}, except that it marks files with @samp{*} instead of flagging | |
e01a5bb5 | 465 | with @samp{D}. |
6bf7aab6 DL |
466 | |
467 | Only the non-directory part of the file name is used in matching. Use | |
e01a5bb5 RS |
468 | @samp{^} and @samp{$} to anchor matches. You can exclude |
469 | subdirectories by temporarily hiding them (@pxref{Hiding | |
470 | Subdirectories}). | |
6bf7aab6 DL |
471 | |
472 | @item % g @var{regexp} @key{RET} | |
473 | @findex dired-mark-files-containing-regexp | |
a33b10b5 EZ |
474 | @kindex % g @r{(Dired)} |
475 | @cindex finding files containing regexp matches (in Dired) | |
6bf7aab6 DL |
476 | Mark (with @samp{*}) all files whose @emph{contents} contain a match for |
477 | the regular expression @var{regexp} | |
478 | (@code{dired-mark-files-containing-regexp}). This command is like | |
479 | @kbd{% m}, except that it searches the file contents instead of the file | |
480 | name. | |
481 | ||
e01a5bb5 RS |
482 | @item C-x u |
483 | @itemx C-_ | |
484 | @itemx C-/ | |
6bf7aab6 DL |
485 | @kindex C-_ @r{(Dired)} |
486 | @findex dired-undo | |
487 | Undo changes in the Dired buffer, such as adding or removing | |
4691d21e | 488 | marks (@code{dired-undo}). @emph{This command does not revert the |
3a2aa1dc | 489 | actual file operations, nor recover lost files!} It just undoes |
e01a5bb5 RS |
490 | changes in the buffer itself. |
491 | ||
492 | In some cases, using this after commands that operate on files can | |
493 | cause trouble. For example, after renaming one or more files, | |
494 | @code{dired-undo} restores the original names in the Dired buffer, | |
495 | which gets the Dired buffer out of sync with the actual contents of | |
496 | the directory. | |
6bf7aab6 DL |
497 | @end table |
498 | ||
499 | @node Operating on Files | |
500 | @section Operating on Files | |
501 | @cindex operating on files in Dired | |
502 | ||
503 | This section describes the basic Dired commands to operate on one file | |
504 | or several files. All of these commands are capital letters; all of | |
505 | them use the minibuffer, either to read an argument or to ask for | |
e01a5bb5 RS |
506 | confirmation, before they act. All of them let you specify the |
507 | files to manipulate in these ways: | |
6bf7aab6 DL |
508 | |
509 | @itemize @bullet | |
510 | @item | |
511 | If you give the command a numeric prefix argument @var{n}, it operates | |
512 | on the next @var{n} files, starting with the current file. (If @var{n} | |
513 | is negative, the command operates on the @minus{}@var{n} files preceding | |
514 | the current line.) | |
515 | ||
516 | @item | |
517 | Otherwise, if some files are marked with @samp{*}, the command operates | |
518 | on all those files. | |
519 | ||
520 | @item | |
521 | Otherwise, the command operates on the current file only. | |
522 | @end itemize | |
523 | ||
e01a5bb5 RS |
524 | @noindent |
525 | Certain other Dired commands, such as @kbd{!} and the @samp{%} | |
526 | commands, use the same conventions to decide which files to work on. | |
527 | ||
b792ae36 EZ |
528 | @vindex dired-dwim-target |
529 | @cindex two directories (in Dired) | |
530 | Commands which ask for a destination directory, such as those which | |
531 | copy and rename files or create links for them, try to guess the default | |
532 | target directory for the operation. Normally, they suggest the Dired | |
533 | buffer's default directory, but if the variable @code{dired-dwim-target} | |
534 | is non-@code{nil}, and if there is another Dired buffer displayed in the | |
535 | next window, that other buffer's directory is suggested instead. | |
536 | ||
e01a5bb5 | 537 | Here are the file-manipulating Dired commands that operate on files. |
6bf7aab6 DL |
538 | |
539 | @table @kbd | |
540 | @findex dired-do-copy | |
541 | @kindex C @r{(Dired)} | |
a33b10b5 | 542 | @cindex copying files (in Dired) |
6bf7aab6 DL |
543 | @item C @var{new} @key{RET} |
544 | Copy the specified files (@code{dired-do-copy}). The argument @var{new} | |
545 | is the directory to copy into, or (if copying a single file) the new | |
546 | name. | |
547 | ||
548 | @vindex dired-copy-preserve-time | |
e01a5bb5 RS |
549 | If @code{dired-copy-preserve-time} is non-@code{nil}, then copying |
550 | with this command preserves the modification time of the old file in | |
551 | the copy. | |
6bf7aab6 | 552 | |
a8ef67ae | 553 | @vindex dired-recursive-copies |
db1433e5 | 554 | @cindex recursive copying |
e01a5bb5 RS |
555 | The variable @code{dired-recursive-copies} controls whether to copy |
556 | directories recursively. The default is @code{nil}, which means that | |
557 | directories cannot be copied. | |
a8ef67ae | 558 | |
6bf7aab6 DL |
559 | @item D |
560 | @findex dired-do-delete | |
561 | @kindex D @r{(Dired)} | |
562 | Delete the specified files (@code{dired-do-delete}). Like the other | |
563 | commands in this section, this command operates on the @emph{marked} | |
564 | files, or the next @var{n} files. By contrast, @kbd{x} | |
5942fb80 | 565 | (@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. |
6bf7aab6 DL |
566 | |
567 | @findex dired-do-rename | |
568 | @kindex R @r{(Dired)} | |
a33b10b5 | 569 | @cindex renaming files (in Dired) |
6bf7aab6 DL |
570 | @item R @var{new} @key{RET} |
571 | Rename the specified files (@code{dired-do-rename}). The argument | |
572 | @var{new} is the directory to rename into, or (if renaming a single | |
573 | file) the new name. | |
574 | ||
575 | Dired automatically changes the visited file name of buffers associated | |
576 | with renamed files so that they refer to the new names. | |
577 | ||
578 | @findex dired-do-hardlink | |
579 | @kindex H @r{(Dired)} | |
a33b10b5 | 580 | @cindex hard links (in Dired) |
6bf7aab6 DL |
581 | @item H @var{new} @key{RET} |
582 | Make hard links to the specified files (@code{dired-do-hardlink}). The | |
583 | argument @var{new} is the directory to make the links in, or (if making | |
584 | just one link) the name to give the link. | |
585 | ||
586 | @findex dired-do-symlink | |
587 | @kindex S @r{(Dired)} | |
9eae419d | 588 | @cindex symbolic links (creation in Dired) |
6bf7aab6 DL |
589 | @item S @var{new} @key{RET} |
590 | Make symbolic links to the specified files (@code{dired-do-symlink}). | |
591 | The argument @var{new} is the directory to make the links in, or (if | |
592 | making just one link) the name to give the link. | |
593 | ||
594 | @findex dired-do-chmod | |
595 | @kindex M @r{(Dired)} | |
a33b10b5 | 596 | @cindex changing file permissions (in Dired) |
6bf7aab6 DL |
597 | @item M @var{modespec} @key{RET} |
598 | Change the mode (also called ``permission bits'') of the specified files | |
599 | (@code{dired-do-chmod}). This uses the @code{chmod} program, so | |
600 | @var{modespec} can be any argument that @code{chmod} can handle. | |
601 | ||
602 | @findex dired-do-chgrp | |
603 | @kindex G @r{(Dired)} | |
4946337d | 604 | @cindex changing file group (in Dired) |
6bf7aab6 DL |
605 | @item G @var{newgroup} @key{RET} |
606 | Change the group of the specified files to @var{newgroup} | |
607 | (@code{dired-do-chgrp}). | |
608 | ||
609 | @findex dired-do-chown | |
610 | @kindex O @r{(Dired)} | |
a33b10b5 | 611 | @cindex changing file owner (in Dired) |
6bf7aab6 DL |
612 | @item O @var{newowner} @key{RET} |
613 | Change the owner of the specified files to @var{newowner} | |
614 | (@code{dired-do-chown}). (On most systems, only the superuser can do | |
615 | this.) | |
616 | ||
617 | @vindex dired-chown-program | |
618 | The variable @code{dired-chown-program} specifies the name of the | |
619 | program to use to do the work (different systems put @code{chown} in | |
620 | different places). | |
621 | ||
100d3624 JL |
622 | @findex dired-do-touch |
623 | @kindex T @r{(Dired)} | |
624 | @cindex changing file time (in Dired) | |
625 | @item T @var{timestamp} @key{RET} | |
e01a5bb5 RS |
626 | Touch the specified files (@code{dired-do-touch}). This means |
627 | updating their modification times to the present time. | |
100d3624 | 628 | |
6bf7aab6 DL |
629 | @findex dired-do-print |
630 | @kindex P @r{(Dired)} | |
a33b10b5 | 631 | @cindex printing files (in Dired) |
6bf7aab6 DL |
632 | @item P @var{command} @key{RET} |
633 | Print the specified files (@code{dired-do-print}). You must specify the | |
634 | command to print them with, but the minibuffer starts out with a | |
635 | suitable guess made using the variables @code{lpr-command} and | |
636 | @code{lpr-switches} (the same variables that @code{lpr-buffer} uses; | |
e159097a | 637 | @pxref{Printing}). |
6bf7aab6 DL |
638 | |
639 | @findex dired-do-compress | |
640 | @kindex Z @r{(Dired)} | |
a33b10b5 | 641 | @cindex compressing files (in Dired) |
6bf7aab6 DL |
642 | @item Z |
643 | Compress the specified files (@code{dired-do-compress}). If the file | |
e01a5bb5 | 644 | appears to be a compressed file already, uncompress it instead. |
6bf7aab6 DL |
645 | |
646 | @findex dired-do-load | |
647 | @kindex L @r{(Dired)} | |
a33b10b5 | 648 | @cindex loading several files (in Dired) |
6bf7aab6 DL |
649 | @item L |
650 | Load the specified Emacs Lisp files (@code{dired-do-load}). | |
651 | @xref{Lisp Libraries}. | |
652 | ||
653 | @findex dired-do-byte-compile | |
654 | @kindex B @r{(Dired)} | |
a33b10b5 | 655 | @cindex byte-compiling several files (in Dired) |
6bf7aab6 DL |
656 | @item B |
657 | Byte compile the specified Emacs Lisp files | |
658 | (@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte | |
659 | Compilation, elisp, The Emacs Lisp Reference Manual}. | |
660 | ||
661 | @kindex A @r{(Dired)} | |
662 | @findex dired-do-search | |
a33b10b5 | 663 | @cindex search multiple files (in Dired) |
6bf7aab6 DL |
664 | @item A @var{regexp} @key{RET} |
665 | Search all the specified files for the regular expression @var{regexp} | |
666 | (@code{dired-do-search}). | |
667 | ||
668 | This command is a variant of @code{tags-search}. The search stops at | |
669 | the first match it finds; use @kbd{M-,} to resume the search and find | |
670 | the next match. @xref{Tags Search}. | |
671 | ||
672 | @kindex Q @r{(Dired)} | |
5942fb80 | 673 | @findex dired-do-query-replace-regexp |
a33b10b5 | 674 | @cindex search and replace in multiple files (in Dired) |
5942fb80 | 675 | @item Q @var{regexp} @key{RET} @var{to} @key{RET} |
6bf7aab6 | 676 | Perform @code{query-replace-regexp} on each of the specified files, |
5942fb80 RS |
677 | replacing matches for @var{regexp} with the string |
678 | @var{to} (@code{dired-do-query-replace-regexp}). | |
6bf7aab6 DL |
679 | |
680 | This command is a variant of @code{tags-query-replace}. If you exit the | |
681 | query replace loop, you can use @kbd{M-,} to resume the scan and replace | |
682 | more matches. @xref{Tags Search}. | |
683 | @end table | |
684 | ||
6bf7aab6 DL |
685 | @node Shell Commands in Dired |
686 | @section Shell Commands in Dired | |
687 | @cindex shell commands, Dired | |
688 | ||
689 | @findex dired-do-shell-command | |
690 | @kindex ! @r{(Dired)} | |
38458147 | 691 | @kindex X @r{(Dired)} |
e01a5bb5 RS |
692 | The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a |
693 | shell command string in the minibuffer and runs that shell command on | |
694 | all the specified files. (@kbd{X} is a synonym for @kbd{!}.) You can | |
695 | specify the files to operate on in the usual ways for Dired commands | |
696 | (@pxref{Operating on Files}). | |
697 | ||
698 | The working directory for the shell command is the top-level directory | |
699 | of the Dired buffer. | |
700 | ||
701 | There are two ways of applying a shell command to multiple files: | |
6bf7aab6 DL |
702 | |
703 | @itemize @bullet | |
704 | @item | |
eb18d007 RS |
705 | If you use @samp{*} surrounded by whitespace in the shell command, |
706 | then the command runs just once, with the list of file names | |
707 | substituted for the @samp{*}. The order of file names is the order of | |
708 | appearance in the Dired buffer. | |
6bf7aab6 DL |
709 | |
710 | Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire | |
711 | list of file names, putting them into one tar file @file{foo.tar}. | |
712 | ||
eb18d007 RS |
713 | If you want to use @samp{*} as a shell wildcard with whitespace around |
714 | it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; | |
715 | but since the @samp{*} is not surrounded by whitespace, Dired does | |
716 | not treat it specially. | |
717 | ||
6bf7aab6 | 718 | @item |
eb18d007 RS |
719 | If the command string doesn't contain @samp{*} surrounded by |
720 | whitespace, then it runs once @emph{for each file}. Normally the file | |
721 | name is added at the end. | |
6bf7aab6 DL |
722 | |
723 | For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each | |
724 | file. | |
6bf7aab6 | 725 | |
eb18d007 | 726 | @item |
065e46d0 | 727 | However, if the command string contains @samp{?} surrounded by |
e01a5bb5 | 728 | whitespace, the current file name is substituted for @samp{?} (rather |
065e46d0 RS |
729 | than added at the end). You can use @samp{?} this way more than once |
730 | in the command, and the same file name replaces each occurrence. | |
eb18d007 | 731 | @end itemize |
6bf7aab6 | 732 | |
e01a5bb5 | 733 | To iterate over the file names in a more complicated fashion, use an |
2d36e6a9 RS |
734 | explicit shell loop. For example, here is how to uuencode each file, |
735 | making the output file name by appending @samp{.uu} to the input file | |
736 | name: | |
a8ef67ae RS |
737 | |
738 | @example | |
eb18d007 | 739 | for file in * ; do uuencode "$file" "$file" >"$file".uu; done |
a8ef67ae | 740 | @end example |
4bce911c | 741 | |
e01a5bb5 RS |
742 | The @kbd{!} command does not attempt to update the Dired buffer to |
743 | show new or modified files, because it doesn't understand shell | |
6bf7aab6 DL |
744 | commands, and does not know what files the shell command changed. Use |
745 | the @kbd{g} command to update the Dired buffer (@pxref{Dired | |
746 | Updating}). | |
747 | ||
748 | @node Transforming File Names | |
749 | @section Transforming File Names in Dired | |
750 | ||
4691d21e | 751 | This section describes Dired commands which alter file names in a |
e01a5bb5 RS |
752 | systematic way. Each command operates on some or all of the marked |
753 | files, using a new name made by transforming the existing name. | |
4691d21e EZ |
754 | |
755 | Like the basic Dired file-manipulation commands (@pxref{Operating on | |
756 | Files}), the commands described here operate either on the next | |
757 | @var{n} files, or on all files marked with @samp{*}, or on the current | |
758 | file. (To mark files, use the commands described in @ref{Marks vs | |
759 | Flags}.) | |
760 | ||
761 | All of the commands described in this section work | |
762 | @emph{interactively}: they ask you to confirm the operation for each | |
763 | candidate file. Thus, you can select more files than you actually | |
764 | need to operate on (e.g., with a regexp that matches many files), and | |
e01a5bb5 | 765 | then filter the selected names by typing @kbd{y} or @kbd{n} when the |
4691d21e | 766 | command prompts for confirmation. |
6bf7aab6 DL |
767 | |
768 | @table @kbd | |
769 | @findex dired-upcase | |
770 | @kindex % u @r{(Dired)} | |
a33b10b5 | 771 | @cindex upcase file names |
6bf7aab6 DL |
772 | @item % u |
773 | Rename each of the selected files to an upper-case name | |
774 | (@code{dired-upcase}). If the old file names are @file{Foo} | |
775 | and @file{bar}, the new names are @file{FOO} and @file{BAR}. | |
776 | ||
777 | @item % l | |
778 | @findex dired-downcase | |
779 | @kindex % l @r{(Dired)} | |
a33b10b5 | 780 | @cindex downcase file names |
6bf7aab6 DL |
781 | Rename each of the selected files to a lower-case name |
782 | (@code{dired-downcase}). If the old file names are @file{Foo} and | |
783 | @file{bar}, the new names are @file{foo} and @file{bar}. | |
784 | ||
785 | @item % R @var{from} @key{RET} @var{to} @key{RET} | |
786 | @kindex % R @r{(Dired)} | |
787 | @findex dired-do-rename-regexp | |
788 | @itemx % C @var{from} @key{RET} @var{to} @key{RET} | |
789 | @kindex % C @r{(Dired)} | |
790 | @findex dired-do-copy-regexp | |
791 | @itemx % H @var{from} @key{RET} @var{to} @key{RET} | |
792 | @kindex % H @r{(Dired)} | |
793 | @findex dired-do-hardlink-regexp | |
794 | @itemx % S @var{from} @key{RET} @var{to} @key{RET} | |
795 | @kindex % S @r{(Dired)} | |
796 | @findex dired-do-symlink-regexp | |
797 | These four commands rename, copy, make hard links and make soft links, | |
798 | in each case computing the new name by regular-expression substitution | |
799 | from the name of the old file. | |
800 | @end table | |
801 | ||
e01a5bb5 RS |
802 | The four regular-expression substitution commands effectively |
803 | perform a search-and-replace on the selected file names. They read | |
804 | two arguments: a regular expression @var{from}, and a substitution | |
805 | pattern @var{to}; they match each ``old'' file name against | |
806 | @var{from}, and then replace the matching part with @var{to}. You can | |
807 | use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or | |
808 | part of what the pattern matched in the old file name, as in | |
809 | @code{replace-regexp} (@pxref{Regexp Replace}). If the regular | |
810 | expression matches more than once in a file name, only the first match | |
811 | is replaced. | |
6bf7aab6 DL |
812 | |
813 | For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each | |
814 | selected file by prepending @samp{x-} to its name. The inverse of this, | |
815 | removing @samp{x-} from the front of each file name, is also possible: | |
816 | one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is | |
817 | @kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor | |
818 | matches that should span the whole filename.) | |
819 | ||
820 | Normally, the replacement process does not consider the files' | |
821 | directory names; it operates on the file name within the directory. If | |
822 | you specify a numeric argument of zero, then replacement affects the | |
e01a5bb5 | 823 | entire absolute file name including directory name. (A non-zero |
4691d21e | 824 | argument specifies the number of files to operate on.) |
6bf7aab6 | 825 | |
e01a5bb5 RS |
826 | You may want to select the set of files to operate on using the same |
827 | regexp @var{from} that you will use to operate on them. To do this, | |
828 | mark those files with @kbd{% m @var{from} @key{RET}}, then use the | |
829 | same regular expression in the command to operate on the files. To | |
830 | make this more convenient, the @kbd{%} commands to operate on files | |
831 | use the last regular expression specified in any @kbd{%} command as a | |
832 | default. | |
6bf7aab6 DL |
833 | |
834 | @node Comparison in Dired | |
835 | @section File Comparison with Dired | |
a33b10b5 EZ |
836 | @cindex file comparison (in Dired) |
837 | @cindex compare files (in Dired) | |
6bf7aab6 DL |
838 | |
839 | Here are two Dired commands that compare specified files using | |
e01a5bb5 RS |
840 | @code{diff}. They show the output in a buffer using Diff mode |
841 | (@pxref{Comparing Files}). | |
6bf7aab6 DL |
842 | |
843 | @table @kbd | |
844 | @item = | |
845 | @findex dired-diff | |
846 | @kindex = @r{(Dired)} | |
e01a5bb5 RS |
847 | Compare the current file (the file at point) with another file (the |
848 | file at the mark) using the @code{diff} program (@code{dired-diff}). | |
849 | The file at the mark is the first argument of @code{diff}, and the | |
850 | file at point is the second argument. This refers to the ordinary | |
851 | Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} | |
7198b459 | 852 | (@code{set-mark-command}) to set the mark at the first file's line |
e01a5bb5 | 853 | (@pxref{Setting Mark}). |
6bf7aab6 DL |
854 | |
855 | @findex dired-backup-diff | |
856 | @kindex M-= @r{(Dired)} | |
857 | @item M-= | |
858 | Compare the current file with its latest backup file | |
859 | (@code{dired-backup-diff}). If the current file is itself a backup, | |
860 | compare it with the file it is a backup of; this way, you can compare | |
e01a5bb5 | 861 | a file with any one of its backups. |
6bf7aab6 DL |
862 | |
863 | The backup file is the first file given to @code{diff}. | |
864 | @end table | |
865 | ||
866 | @node Subdirectories in Dired | |
867 | @section Subdirectories in Dired | |
868 | @cindex subdirectories in Dired | |
869 | @cindex expanding subdirectories in Dired | |
870 | ||
871 | A Dired buffer displays just one directory in the normal case; | |
872 | but you can optionally include its subdirectories as well. | |
873 | ||
874 | The simplest way to include multiple directories in one Dired buffer is | |
875 | to specify the options @samp{-lR} for running @code{ls}. (If you give a | |
876 | numeric argument when you run Dired, then you can specify these options | |
877 | in the minibuffer.) That produces a recursive directory listing showing | |
878 | all subdirectories at all levels. | |
879 | ||
e01a5bb5 RS |
880 | More often, you will want to show only specific subdirectories. You |
881 | can do this with the @kbd{i} command: | |
6bf7aab6 DL |
882 | |
883 | @table @kbd | |
884 | @findex dired-maybe-insert-subdir | |
885 | @kindex i @r{(Dired)} | |
886 | @item i | |
887 | @cindex inserted subdirectory (Dired) | |
888 | @cindex in-situ subdirectory (Dired) | |
889 | Insert the contents of a subdirectory later in the buffer. | |
890 | @end table | |
891 | ||
892 | Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line | |
893 | that describes a file which is a directory. It inserts the contents of | |
894 | that directory into the same Dired buffer, and moves there. Inserted | |
895 | subdirectory contents follow the top-level directory of the Dired | |
896 | buffer, just as they do in @samp{ls -lR} output. | |
897 | ||
898 | If the subdirectory's contents are already present in the buffer, the | |
899 | @kbd{i} command just moves to it. | |
900 | ||
901 | In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u | |
902 | C-@key{SPC}} takes you back to the old position in the buffer (the line | |
903 | describing that subdirectory). | |
904 | ||
905 | Use the @kbd{l} command (@code{dired-do-redisplay}) to update the | |
38458147 EZ |
906 | subdirectory's contents. Use @kbd{C-u k} on the subdirectory header |
907 | line to delete the subdirectory. @xref{Dired Updating}. | |
6bf7aab6 DL |
908 | |
909 | @node Subdirectory Motion | |
910 | @section Moving Over Subdirectories | |
911 | ||
912 | When a Dired buffer lists subdirectories, you can use the page motion | |
5942fb80 RS |
913 | commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories |
914 | (@pxref{Pages}). | |
6bf7aab6 DL |
915 | |
916 | @cindex header line (Dired) | |
917 | @cindex directory header lines | |
918 | The following commands move across, up and down in the tree of | |
919 | directories within one Dired buffer. They move to @dfn{directory header | |
920 | lines}, which are the lines that give a directory's name, at the | |
921 | beginning of the directory's contents. | |
922 | ||
923 | @table @kbd | |
924 | @findex dired-next-subdir | |
925 | @kindex C-M-n @r{(Dired)} | |
926 | @item C-M-n | |
927 | Go to next subdirectory header line, regardless of level | |
928 | (@code{dired-next-subdir}). | |
929 | ||
930 | @findex dired-prev-subdir | |
931 | @kindex C-M-p @r{(Dired)} | |
932 | @item C-M-p | |
933 | Go to previous subdirectory header line, regardless of level | |
934 | (@code{dired-prev-subdir}). | |
935 | ||
936 | @findex dired-tree-up | |
937 | @kindex C-M-u @r{(Dired)} | |
938 | @item C-M-u | |
939 | Go up to the parent directory's header line (@code{dired-tree-up}). | |
940 | ||
941 | @findex dired-tree-down | |
942 | @kindex C-M-d @r{(Dired)} | |
943 | @item C-M-d | |
944 | Go down in the directory tree, to the first subdirectory's header line | |
945 | (@code{dired-tree-down}). | |
946 | ||
947 | @findex dired-prev-dirline | |
948 | @kindex < @r{(Dired)} | |
949 | @item < | |
950 | Move up to the previous directory-file line (@code{dired-prev-dirline}). | |
951 | These lines are the ones that describe a directory as a file in its | |
952 | parent directory. | |
953 | ||
954 | @findex dired-next-dirline | |
955 | @kindex > @r{(Dired)} | |
956 | @item > | |
957 | Move down to the next directory-file line (@code{dired-prev-dirline}). | |
958 | @end table | |
959 | ||
960 | @node Hiding Subdirectories | |
961 | @section Hiding Subdirectories | |
962 | ||
963 | @cindex hiding in Dired (Dired) | |
964 | @dfn{Hiding} a subdirectory means to make it invisible, except for its | |
e01a5bb5 | 965 | header line. |
6bf7aab6 DL |
966 | |
967 | @table @kbd | |
968 | @item $ | |
969 | @findex dired-hide-subdir | |
970 | @kindex $ @r{(Dired)} | |
971 | Hide or reveal the subdirectory that point is in, and move point to the | |
972 | next subdirectory (@code{dired-hide-subdir}). A numeric argument serves | |
973 | as a repeat count. | |
974 | ||
975 | @item M-$ | |
976 | @findex dired-hide-all | |
977 | @kindex M-$ @r{(Dired)} | |
978 | Hide all subdirectories in this Dired buffer, leaving only their header | |
979 | lines (@code{dired-hide-all}). Or, if any subdirectory is currently | |
980 | hidden, make all subdirectories visible again. You can use this command | |
981 | to get an overview in very deep directory trees or to move quickly to | |
982 | subdirectories far away. | |
983 | @end table | |
984 | ||
985 | Ordinary Dired commands never consider files inside a hidden | |
986 | subdirectory. For example, the commands to operate on marked files | |
987 | ignore files in hidden directories even if they are marked. Thus you | |
988 | can use hiding to temporarily exclude subdirectories from operations | |
e01a5bb5 RS |
989 | without having to remove the Dired marks on files in those |
990 | subdirectories. | |
6bf7aab6 | 991 | |
6bf7aab6 DL |
992 | @node Dired Updating |
993 | @section Updating the Dired Buffer | |
a33b10b5 EZ |
994 | @cindex updating Dired buffer |
995 | @cindex refreshing displayed files | |
6bf7aab6 DL |
996 | |
997 | This section describes commands to update the Dired buffer to reflect | |
998 | outside (non-Dired) changes in the directories and files, and to delete | |
999 | part of the Dired buffer. | |
1000 | ||
1001 | @table @kbd | |
1002 | @item g | |
1003 | Update the entire contents of the Dired buffer (@code{revert-buffer}). | |
1004 | ||
1005 | @item l | |
e01a5bb5 RS |
1006 | Update the specified files (@code{dired-do-redisplay}). You specify the |
1007 | files for @kbd{l} in the same way as for file operations. | |
6bf7aab6 DL |
1008 | |
1009 | @item k | |
1010 | Delete the specified @emph{file lines}---not the files, just the lines | |
1011 | (@code{dired-do-kill-lines}). | |
1012 | ||
1013 | @item s | |
1014 | Toggle between alphabetical order and date/time order | |
1015 | (@code{dired-sort-toggle-or-edit}). | |
1016 | ||
1017 | @item C-u s @var{switches} @key{RET} | |
1018 | Refresh the Dired buffer using @var{switches} as | |
1019 | @code{dired-listing-switches}. | |
1020 | @end table | |
1021 | ||
1022 | @kindex g @r{(Dired)} | |
1023 | @findex revert-buffer @r{(Dired)} | |
1024 | Type @kbd{g} (@code{revert-buffer}) to update the contents of the | |
1025 | Dired buffer, based on changes in the files and directories listed. | |
1026 | This preserves all marks except for those on files that have vanished. | |
1027 | Hidden subdirectories are updated but remain hidden. | |
1028 | ||
1029 | @kindex l @r{(Dired)} | |
1030 | @findex dired-do-redisplay | |
1031 | To update only some of the files, type @kbd{l} | |
5942fb80 RS |
1032 | (@code{dired-do-redisplay}). Like the Dired file-operating commands, |
1033 | this command operates on the next @var{n} files (or previous | |
1034 | @minus{}@var{n} files), or on the marked files if any, or on the | |
1035 | current file. Updating the files means reading their current status, | |
1036 | then updating their lines in the buffer to indicate that status. | |
6bf7aab6 DL |
1037 | |
1038 | If you use @kbd{l} on a subdirectory header line, it updates the | |
1039 | contents of the corresponding subdirectory. | |
1040 | ||
1041 | @kindex k @r{(Dired)} | |
1042 | @findex dired-do-kill-lines | |
5942fb80 RS |
1043 | To delete the specified @emph{file lines} from the buffer---not |
1044 | delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like | |
1045 | the file-operating commands, this command operates on the next @var{n} | |
1046 | files, or on the marked files if any; but it does not operate on the | |
1047 | current file as a last resort. | |
6bf7aab6 | 1048 | |
35d9c1cc LT |
1049 | If you use @kbd{k} with a numeric prefix argument to kill the line |
1050 | for a file that is a directory, which you have inserted in the Dired | |
e01a5bb5 RS |
1051 | buffer as a subdirectory, it deletes that subdirectory from the buffer |
1052 | as well. Typing @kbd{C-u k} on the header line for a subdirectory | |
1053 | also deletes the subdirectory from the Dired buffer. | |
6bf7aab6 DL |
1054 | |
1055 | The @kbd{g} command brings back any individual lines that you have | |
1056 | killed in this way, but not subdirectories---you must use @kbd{i} to | |
5942fb80 | 1057 | reinsert a subdirectory. |
6bf7aab6 DL |
1058 | |
1059 | @cindex Dired sorting | |
1060 | @cindex sorting Dired buffer | |
1061 | @kindex s @r{(Dired)} | |
1062 | @findex dired-sort-toggle-or-edit | |
1063 | The files in a Dired buffers are normally listed in alphabetical order | |
1064 | by file names. Alternatively Dired can sort them by date/time. The | |
1065 | Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches | |
1066 | between these two sorting modes. The mode line in a Dired buffer | |
1067 | indicates which way it is currently sorted---by name, or by date. | |
1068 | ||
1069 | @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for | |
1070 | @code{dired-listing-switches}. | |
1071 | ||
1072 | @node Dired and Find | |
1073 | @section Dired and @code{find} | |
1074 | @cindex @code{find} and Dired | |
1075 | ||
1076 | You can select a set of files for display in a Dired buffer more | |
1077 | flexibly by using the @code{find} utility to choose the files. | |
1078 | ||
1079 | @findex find-name-dired | |
1080 | To search for files with names matching a wildcard pattern use | |
1081 | @kbd{M-x find-name-dired}. It reads arguments @var{directory} and | |
1082 | @var{pattern}, and chooses all the files in @var{directory} or its | |
1083 | subdirectories whose individual names match @var{pattern}. | |
1084 | ||
e01a5bb5 | 1085 | The files thus chosen are displayed in a Dired buffer, in which the |
6bf7aab6 DL |
1086 | ordinary Dired commands are available. |
1087 | ||
1088 | @findex find-grep-dired | |
1089 | If you want to test the contents of files, rather than their names, | |
1090 | use @kbd{M-x find-grep-dired}. This command reads two minibuffer | |
1091 | arguments, @var{directory} and @var{regexp}; it chooses all the files in | |
1092 | @var{directory} or its subdirectories that contain a match for | |
1093 | @var{regexp}. It works by running the programs @code{find} and | |
6ac064d6 | 1094 | @code{grep}. See also @kbd{M-x grep-find}, in @ref{Grep Searching}. |
6bf7aab6 | 1095 | Remember to write the regular expression for @code{grep}, not for Emacs. |
a33b10b5 EZ |
1096 | (An alternative method of showing files whose contents match a given |
1097 | regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.) | |
6bf7aab6 DL |
1098 | |
1099 | @findex find-dired | |
1100 | The most general command in this series is @kbd{M-x find-dired}, which | |
1101 | lets you specify any condition that @code{find} can test. It takes two | |
1102 | minibuffer arguments, @var{directory} and @var{find-args}; it runs | |
1103 | @code{find} in @var{directory}, passing @var{find-args} to tell | |
1104 | @code{find} what condition to test. To use this command, you need to | |
1105 | know how to use @code{find}. | |
1106 | ||
c3ecd445 LT |
1107 | @vindex find-ls-option |
1108 | The format of listing produced by these commands is controlled by the | |
1109 | variable @code{find-ls-option}, whose default value specifies using | |
1110 | options @samp{-ld} for @code{ls}. If your listings are corrupted, you | |
1111 | may need to change the value of this variable. | |
1112 | ||
a8ef67ae RS |
1113 | @findex locate |
1114 | @findex locate-with-filter | |
1115 | @cindex file database (locate) | |
1116 | @vindex locate-command | |
3a2aa1dc | 1117 | @kbd{M-x locate} provides a similar interface to the @code{locate} |
e01a5bb5 RS |
1118 | program. @kbd{M-x locate-with-filter} is similar, but keeps only files |
1119 | whose names match a given regular expression. | |
a8ef67ae | 1120 | |
e01a5bb5 | 1121 | These buffers don't work entirely like ordinary Dired buffers: file |
910dc292 LT |
1122 | operations work, but do not always automatically update the buffer. |
1123 | Reverting the buffer with @kbd{g} deletes all inserted subdirectories, | |
1124 | and erases all flags and marks. | |
1125 | ||
9ae7d7af RS |
1126 | @node Wdired |
1127 | @section Editing the Dired Buffer | |
1128 | ||
1129 | @cindex wdired mode | |
1130 | @findex wdired-change-to-wdired-mode | |
1131 | Wdired is a special mode that allows you to perform file operations | |
1132 | by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands | |
1133 | for ``writable''.) To enter Wdired mode, type @kbd{M-x | |
1134 | wdired-change-to-wdired-mode} while in a Dired buffer. Alternatively, | |
1135 | use @samp{Edit File Names} in the @samp{Immediate} menu bar menu. | |
1136 | ||
1137 | @findex wdired-finish-edit | |
1138 | While in Wdired mode, you can rename files by editing the file names | |
1139 | displayed in the Dired buffer. All the ordinary Emacs editing | |
1140 | commands, including rectangle operations and @code{query-replace}, are | |
1141 | available for this. Once you are done editing, type @kbd{C-c C-c} | |
1142 | (@code{wdired-finish-edit}). This applies your changes and switches | |
1143 | back to ordinary Dired mode. | |
1144 | ||
1145 | Apart from simply renaming files, you can move a file to another | |
1146 | directory by typing in the new file name (either absolute or | |
1147 | relative). To mark a file for deletion, delete the entire filename. | |
e01a5bb5 RS |
1148 | To change the target of a symbolic link, edit the link target name |
1149 | which appears next to the link name. | |
9ae7d7af RS |
1150 | |
1151 | The rest of the text in the buffer, such as the file sizes and | |
1152 | modification dates, is marked read-only, so you can't edit it. | |
1153 | However, if you set @code{wdired-allow-to-change-permissions} to | |
e01a5bb5 RS |
1154 | @code{t}, you can edit the file permissions. For example, you can |
1155 | change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file | |
9ae7d7af RS |
1156 | world-writable. These changes also take effect when you type @kbd{C-c |
1157 | C-c}. | |
1158 | ||
67bca9b2 RS |
1159 | @node Misc Dired Features |
1160 | @section Other Dired Features | |
9eae419d | 1161 | |
e01a5bb5 RS |
1162 | @kindex + @r{(Dired)} |
1163 | @findex dired-create-directory | |
1164 | An unusual Dired file-operation command is @kbd{+} | |
1165 | (@code{dired-create-directory}). This command reads a directory name, | |
1166 | and creates the directory if it does not already exist. | |
1167 | ||
9eae419d | 1168 | @cindex Adding to the kill ring in Dired. |
27437d8b | 1169 | @kindex w @r{(Dired)} |
9eae419d | 1170 | @findex dired-copy-filename-as-kill |
67bca9b2 | 1171 | The @kbd{w} command (@code{dired-copy-filename-as-kill}) puts the |
9eae419d | 1172 | names of the marked (or next @var{n}) files into the kill ring, as if |
105fa3fb | 1173 | you had killed them with @kbd{C-w}. The names are separated by a space. |
67bca9b2 | 1174 | |
e01a5bb5 RS |
1175 | With a zero prefix argument, this uses the absolute file name of |
1176 | each marked file. With just @kbd{C-u} as the prefix argument, it uses | |
1177 | file names relative to the Dired buffer's default directory. (This | |
1178 | can still contain slashes if in a subdirectory.) As a special case, | |
1179 | if point is on a directory headerline, @kbd{w} gives you the absolute | |
1180 | name of that directory. Any prefix argument or marked files are | |
1181 | ignored in this case. | |
1182 | ||
67bca9b2 RS |
1183 | The main purpose of this command is so that you can yank the file |
1184 | names into arguments for other Emacs commands. It also displays what | |
e01a5bb5 RS |
1185 | it added to the kill ring, so you can use it to display the list of |
1186 | currently marked files in the echo area. | |
67bca9b2 | 1187 | |
ea3b47e3 RS |
1188 | @findex dired-compare-directories |
1189 | The command @kbd{M-x dired-compare-directories} is used to compare | |
1190 | the current Dired buffer with another directory. It marks all the files | |
1191 | that are ``different'' between the two directories. It puts these marks | |
1192 | in all Dired buffers where these files are listed, which of course includes | |
1193 | the current buffer. | |
1194 | ||
1195 | The default comparison method (used if you type @key{RET} at the | |
1196 | prompt) is to compare just the file names---each file name that does | |
1197 | not appear in the other directory is ``different''. You can specify | |
1198 | more stringent comparisons by entering a Lisp expression, which can | |
1199 | refer to the variables @code{size1} and @code{size2}, the respective | |
1200 | file sizes; @code{mtime1} and @code{mtime2}, the last modification | |
1201 | times in seconds, as floating point numers; and @code{fa1} and | |
1202 | @code{fa2}, the respective file attribute lists (as returned by the | |
1203 | function @code{file-attributes}). This expression is evaluated for | |
1204 | each pair of like-named files, and if the expression's value is | |
1205 | non-@code{nil}, those files are considered ``different''. | |
1206 | ||
1207 | For instance, @code{M-x dired-compare-directories @key{RET} (> | |
1208 | mtime1 mtime2) @key{RET}} marks files newer in this directory than in | |
1209 | the other, and marks files older in the other directory than in this | |
1210 | one. It also marks files with no counterpart, in both directories, as | |
1211 | always. | |
1212 | ||
1213 | @cindex drag and drop, Dired | |
67bca9b2 RS |
1214 | On the X window system, Emacs supports the ``drag and drop'' |
1215 | protocol. You can drag a file object from another program, and drop | |
1216 | it onto a Dired buffer; this either moves, copies, or creates a link | |
1217 | to the file in that directory. Precisely which action is taken is | |
1218 | determined by the originating program. Dragging files out of a Dired | |
1219 | buffer is currently not supported. | |
9eae419d | 1220 | |
ab5796a9 MB |
1221 | @ignore |
1222 | arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1 | |
1223 | @end ignore |