@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
+@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Dired, Calendar/Diary, Rmail, Top
Emacs commands to move around in this buffer, and special Dired commands
to operate on the files listed.
+ The Dired buffer is ``read-only,'' and inserting text in it is not
+useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are
+used for special Dired commands. Some Dired commands @dfn{mark} or
+@dfn{flag} the @dfn{current file} (that is, the file on the current
+line); other commands operate on the marked files or on the flagged
+files.
+
The Dired-X package provides various extra features for Dired mode.
-@xref{,Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
+@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
@menu
* Enter: Dired Enter. How to invoke Dired.
-* Commands: Dired Commands. Commands in the Dired buffer.
+* Navigation: Dired Navigation. Special motion commands in the Dired buffer.
* Deletion: Dired Deletion. Deleting files with Dired.
* Flagging Many Files:: Flagging files based on their names.
* Visit: Dired Visiting. Other file operations through Dired.
of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
separate frame to display the Dired buffer.
-@node Dired Commands
-@section Commands in the Dired Buffer
-
- The Dired buffer is ``read-only,'' and inserting text in it is not
-useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are
-used for special Dired commands. Some Dired commands @dfn{mark} or
-@dfn{flag} the @dfn{current file} (that is, the file on the current
-line); other commands operate on the marked files or on the flagged
-files.
+@node Dired Navigation
+@section Navigation in the Dired Buffer
@kindex C-n @r{(Dired)}
@kindex C-p @r{(Dired)}
so common in Dired that it deserves to be easy to type.) @key{DEL}
(move up and unflag) is often useful simply for moving up.
+ Some additional navigation commands are available when the Dired
+buffer includes several directories. @xref{Subdirectory Motion}.
+
@node Dired Deletion
@section Deleting Files with Dired
@cindex flagging files (in Dired)
@cindex deleting files (in Dired)
- The primary use of Dired is to @dfn{flag} files for deletion and then
-delete the files previously flagged.
+ One of the most frequent uses of Dired is to first @dfn{flag} files for
+deletion, then delete the files that were flagged.
@table @kbd
@item d
so that repeated @kbd{d} commands flag successive files. A numeric
argument serves as a repeat count.
+@cindex recursive deletion
@vindex dired-recursive-deletes
The variable @code{dired-recursive-deletes} controls whether the
delete command will delete non-empty directories (including their
@kindex DEL @r{(Dired)}
The files are flagged for deletion rather than deleted immediately to
reduce the danger of deleting a file accidentally. Until you direct
-Dired to expunge the flagged files, you can remove deletion flags using
+Dired to delete the flagged files, you can remove deletion flags using
the commands @kbd{u} and @key{DEL}. @kbd{u} (@code{dired-unmark}) works
just like @kbd{d}, but removes flags rather than making flags.
@key{DEL} (@code{dired-unmark-backward}) moves upward, removing flags;
it is like @kbd{u} with argument @minus{}1.
@kindex x @r{(Dired)}
-@findex dired-expunge
+@findex dired-do-flagged-delete
@cindex expunging (Dired)
- To delete the flagged files, type @kbd{x} (@code{dired-expunge}).
+ To delete the flagged files, type @kbd{x} (@code{dired-do-flagged-delete}).
+(This is also known as @dfn{expunging}.)
This command first displays a list of all the file names flagged for
deletion, and requests confirmation with @kbd{yes}. If you confirm,
Dired deletes the flagged files, then deletes their lines from the text
@kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
match the regular expression specified by the variable
@code{dired-garbage-files-regexp}. By default, this matches certain
-files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files
-produced by @code{patch}.
+files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and
+@samp{.rej} files produced by @code{patch}.
@kindex # @r{(Dired)}
-@kindex ~ @r{(Dired)}
@findex dired-flag-auto-save-files
-@findex dired-flag-backup-files
@cindex deleting auto-save files
@kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all
files whose names look like auto-save files (@pxref{Auto Save})---that
-is, files whose names begin and end with @samp{#}. @kbd{~}
-(@code{dired-flag-backup-files}) flags for deletion all files whose
-names say they are backup files (@pxref{Backup})---that is, whose names
-end in @samp{~}.
+is, files whose names begin and end with @samp{#}.
+
+@kindex ~ @r{(Dired)}
+@findex dired-flag-backup-files
+ @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all files
+whose names say they are backup files (@pxref{Backup})---that is, files
+whose names end in @samp{~}.
@kindex . @r{(Dired)}
@vindex dired-kept-versions
and supplying that file name (@code{dired-find-file}). @xref{Visiting}.
@item @key{RET}
+@itemx e
@kindex RET @r{(Dired)}
+@kindex e @r{(Dired)}
Equivalent to @kbd{f}.
@item a
@item v
@kindex v @r{(Dired)}
@findex dired-view-file
-View the file described on the current line, using @kbd{M-x view-file}
-(@code{dired-view-file}).
-
-Viewing a file is like visiting it, but is slanted toward moving around
-in the file conveniently and does not allow changing the file.
-@xref{Misc File Ops,View File}.
+View the file described on the current line, using either an external
+viewing program or @kbd{M-x view-file} (@code{dired-view-file}).
+
+@vindex dired-view-command-alist
+External viewers are used for certain file types under the control of
+@code{dired-view-command-alist}. Viewing a file with @code{view-file}
+is like visiting it, but is slanted toward moving around in the file
+conveniently and does not allow changing the file. @xref{Misc File
+Ops,View File, Miscellaneous File Operations}.
+
+@item ^
+@kindex ^ @r{(Dired)}
+@findex dired-up-directory
+Visit the parent directory of the current directory
+(@code{dired-up-directory}). This is more convenient than moving to
+the parent directory's line and typing @kbd{f} there.
@end table
@node Marks vs Flags
@section Dired Marks vs. Flags
@cindex marking many files (in Dired)
- Instead of flagging a file with @samp{D}, you can @dfn{mark} the file
-with some other character (usually @samp{*}). Most Dired commands to
-operate on files, aside from ``expunge'' (@kbd{x}), look for files
-marked with @samp{*}.
+ Instead of flagging a file with @samp{D}, you can @dfn{mark} the
+file with some other character (usually @samp{*}). Most Dired
+commands to operate on files use the files marked with @samp{*}, the
+exception being @kbd{x} which deletes the flagged files.
Here are some commands for marking with @samp{*}, or for unmarking or
operating on marks. (@xref{Dired Deletion}, for commands to flag and
@item * !
@kindex * ! @r{(Dired)}
-@findex dired-unmark-all-files-no-query
+@findex dired-unmark-all-marks
Remove all marks from all the files in this Dired buffer
-(@code{dired-unmark-all-files-no-query}).
+(@code{dired-unmark-all-marks}).
@item * ? @var{markchar}
@kindex * ? @r{(Dired)}
Remove all marks that use the character @var{markchar}
(@code{dired-unmark-all-files}). The argument is a single
character---do not use @key{RET} to terminate it. See the description
-of the @kbd{* c} command below, which lets you change the character that
-marks files.
+of the @kbd{* c} command below, which lets you replace one mark
+character with another.
With a numeric argument, this command queries about each marked file,
asking whether to remove its mark. You can answer @kbd{y} meaning yes,
@item * t
@kindex * t @r{(Dired)}
-@findex dired-do-toggle
+@findex dired-toggle-marks
@cindex toggling marks (in Dired)
-Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*}
+Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*}
become unmarked, and unmarked files are marked with @samp{*}. Files
marked in any other way are not affected.
* c D t * c SPC D * c t SPC
@end example
-This assumes that no files are marked with @samp{t}.
+This assumes that no files were already marked with @samp{t}.
@item % m @var{regexp} @key{RET}
@itemx * % @var{regexp} @key{RET}
@kindex C-_ @r{(Dired)}
@findex dired-undo
Undo changes in the Dired buffer, such as adding or removing
-marks (@code{dired-undo}).
+marks (@code{dired-undo}). @emph{This command does not revert the
+actual file operations, nor recover lost files!} It just undoes
+changes in the buffer itself. For example, if used after renaming one
+or more files, @code{dired-undo} restores the original names, which
+will get the Dired buffer out of sync with the actual contents of the
+directory.
@end table
@node Operating on Files
Otherwise, the command operates on the current file only.
@end itemize
+@vindex dired-dwim-target
+@cindex two directories (in Dired)
+ Commands which ask for a destination directory, such as those which
+copy and rename files or create links for them, try to guess the default
+target directory for the operation. Normally, they suggest the Dired
+buffer's default directory, but if the variable @code{dired-dwim-target}
+is non-@code{nil}, and if there is another Dired buffer displayed in the
+next window, that other buffer's directory is suggested instead.
+
Here are the file-manipulating commands that operate on files in this
way. (Some other Dired commands, such as @kbd{!} and the @samp{%}
commands, also use these conventions to decide which files to work on.)
as that of the old file.
@vindex dired-recursive-copies
+@cindex recursive copying
The variable @code{dired-recursive-copies} controls whether
directories are copied recursively. The default is to not copy
recursively, which means that directories cannot be copied.
Delete the specified files (@code{dired-do-delete}). Like the other
commands in this section, this command operates on the @emph{marked}
files, or the next @var{n} files. By contrast, @kbd{x}
-(@code{dired-expunge}) deletes all @dfn{flagged} files.
+(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files.
@findex dired-do-rename
@kindex R @r{(Dired)}
the next match. @xref{Tags Search}.
@kindex Q @r{(Dired)}
-@findex dired-do-query-replace
+@findex dired-do-query-replace-regexp
@cindex search and replace in multiple files (in Dired)
-@item Q @var{from} @key{RET} @var{to} @key{RET}
+@item Q @var{regexp} @key{RET} @var{to} @key{RET}
Perform @code{query-replace-regexp} on each of the specified files,
-replacing matches for @var{from} (a regular expression) with the string
-@var{to} (@code{dired-do-query-replace}).
+replacing matches for @var{regexp} with the string
+@var{to} (@code{dired-do-query-replace-regexp}).
This command is a variant of @code{tags-query-replace}. If you exit the
query replace loop, you can use @kbd{M-,} to resume the scan and replace
@itemize @bullet
@item
-If you use @samp{*} in the shell command, then it runs just once, with
-the list of file names substituted for the @samp{*}. The order of file
-names is the order of appearance in the Dired buffer.
+If you use @samp{*} surrounded by whitespace in the shell command,
+then the command runs just once, with the list of file names
+substituted for the @samp{*}. The order of file names is the order of
+appearance in the Dired buffer.
Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
list of file names, putting them into one tar file @file{foo.tar}.
+If you want to use @samp{*} as a shell wildcard with whitespace around
+it, write @samp{*""}. In the shell, this is equivalent to @samp{*};
+but since the @samp{*} is not surrounded by whitespace, Dired does
+not treat it specially.
+
@item
-If the command string doesn't contain @samp{*}, then it runs once
-@emph{for each file}, with the file name added at the end.
+If the command string doesn't contain @samp{*} surrounded by
+whitespace, then it runs once @emph{for each file}. Normally the file
+name is added at the end.
For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
file.
-@end itemize
-What if you want to run the shell command once for each file, with the
-file name inserted in the middle? You can use @samp{?} in the command
-instead of @samp{*}. The current file name is substituted for
-@samp{?}. You can use @samp{?} more than once. For instance, here is
-how to uuencode each file, making the output file name by appending
-@samp{.uu} to the input file name:
+@item
+If the command string contains @samp{?} surrounded by whitespace, the
+current file name is substituted for @samp{?}. You can use @samp{?}
+this way more than once in the command, and each occurrence is
+replaced. For instance, here is how to uuencode each file, making the
+output file name by appending @samp{.uu} to the input file name:
@example
uuencode ? ? > ?.uu
@end example
+@end itemize
-To use the file names in a more complicated fashion, you can use a
-shell loop. For example, this shell command is another way to
-uuencode each file:
+To iterate over the file names in a more complicated fashion, use an
+explicit shell loop. For example, this shell command is another way
+to uuencode each file:
@example
-for file in *; do uuencode $file $file >$file.uu; done
+for file in * ; do uuencode "$file" "$file" >"$file".uu; done
@end example
+@noindent
+This simple example doesn't require a shell loop (you can do it
+with @samp{?}, but it illustrates the technique.
+
The working directory for the shell command is the top-level directory
of the Dired buffer.
@node Transforming File Names
@section Transforming File Names in Dired
- Here are commands that alter file names in a systematic way:
+ This section describes Dired commands which alter file names in a
+systematic way.
+
+ Like the basic Dired file-manipulation commands (@pxref{Operating on
+Files}), the commands described here operate either on the next
+@var{n} files, or on all files marked with @samp{*}, or on the current
+file. (To mark files, use the commands described in @ref{Marks vs
+Flags}.)
+
+ All of the commands described in this section work
+@emph{interactively}: they ask you to confirm the operation for each
+candidate file. Thus, you can select more files than you actually
+need to operate on (e.g., with a regexp that matches many files), and
+then refine the selection by typing @kbd{y} or @kbd{n} when the
+command prompts for confirmation.
@table @kbd
@findex dired-upcase
Normally, the replacement process does not consider the files'
directory names; it operates on the file name within the directory. If
you specify a numeric argument of zero, then replacement affects the
-entire absolute file name including directory name.
+entire absolute file name including directory name. (Non-zero
+argument specifies the number of files to operate on.)
Often you will want to select the set of files to operate on using the
same @var{regexp} that you will use to operate on them. To do this,
Compare the current file (the file at point) with another file (the file
at the mark) using the @code{diff} program (@code{dired-diff}). The
file at the mark is the first argument of @code{diff}, and the file at
-point is the second argument.
+point is the second argument. Use @kbd{C-@key{SPC}}
+(@code{set-mark-command}) to set the mark at the first file's line
+(@pxref{Setting Mark}), since @code{dired-diff} ignores the files marked
+with the Dired's @kbd{m} command.
@findex dired-backup-diff
@kindex M-= @r{(Dired)}
@section Moving Over Subdirectories
When a Dired buffer lists subdirectories, you can use the page motion
-commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories.
+commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories
+(@pxref{Pages}).
@cindex header line (Dired)
@cindex directory header lines
@kindex l @r{(Dired)}
@findex dired-do-redisplay
To update only some of the files, type @kbd{l}
-(@code{dired-do-redisplay}). This command applies to the next @var{n}
-files, or to the marked files if any, or to the current file. Updating
-them means reading their current status from the file system and
-changing the buffer to reflect it properly.
+(@code{dired-do-redisplay}). Like the Dired file-operating commands,
+this command operates on the next @var{n} files (or previous
+@minus{}@var{n} files), or on the marked files if any, or on the
+current file. Updating the files means reading their current status,
+then updating their lines in the buffer to indicate that status.
If you use @kbd{l} on a subdirectory header line, it updates the
contents of the corresponding subdirectory.
@kindex k @r{(Dired)}
@findex dired-do-kill-lines
- To delete the specified @emph{file lines}---not the files, just the
-lines---type @kbd{k} (@code{dired-do-kill-lines}). With a numeric
-argument @var{n}, this command applies to the next @var{n} files;
-otherwise, it applies to the marked files.
+ To delete the specified @emph{file lines} from the buffer---not
+delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like
+the file-operating commands, this command operates on the next @var{n}
+files, or on the marked files if any; but it does not operate on the
+current file as a last resort.
If you kill the line for a file that is a directory, the directory's
contents are also deleted from the buffer. Typing @kbd{C-u k} on the
The @kbd{g} command brings back any individual lines that you have
killed in this way, but not subdirectories---you must use @kbd{i} to
-reinsert each subdirectory.
+reinsert a subdirectory.
@cindex Dired sorting
@cindex sorting Dired buffer
@findex locate-with-filter
@cindex file database (locate)
@vindex locate-command
- @kbd{M-x locate} provides a similar interface to the @code{locate}.
-@kbd{M-x locate-with-filter} is similar, but keeps only lines matching
-a given regular expression.
+ @kbd{M-x locate} provides a similar interface to the @code{locate}
+program. @kbd{M-x locate-with-filter} is similar, but keeps only lines
+matching a given regular expression.
@vindex find-ls-option
The format of listing produced by these commands is controlled by the