Dired makes an Emacs buffer containing a listing of a directory, and
optionally some of its subdirectories as well. You can use the normal
-Emacs commands to move around in this buffer, and special Dired commands
-to operate on the files listed.
+Emacs commands to move around in this buffer, and special Dired
+commands to operate on the listed files.
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 redefined 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. You first mark certain files in order to operate
-on all of them with on command.
+allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are
+redefined 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. You first mark certain files in order to operate on all of
+them with one command.
The Dired-X package provides various extra features for Dired mode.
@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
+ You can also view a list of files in a directory with @kbd{C-x C-d}
+(@code{list-directory}). Unlike Dired, this command does not allow
+you to operate on the listed files. @xref{Directories}.
+
@menu
* Enter: Dired Enter. How to invoke Dired.
* Navigation: Dired Navigation. Special motion commands in the Dired buffer.
@findex dired
@kindex C-x d
@vindex dired-listing-switches
- To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command
-reads a directory name or wildcard file name pattern as a minibuffer
-argument to specify the files to list. @kbd{C-x C-f} given a
-directory name also invokes Dired. Where @code{dired} differs from
-@code{list-directory} is that it puts the buffer into Dired mode, so
-that the special commands of Dired are available.
+ To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a
+directory name using the minibuffer, and opens a @dfn{Dired buffer}
+listing the files in that directory. You can also supply a wildcard
+file name pattern as the minibuffer argument, in which case the Dired
+buffer lists all files matching that pattern. The usual history and
+completion commands can be used in the minibuffer; in particular,
+@kbd{M-n} puts the name of the visited file (if any) in the minibuffer
+(@pxref{Minibuffer History}).
+
+ You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file})
+a directory name.
The variable @code{dired-listing-switches} specifies the options to
give to @code{ls} for listing the directory; this string @emph{must}
On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls};
see @ref{ls in Lisp}, for options and peculiarities of that emulation.
-
@findex dired-other-window
@kindex C-x 4 d
@findex dired-other-frame
@kindex SPC @r{(Dired)}
For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
-to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is
-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.
+to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines
+is so common in Dired that it deserves to be easy to type.) @key{DEL}
+(move up and unflag) is also often useful simply for moving up
+(@pxref{Dired Deletion}).
@findex dired-goto-file
@kindex j @r{(Dired)}
- @kbd{j} (@code{dired-goto-file}) moves point to the line that
-describes a specified file or directory.
+ @kbd{j} (@code{dired-goto-file}) prompts for a file name using the
+minibuffer, and moves point to the line in the Dired buffer describing
+that file.
+
+@cindex searching Dired buffers
+@vindex dired-isearch-filenames
+ @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward
+incremental search in the Dired buffer, looking for matches only
+amongst the file names and ignoring the rest of the text in the
+buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp})
+does the same, using a regular expression search. If you change the
+variable @var{dired-isearch-filenames} to non-@code{nil}, then the
+usual search commands also limit themselves to the file names; for
+instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. @xref{Search}, for
+information about incremental search.
Some additional navigation commands are available when the Dired
buffer includes several directories. @xref{Subdirectory Motion}.
@kindex x @r{(Dired)}
@findex dired-do-flagged-delete
-@cindex expunging (Dired)
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 of the Dired buffer. The Dired buffer, with
-somewhat fewer lines, remains selected.
+(@code{dired-do-flagged-delete}). 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 of the Dired buffer. The Dired
+buffer, with somewhat fewer lines, remains selected.
If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
return immediately to Dired, with the deletion flags still present in
@section Flagging Many Files at Once
@cindex flagging many files for deletion (in Dired)
+ The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands
+flag many files for deletion, based on their file names:
+
@table @kbd
@item #
Flag all auto-save files (files whose names start and end with @samp{#})
Flag all backup files (files whose names end with @samp{~}) for deletion
(@pxref{Backup}).
-@item &
-Flag for deletion all files with certain kinds of names which suggest
-you could easily create those files again.
-
@item .@: @r{(Period)}
Flag excess numeric backup files for deletion. The oldest and newest
few backup files of any one file are exempt; the middle ones are
flagged.
+@item % &
+Flag for deletion all files with certain kinds of names which suggest
+you could easily create those files again.
+
@item % d @var{regexp} @key{RET}
Flag for deletion all files whose names match the regular expression
@var{regexp}.
@end table
- The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for
-deletion, based on their file names. These commands are useful
-precisely because they do not themselves delete any files; you can
-remove the deletion flags from any flagged files that you really wish to
-keep.@refill
-
-@kindex & @r{(Dired)}
-@findex dired-flag-garbage-files
-@vindex dired-garbage-files-regexp
-@cindex deleting some backup files
- @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{}, @samp{.bak} files, and the @samp{.orig} and
-@samp{.rej} files produced by @code{patch}.
-
@kindex # @r{(Dired)}
@findex dired-flag-auto-save-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---that is, files whose
-names begin and end with @samp{#}. @xref{Auto Save}.
+ @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose
+names look like auto-save files---that is, files whose names begin and
+end with @samp{#}. @xref{Auto Save}.
@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---that is, files whose
-names end in @samp{~}. @xref{Backup}.
+ @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names
+say they are backup files---that is, files whose names end in
+@samp{~}. @xref{Backup}.
@kindex . @r{(Dired)}
@vindex dired-kept-versions
@findex dired-clean-directory
- @kbd{.} (period, @code{dired-clean-directory}) flags just some of the
-backup files for deletion: all but the oldest few and newest few backups
-of any one file. Normally @code{dired-kept-versions} (@strong{not}
-@code{kept-new-versions}; that applies only when saving) specifies the
-number of newest versions of each file to keep, and
-@code{kept-old-versions} specifies the number of oldest versions to
-keep.
+ @kbd{.} (period, @code{dired-clean-directory}) flags just some of
+the backup files for deletion: all but the oldest few and newest few
+backups of any one file. Normally, the number of newest versions kept
+for each file is given by the variable @code{dired-kept-versions}
+(@strong{not} @code{kept-new-versions}; that applies only when
+saving). The number of oldest versions to keep is given by the
+variable @code{kept-old-versions}.
Period with a positive numeric argument, as in @kbd{C-u 3 .},
specifies the number of newest versions to keep, overriding
@code{kept-old-versions}, using minus the value of the argument to
specify the number of oldest versions of each file to keep.
+@kindex % & @r{(Dired)}
+@findex dired-flag-garbage-files
+@vindex dired-garbage-files-regexp
+@cindex deleting some backup files
+ @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{}, @samp{.bak} files, and the @samp{.orig} and
+@samp{.rej} files produced by @code{patch}.
+
@findex dired-flag-files-regexp
@kindex % d @r{(Dired)}
- The @kbd{% d} command flags all files whose names match a specified
-regular expression (@code{dired-flag-files-regexp}). Only the
-non-directory part of the file name is used in matching. You can use
-@samp{^} and @samp{$} to anchor matches. You can exclude certain
-subdirectories from marking by hiding them while you use @kbd{% d}.
-@xref{Hiding Subdirectories}.
+ @kbd{% d} flags all files whose names match a specified regular
+expression (@code{dired-flag-files-regexp}). Only the non-directory
+part of the file name is used in matching. You can use @samp{^} and
+@samp{$} to anchor matches. You can exclude certain subdirectories
+from marking by hiding them while you use @kbd{% d}. @xref{Hiding
+Subdirectories}.
@node Dired Visiting
@section Visiting 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 use the files marked with @samp{*}. The
-only command that operates on flagged files is @kbd{x}, which expunges
+only command that operates on flagged files is @kbd{x}, which deletes
them.
Here are some commands for marking with @samp{*}, for unmarking, and
@kindex X @r{(Dired)}
The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a
shell command string in the minibuffer and runs that shell command on
-all the specified files. (@kbd{X} is a synonym for @kbd{!}.) You can
-specify the files to operate on in the usual ways for Dired commands
-(@pxref{Operating on Files}).
+one or more files. The files that the shell command operates on are
+determined in the usual way for Dired commands (@pxref{Operating on
+Files}). The command @kbd{X} is a synonym for @kbd{!}.
- The working directory for the shell command is the top-level directory
-of the Dired buffer.
+ The command @kbd{&} (@code{dired-do-async-shell-command}) does the
+same, except that it runs the shell command asynchronously. You can
+also do this with @kbd{!}, by appending a @samp{&} character to the
+end of the shell command.
- There are two ways of applying a shell command to multiple files:
+ For both @kbd{!} and @kbd{&}, the working directory for the shell
+command is the top-level directory of the Dired buffer.
+
+ If you tell @kbd{!} or @kbd{&} to operate on more than one file, the
+shell command string determines how those files are passed to the
+shell command:
@itemize @bullet
@item
-If you use @samp{*} surrounded by whitespace in the shell command,
+If you use @samp{*} surrounded by whitespace in the command string,
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.
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.
+but since the @samp{*} is not surrounded by whitespace, Dired does not
+treat it specially.
@item
-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.
+Otherwise, if the command string contains @samp{?} surrounded by
+whitespace, Emacs runs the shell command once @emph{for each file},
+substituting the current file name for @samp{?} each time. You can
+use @samp{?} more than once in the command; the same file name
+replaces each occurrence.
@item
-However, if the command string contains @samp{?} surrounded by
-whitespace, the current file name is substituted for @samp{?} (rather
-than added at the end). You can use @samp{?} this way more than once
-in the command, and the same file name replaces each occurrence.
+If the command string contains neither @samp{*} nor @samp{?}, Emacs
+runs the shell command once for each file, adding the file name is
+added at the end. For example, @kbd{! uudecode @key{RET}} runs
+@code{uudecode} on each file.
@end itemize
To iterate over the file names in a more complicated fashion, use an
for file in * ; do uuencode "$file" "$file" >"$file".uu; done
@end example
- The @kbd{!} command does not attempt to update the Dired buffer to
-show new or modified files, because it doesn't understand shell
-commands, and does not know what files the shell command changed. Use
-the @kbd{g} command to update the Dired buffer (@pxref{Dired
-Updating}).
+ The @kbd{!} and @kbd{&} commands do not attempt to update the Dired
+buffer to show new or modified files, because they don't know what
+files will be changed. Use the @kbd{g} command to update the Dired
+buffer (@pxref{Dired Updating}).
+
+ @xref{Single Shell}, for information about running shell commands
+outside Dired.
@node Transforming File Names
@section Transforming File Names in Dired
line to delete the subdirectory (@pxref{Dired Updating}). You can also
hide and show inserted subdirectories (@pxref{Hiding Subdirectories}).
-
-
-
@ifnottex
@include dired-xtra.texi
@end ifnottex
@cindex @code{find} and Dired
You can select a set of files for display in a Dired buffer more
-flexibly by using the @code{find} utility to choose the files.
+flexibly by using the @command{find} utility to choose the files.
@findex find-name-dired
To search for files with names matching a wildcard pattern use
@findex find-grep-dired
If you want to test the contents of files, rather than their names,
use @kbd{M-x find-grep-dired}. This command reads two minibuffer
-arguments, @var{directory} and @var{regexp}; it chooses all the files in
-@var{directory} or its subdirectories that contain a match for
-@var{regexp}. It works by running the programs @code{find} and
-@code{grep}. See also @kbd{M-x grep-find}, in @ref{Grep Searching}.
-Remember to write the regular expression for @code{grep}, not for Emacs.
-(An alternative method of showing files whose contents match a given
-regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.)
+arguments, @var{directory} and @var{regexp}; it chooses all the files
+in @var{directory} or its subdirectories that contain a match for
+@var{regexp}. It works by running the programs @command{find} and
+@command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep
+Searching}. Remember to write the regular expression for
+@command{grep}, not for Emacs. (An alternative method of showing
+files whose contents match a given regexp is the @kbd{% g
+@var{regexp}} command, see @ref{Marks vs Flags}.)
@findex find-dired
- The most general command in this series is @kbd{M-x find-dired}, which
-lets you specify any condition that @code{find} can test. It takes two
-minibuffer arguments, @var{directory} and @var{find-args}; it runs
-@code{find} in @var{directory}, passing @var{find-args} to tell
-@code{find} what condition to test. To use this command, you need to
-know how to use @code{find}.
+ The most general command in this series is @kbd{M-x find-dired},
+which lets you specify any condition that @command{find} can test. It
+takes two minibuffer arguments, @var{directory} and @var{find-args};
+it runs @command{find} in @var{directory}, passing @var{find-args} to
+tell @command{find} what condition to test. To use this command, you
+need to know how to use @command{find}.
@vindex find-ls-option
The format of listing produced by these commands is controlled by the
@cindex file database (locate)
@vindex locate-command
The command @kbd{M-x locate} provides a similar interface to the
-@code{locate} program. @kbd{M-x locate-with-filter} is similar, but
+@command{locate} program. @kbd{M-x locate-with-filter} is similar, but
keeps only files whose names match a given regular expression.
These buffers don't work entirely like ordinary Dired buffers: file
@findex wdired-change-to-wdired-mode
Wdired is a special mode that allows you to perform file operations
by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands
-for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} or @kbd{M-x
-wdired-change-to-wdired-mode} while in a Dired buffer. Alternatively,
-use @samp{Edit File Names} in the @samp{Immediate} menu bar menu.
+for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q}
+(@code{dired-toggle-read-only}) while in a Dired buffer.
+Alternatively, use the @samp{Immediate / Edit File Names} menu item.
@findex wdired-finish-edit
While in Wdired mode, you can rename files by editing the file names
@kindex + @r{(Dired)}
@findex dired-create-directory
- An unusual Dired file-operation command is @kbd{+}
-(@code{dired-create-directory}). This command reads a directory name,
-and creates the directory if it does not already exist.
+ The command @kbd{+} (@code{dired-create-directory}) reads a
+directory name, and creates the directory if it does not already
+exist.
+
+@cindex searching multiple files via Dired
+ The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a
+``multi-file'' incremental search on the marked files. If a search
+fails at the end of a file, typing @kbd{C-s} advances to the next
+marked file and repeats the search; at the end of the last marked
+file, the search wraps around to the first marked file. The command
+@kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with
+a regular expression search. @xref{Repeat Isearch}, for information
+about search repetition.
@cindex Adding to the kill ring in Dired.
@kindex w @r{(Dired)}
@findex dired-copy-filename-as-kill
- The @kbd{w} command (@code{dired-copy-filename-as-kill}) puts the
+ The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the
names of the marked (or next @var{n}) files into the kill ring, as if
-you had killed them with @kbd{C-w}. The names are separated by a space.
+you had killed them with @kbd{C-w}. The names are separated by a
+space.
With a zero prefix argument, this uses the absolute file name of
each marked file. With just @kbd{C-u} as the prefix argument, it uses
projects / emacs.git / commitdiff