@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Dired, Calendar/Diary, Rmail, Top
@chapter Dired, the Directory Editor
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 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.
+
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.
* Transforming File Names:: Using patterns to rename multiple files.
* Comparison in Dired:: Running `diff' by way of Dired.
* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
+@ifnottex
+* Subdir Switches:: Subdirectory switches in Dired.
+@end ifnottex
* Subdirectory Motion:: Moving across subdirectories, and up and down.
* Hiding Subdirectories:: Making subdirectories visible or invisible.
* Updating: Dired Updating. Discarding lines for files of no interest.
* Find: Dired and Find. Using `find' to choose the files for Dired.
+* Wdired:: Operating on files by editing the Dired buffer.
+* Misc: Misc Dired Features. Various other features.
@end menu
@node Dired Enter
@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 which files to list. Where @code{dired} differs from
-@code{list-directory} is in putting the buffer into Dired mode so that
-the special commands of Dired are available.
+ 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.
The variable @code{dired-listing-switches} specifies the options to
-give to @code{ls} for listing directory; this string @emph{must} contain
-@samp{-l}. If you use a numeric prefix argument with the @code{dired}
-command, you can specify the @code{ls} switches with the minibuffer
-before you enter the directory specification.
+give to @code{ls} for listing the directory; this string @emph{must}
+contain @samp{-l}. If you use a numeric prefix argument with the
+@code{dired} command, you can specify the @code{ls} switches with the
+minibuffer before you enter the directory specification. No matter
+how they are specified, the @code{ls} switches can include short
+options (that is, single characters) requiring no arguments, and long
+options (starting with @samp{--}) whose arguments are specified with
+@samp{=}.
@findex dired-other-window
@kindex C-x 4 d
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)}
All the usual Emacs cursor motion commands are available in Dired
-buffers. Some special-purpose cursor motion commands are also
-provided. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
-cursor at the beginning of the file name on the line, rather than at the
-beginning of the line.
+buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
+cursor at the beginning of the file name on the line, rather than at
+the beginning of the line.
@kindex SPC @r{(Dired)}
For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
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.
+@findex dired-goto-file
+@kindex M-g @r{(Dired)}
+ @kbd{M-g} (@code{dired-goto-file}) moves point to the line that
+describes a specified file or directory.
+
+ 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
@kindex d @r{(Dired)}
@findex dired-flag-file-deletion
- You can flag a file for deletion by moving to the line describing the
-file and typing @kbd{d} (@code{dired-flag-file-deletion}). The deletion flag is visible as a @samp{D} at
-the beginning of the line. This command moves point to the next line,
-so that repeated @kbd{d} commands flag successive files. A numeric
-argument serves as a repeat count.
-
-@vindex dired-recursive-deletes
- The variable @code{dired-recursive-deletes} controls whether the
-delete command will delete non-empty directories (including their
-contents). The default is to delete only empty directories.
+ You can flag a file for deletion by moving to the line describing
+the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The
+deletion flag is visible as a @samp{D} at the beginning of the line.
+This command moves point to the next line, so that repeated @kbd{d}
+commands flag successive files. A numeric argument serves as a repeat
+count.
@kindex u @r{(Dired deletion)}
@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 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.
+ The reason for flagging files for deletion, rather than deleting
+files immediately, is to reduce the danger of deleting a file
+accidentally. Until you direct 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-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 shortened Dired buffer remains selected.
+ 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.
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
the buffer, and no files actually deleted.
+@cindex recursive deletion
+@vindex dired-recursive-deletes
+ You can delete empty directories just like other files, but normally
+Dired cannot delete directories that are nonempty. If the variable
+@code{dired-recursive-deletes} is non-@code{nil}, then Dired can
+delete nonempty directories including all their contents. That can
+be somewhat risky.
+
@node Flagging Many Files
@section Flagging Many Files at Once
@cindex flagging many files for deletion (in Dired)
(@pxref{Backup}).
@item &
-Flag for deletion all files with certain kinds of names, names that
-suggest you could easily create the files again.
+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
@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{~}.
+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}.
@kindex . @r{(Dired)}
@vindex dired-kept-versions
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 subdirectories
-by hiding them (@pxref{Hiding Subdirectories}).
+@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
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}.
+@ignore @c This command seems too risky to document at all.
@item a
@kindex a @r{(Dired)}
@findex dired-find-alternate-file
Like @kbd{f}, but replaces the contents of the Dired buffer with
that of an alternate file or directory (@code{dired-find-alternate-file}).
+@end ignore
@item o
@kindex o @r{(Dired)}
Visit the file described on the current line, and display the buffer in
another window, but do not select that window (@code{dired-display-file}).
-@item Mouse-2
+@item Mouse-1
+@itemx Mouse-2
@findex dired-mouse-find-file-other-window
Visit the file named by the line you click on
(@code{dired-mouse-find-file-other-window}). This uses another window
@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, Miscellaneous File Operations}.
+(@code{dired-view-file}). 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 equivalent to moving to the line
+for @file{..} and typing @kbd{f} there.
@end table
@node 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 use the files marked with @samp{*}, the
-exception being @kbd{x} which deletes the flagged files.
+commands to operate on files use the files marked with @samp{*}. The
+only command that operates on flagged flies is @kbd{x}, which expunges
+them.
- Here are some commands for marking with @samp{*}, or for unmarking or
-operating on marks. (@xref{Dired Deletion}, for commands to flag and
-unflag files.)
+ Here are some commands for marking with @samp{*}, for unmarking, and
+for operating on marks. (@xref{Dired Deletion}, for commands to flag
+and unflag files.)
@table @kbd
@item m
@item * @@
@kindex * @@ @r{(Dired)}
@findex dired-mark-symlinks
-@cindex marking symlinks (in Dired)
+@cindex marking symbolic links (in Dired)
Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
With a numeric argument, unmark all those files.
@kindex * / @r{(Dired)}
@findex dired-mark-directories
@cindex marking subdirectories (in Dired)
-Mark with @samp{*} all files which are actually directories, except for
+Mark with @samp{*} all files which are directories, except for
@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric
argument, unmark all those files.
(@code{dired-unmark-backward}).
@item * !
+@itemx U
@kindex * ! @r{(Dired)}
+@kindex U @r{(Dired)}
@findex dired-unmark-all-marks
Remove all marks from all the files in this Dired buffer
(@code{dired-unmark-all-marks}).
@item * ? @var{markchar}
+@itemx M-@key{DEL}
@kindex * ? @r{(Dired)}
+@kindex M-DEL @r{(Dired)}
@findex dired-unmark-all-files
Remove all marks that use the character @var{markchar}
(@code{dired-unmark-all-files}). The argument is a single
files without asking about them.
@item * C-n
+@itemx M-@}
@findex dired-next-marked-file
@kindex * C-n @r{(Dired)}
+@kindex M-@} @r{(Dired)}
Move down to the next marked file (@code{dired-next-marked-file})
A file is ``marked'' if it has any kind of mark.
@item * C-p
+@itemx M-@{
@findex dired-prev-marked-file
@kindex * C-p @r{(Dired)}
+@kindex M-@{ @r{(Dired)}
Move up to the previous marked file (@code{dired-prev-marked-file})
-@item * t
+@item t
+@itemx * t
+@kindex t @r{(Dired)}
@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.
Mark (with @samp{*}) all files whose names match the regular expression
@var{regexp} (@code{dired-mark-files-regexp}). This command is like
@kbd{% d}, except that it marks files with @samp{*} instead of flagging
-with @samp{D}. @xref{Flagging Many Files}.
+with @samp{D}.
Only the non-directory part of the file name is used in matching. Use
-@samp{^} and @samp{$} to anchor matches. Exclude subdirectories by
-hiding them (@pxref{Hiding Subdirectories}).
+@samp{^} and @samp{$} to anchor matches. You can exclude
+subdirectories by temporarily hiding them (@pxref{Hiding
+Subdirectories}).
@item % g @var{regexp} @key{RET}
@findex dired-mark-files-containing-regexp
@kbd{% m}, except that it searches the file contents instead of the file
name.
-@item C-_
+@item C-x u
+@itemx C-_
+@itemx C-/
@kindex C-_ @r{(Dired)}
@findex dired-undo
Undo changes in the Dired buffer, such as adding or removing
marks (@code{dired-undo}). @emph{This command does not revert the
-actual file operations, nor recovers 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.
+actual file operations, nor recover lost files!} It just undoes
+changes in the buffer itself.
+
+In some cases, using this after commands that operate on files can
+cause trouble. For example, after renaming one or more files,
+@code{dired-undo} restores the original names in the Dired buffer,
+which gets the Dired buffer out of sync with the actual contents of
+the directory.
@end table
@node Operating on Files
This section describes the basic Dired commands to operate on one file
or several files. All of these commands are capital letters; all of
them use the minibuffer, either to read an argument or to ask for
-confirmation, before they act. All of them give you several ways to
-specify which files to manipulate:
+confirmation, before they act. All of them let you specify the
+files to manipulate in these ways:
@itemize @bullet
@item
Otherwise, the command operates on the current file only.
@end itemize
+@noindent
+Certain other Dired commands, such as @kbd{!} and the @samp{%}
+commands, use the same conventions to decide which files to work on.
+
@vindex dired-dwim-target
@cindex two directories (in Dired)
Commands which ask for a destination directory, such as those which
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.)
+ Here are the file-manipulating Dired commands that operate on files.
@table @kbd
@findex dired-do-copy
name.
@vindex dired-copy-preserve-time
-If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with
-this command sets the modification time of the new file to be the same
-as that of the old file.
+If @code{dired-copy-preserve-time} is non-@code{nil}, then copying
+with this command preserves the modification time of the old file in
+the copy.
@vindex dired-recursive-copies
-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.
+@cindex recursive copying
+The variable @code{dired-recursive-copies} controls whether to copy
+directories recursively. The default is @code{nil}, which means that
+directories cannot be copied.
@item D
@findex dired-do-delete
@findex dired-do-symlink
@kindex S @r{(Dired)}
-@cindex symlinks (in Dired)
+@cindex symbolic links (creation in Dired)
@item S @var{new} @key{RET}
Make symbolic links to the specified files (@code{dired-do-symlink}).
The argument @var{new} is the directory to make the links in, or (if
program to use to do the work (different systems put @code{chown} in
different places).
+@findex dired-do-touch
+@kindex T @r{(Dired)}
+@cindex changing file time (in Dired)
+@item T @var{timestamp} @key{RET}
+Touch the specified files (@code{dired-do-touch}). This means
+updating their modification times to the present time.
+
@findex dired-do-print
@kindex P @r{(Dired)}
@cindex printing files (in Dired)
command to print them with, but the minibuffer starts out with a
suitable guess made using the variables @code{lpr-command} and
@code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
-@pxref{Hardcopy}).
+@pxref{Printing}).
@findex dired-do-compress
@kindex Z @r{(Dired)}
@cindex compressing files (in Dired)
@item Z
Compress the specified files (@code{dired-do-compress}). If the file
-appears to be a compressed file already, it is uncompressed instead.
+appears to be a compressed file already, uncompress it instead.
@findex dired-do-load
@kindex L @r{(Dired)}
more matches. @xref{Tags Search}.
@end table
-@kindex + @r{(Dired)}
-@findex dired-create-directory
- One special 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.
-
@node Shell Commands in Dired
@section Shell Commands in Dired
@cindex shell commands, Dired
@findex dired-do-shell-command
@kindex ! @r{(Dired)}
@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}). There are two ways of applying a shell
-command to multiple files:
+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}).
+
+ The working directory for the shell command is the top-level directory
+of the Dired buffer.
+
+ There are two ways of applying a shell command to multiple files:
@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:
-@example
-uuencode ? ? > ?.uu
-@end example
+@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.
+@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, here is how to uuencode each file,
+making the output file name by appending @samp{.uu} to the input file
+name:
@example
-for file in *; do uuencode "$file" "$file" >"$file".uu; done
+for file in * ; do uuencode "$file" "$file" >"$file".uu; done
@end example
-The working directory for the shell command is the top-level directory
-of the Dired buffer.
-
-The @kbd{!} command does not attempt to update the Dired buffer to show
-new or modified files, because it doesn't really understand shell
+ 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}).
@section Transforming File Names in Dired
This section describes Dired commands which alter file names in a
-systematic way.
+systematic way. Each command operates on some or all of the marked
+files, using a new name made by transforming the existing name.
Like the basic Dired file-manipulation commands (@pxref{Operating on
Files}), the commands described here operate either on the next
@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
+then filter the selected names by typing @kbd{y} or @kbd{n} when the
command prompts for confirmation.
@table @kbd
from the name of the old file.
@end table
- The four regular-expression substitution commands effectively perform
-a search-and-replace on the selected file names in the Dired buffer.
-They read two arguments: a regular expression @var{from}, and a
-substitution pattern @var{to}.
-
- The commands match each ``old'' file name against the regular
-expression @var{from}, and then replace the matching part with @var{to}.
-You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to
-all or part of what the pattern matched in the old file name, as in
-@code{replace-regexp} (@pxref{Regexp Replace}). If the regular expression
-matches more than once in a file name, only the first match is replaced.
+ The four regular-expression substitution commands effectively
+perform a search-and-replace on the selected file names. They read
+two arguments: a regular expression @var{from}, and a substitution
+pattern @var{to}; they match each ``old'' file name against
+@var{from}, and then replace the matching part with @var{to}. You can
+use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or
+part of what the pattern matched in the old file name, as in
+@code{replace-regexp} (@pxref{Regexp Replace}). If the regular
+expression matches more than once in a file name, only the first match
+is replaced.
For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
selected file by prepending @samp{x-} to its name. The inverse of this,
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. (Non-zero
+entire absolute file name including directory name. (A 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,
-mark those files with @kbd{% m @var{regexp} @key{RET}}, then use the
-same regular expression in the command to operate on the files. To make
-this easier, the @kbd{%} commands to operate on files use the last
-regular expression specified in any @kbd{%} command as a default.
+ You may want to select the set of files to operate on using the same
+regexp @var{from} that you will use to operate on them. To do this,
+mark those files with @kbd{% m @var{from} @key{RET}}, then use the
+same regular expression in the command to operate on the files. To
+make this more convenient, the @kbd{%} commands to operate on files
+use the last regular expression specified in any @kbd{%} command as a
+default.
@node Comparison in Dired
@section File Comparison with Dired
@cindex compare files (in Dired)
Here are two Dired commands that compare specified files using
-@code{diff}.
+@code{diff}. They show the output in a buffer using Diff mode
+(@pxref{Comparing Files}).
@table @kbd
@item =
@findex dired-diff
@kindex = @r{(Dired)}
-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. Use @kbd{C-@key{SPC}}
+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. This refers to the ordinary
+Emacs mark, not Dired marks; 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.
+(@pxref{Setting Mark}).
@findex dired-backup-diff
@kindex M-= @r{(Dired)}
Compare the current file with its latest backup file
(@code{dired-backup-diff}). If the current file is itself a backup,
compare it with the file it is a backup of; this way, you can compare
-a file with any backup version of your choice.
+a file with any one of its backups.
The backup file is the first file given to @code{diff}.
@end table
in the minibuffer.) That produces a recursive directory listing showing
all subdirectories at all levels.
- But usually all the subdirectories are too many; usually you will
-prefer to include specific subdirectories only. You can do this with
-the @kbd{i} command:
+ More often, you will want to show only specific subdirectories. You
+can do this with the @kbd{i} command:
@table @kbd
@findex dired-maybe-insert-subdir
subdirectory's contents. Use @kbd{C-u k} on the subdirectory header
line to delete the subdirectory. @xref{Dired Updating}.
+@ifnottex
+@include dired-xtra.texi
+@end ifnottex
+
@node Subdirectory Motion
@section Moving Over Subdirectories
@cindex hiding in Dired (Dired)
@dfn{Hiding} a subdirectory means to make it invisible, except for its
-header line, via selective display (@pxref{Selective Display}).
+header line.
@table @kbd
@item $
subdirectory. For example, the commands to operate on marked files
ignore files in hidden directories even if they are marked. Thus you
can use hiding to temporarily exclude subdirectories from operations
-without having to remove the markers.
-
- The subdirectory hiding commands toggle; that is, they hide what was
-visible, and show what was hidden.
+without having to remove the Dired marks on files in those
+subdirectories.
@node Dired Updating
@section Updating the Dired Buffer
Update the entire contents of the Dired buffer (@code{revert-buffer}).
@item l
-Update the specified files (@code{dired-do-redisplay}).
+Update the specified files (@code{dired-do-redisplay}). You specify the
+files for @kbd{l} in the same way as for file operations.
@item k
Delete the specified @emph{file lines}---not the files, just the lines
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
-header line for a subdirectory is another way to delete a subdirectory
-from the Dired buffer.
+ If you use @kbd{k} with a numeric prefix argument to kill the line
+for a file that is a directory, which you have inserted in the Dired
+buffer as a subdirectory, it deletes that subdirectory from the buffer
+as well. Typing @kbd{C-u k} on the header line for a subdirectory
+also deletes the subdirectory from the Dired buffer.
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
@var{pattern}, and chooses all the files in @var{directory} or its
subdirectories whose individual names match @var{pattern}.
- The files thus chosen are displayed in a Dired buffer in which the
+ The files thus chosen are displayed in a Dired buffer, in which the
ordinary Dired commands are available.
@findex find-grep-dired
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{Compilation}.
+@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}.)
@code{find} what condition to test. To use this command, you need to
know how to use @code{find}.
-@findex locate
-@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.
-
@vindex find-ls-option
The format of listing produced by these commands is controlled by the
variable @code{find-ls-option}, whose default value specifies using
options @samp{-ld} for @code{ls}. If your listings are corrupted, you
may need to change the value of this variable.
+
+@findex locate
+@findex locate-with-filter
+@cindex file database (locate)
+@vindex locate-command
+ @kbd{M-x locate} provides a similar interface to the @code{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
+operations work, but do not always automatically update the buffer.
+Reverting the buffer with @kbd{g} deletes all inserted subdirectories,
+and erases all flags and marks.
+
+@node Wdired
+@section Editing the Dired Buffer
+
+@cindex wdired mode
+@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{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.
+
+@findex wdired-finish-edit
+ While in Wdired mode, you can rename files by editing the file names
+displayed in the Dired buffer. All the ordinary Emacs editing
+commands, including rectangle operations and @code{query-replace}, are
+available for this. Once you are done editing, type @kbd{C-c C-c}
+(@code{wdired-finish-edit}). This applies your changes and switches
+back to ordinary Dired mode.
+
+ Apart from simply renaming files, you can move a file to another
+directory by typing in the new file name (either absolute or
+relative). To mark a file for deletion, delete the entire filename.
+To change the target of a symbolic link, edit the link target name
+which appears next to the link name.
+
+ The rest of the text in the buffer, such as the file sizes and
+modification dates, is marked read-only, so you can't edit it.
+However, if you set @code{wdired-allow-to-change-permissions} to
+@code{t}, you can edit the file permissions. For example, you can
+change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file
+world-writable. These changes also take effect when you type @kbd{C-c
+C-c}.
+
+@node Misc Dired Features
+@section Other Dired Features
+
+@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.
+
+@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
+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.
+
+ 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
+file names relative to the Dired buffer's default directory. (This
+can still contain slashes if in a subdirectory.) As a special case,
+if point is on a directory headerline, @kbd{w} gives you the absolute
+name of that directory. Any prefix argument or marked files are
+ignored in this case.
+
+ The main purpose of this command is so that you can yank the file
+names into arguments for other Emacs commands. It also displays what
+it added to the kill ring, so you can use it to display the list of
+currently marked files in the echo area.
+
+@findex dired-compare-directories
+ The command @kbd{M-x dired-compare-directories} is used to compare
+the current Dired buffer with another directory. It marks all the files
+that are ``different'' between the two directories. It puts these marks
+in all Dired buffers where these files are listed, which of course includes
+the current buffer.
+
+ The default comparison method (used if you type @key{RET} at the
+prompt) is to compare just the file names---each file name that does
+not appear in the other directory is ``different''. You can specify
+more stringent comparisons by entering a Lisp expression, which can
+refer to the variables @code{size1} and @code{size2}, the respective
+file sizes; @code{mtime1} and @code{mtime2}, the last modification
+times in seconds, as floating point numers; and @code{fa1} and
+@code{fa2}, the respective file attribute lists (as returned by the
+function @code{file-attributes}). This expression is evaluated for
+each pair of like-named files, and if the expression's value is
+non-@code{nil}, those files are considered ``different''.
+
+ For instance, @code{M-x dired-compare-directories @key{RET} (>
+mtime1 mtime2) @key{RET}} marks files newer in this directory than in
+the other, and marks files older in the other directory than in this
+one. It also marks files with no counterpart, in both directories, as
+always.
+
+@cindex drag and drop, Dired
+ On the X window system, Emacs supports the ``drag and drop''
+protocol. You can drag a file object from another program, and drop
+it onto a Dired buffer; this either moves, copies, or creates a link
+to the file in that directory. Precisely which action is taken is
+determined by the originating program. Dragging files out of a Dired
+buffer is currently not supported.
+
+@ignore
+ arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1
+@end ignore