@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Dired, Calendar/Diary, Rmail, Top
+@node Dired
@chapter Dired, the Directory Editor
@c This node is referenced in the tutorial. When renaming or deleting
@c it, the tutorial needs to be adjusted.
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
+ The Dired buffer is ``read-only'', and inserting text in it is not
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
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}.
+@xref{Top, Dired-X,,dired-x, Dired Extra 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
either one file or several files.
* Shell Commands in Dired:: Running a shell command on the marked files.
* Transforming File Names:: Using patterns to rename multiple files.
-* Comparison in Dired:: Running `diff' by way of Dired.
+* Comparison in Dired:: Running @code{diff} by way of Dired.
* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
@ifnottex
* Subdir Switches:: Subdirectory switches in Dired.
* 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.
+* Find: Dired and Find. Using @code{find} to choose the files for Dired.
* Wdired:: Operating on files by editing the Dired buffer.
* Image-Dired:: Viewing image thumbnails in Dired.
* Misc: Misc Dired Features. Various other features.
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}
-contain @samp{-l}. If you use a 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{=}.
-
- On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls};
-see @ref{ls in Lisp}, for options and peculiarities of that emulation.
+give to @command{ls} for listing the directory; this string
+@emph{must} contain @samp{-l}. If you use a prefix argument with the
+@code{dired} command, you can specify the @command{ls} switches with the
+minibuffer before you enter the directory specification. No matter
+how they are specified, the @command{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{=}.
+
+@vindex dired-use-ls-dired
+ If your @command{ls} program supports the @samp{--dired} option,
+Dired automatically passes it that option; this causes @command{ls} to
+emit special escape sequences for certain unusual file names, without
+which Dired will not be able to parse those names. The first time you
+run Dired in an Emacs session, it checks whether @command{ls} supports
+the @samp{--dired} option by calling it once with that option. If the
+exit code is 0, Dired will subsequently use the @samp{--dired} option;
+otherwise it will not. You can inhibit this check by customizing the
+variable @code{dired-use-ls-dired}. The value @code{unspecified} (the
+default) means to perform the check; any other non-@code{nil} value
+means to use the @samp{--dired} option; and @code{nil} means not to
+use the @samp{--dired} option.
+
+ On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}.
+@xref{ls in Lisp}, for options and peculiarities of this emulation.
@findex dired-other-window
@kindex C-x 4 d
@findex dired-other-frame
@kindex C-x 5 d
- To display the Dired buffer in another window rather than in the
-selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead
-of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
-separate frame to display the Dired buffer.
+ To display the Dired buffer in another window, use @kbd{C-x 4 d}
+(@code{dired-other-window}). @kbd{C-x 5 d}
+(@code{dired-other-frame}) displays the Dired buffer in a separate
+frame.
+
+@kindex q @r{(Dired)}
+@findex quit-window
+ Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and
+deletes its window if the window was created just for that buffer.
@node Dired Navigation
@section Navigation in the Dired Buffer
that file.
@cindex searching Dired buffers
+@findex dired-isearch-filenames
@vindex dired-isearch-filenames
+@findex dired-isearch-filenames-regexp
+@kindex M-s f C-s @r{(Dired)}
+@kindex M-s f M-C-s @r{(Dired)}
@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
@table @kbd
@item d
-Flag this file for deletion.
+Flag this file for deletion (@code{dired-flag-file-deletion}).
@item u
-Remove deletion flag on this line.
+Remove the deletion flag (@code{dired-unmark}).
@item @key{DEL}
-Move point to previous line and remove the deletion flag on that line.
+Move point to previous line and remove the deletion flag on that line
+(@code{dired-unmark-backward}).
@item x
-Delete the files that are flagged for deletion.
+Delete files flagged for deletion (@code{dired-do-flagged-delete}).
@end table
@kindex d @r{(Dired)}
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.
+commands flag successive files. A numeric prefix argument serves as a
+repeat count; a negative count means to flag preceding files.
+
+ If the region is active, the @kbd{d} command flags all files in the
+region for deletion; in this case, the command does not move point,
+and ignores any prefix argument.
@kindex u @r{(Dired deletion)}
@kindex DEL @r{(Dired)}
@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.
+like @kbd{u} with argument @minus{}1. A numeric prefix argument to
+either command serves as a repeat count, with a negative count meaning
+to unflag in the opposite direction. If the region is active, these
+commands instead unflag all files in the region, without moving point.
@kindex x @r{(Dired)}
@findex dired-do-flagged-delete
- To delete the flagged files, type @kbd{x}
-(@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
+ To delete flagged files, type @kbd{x}
+(@code{dired-do-flagged-delete}). This command 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.
be somewhat risky.
@vindex delete-by-moving-to-trash
- On some systems, there is a facility called the ``Trash'' or
-``Recycle Bin'', but Emacs does @emph{not} use it by default. Thus,
-when you delete a file in Dired, it is gone forever. However, you can
-tell Emacs to use the Trash for file deletion, by changing the
-variable @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc
-File Ops}, for more information about the Trash.
+ If you change the variable @code{delete-by-moving-to-trash} to
+@code{t}, the above deletion commands will move the affected files or
+directories into the operating system's Trash, instead of deleting
+them outright. @xref{Misc File Ops}.
@node Flagging Many Files
@section Flagging Many Files at Once
@item Mouse-1
@itemx Mouse-2
@findex dired-mouse-find-file-other-window
-Visit the file named by the line you click on
+Visit the file whose name you clicked on
(@code{dired-mouse-find-file-other-window}). This uses another window
to display the file, like the @kbd{o} command.
@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 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}.
+View the file described on the current line, with View mode
+(@code{dired-view-file}). View mode provides convenient commands to
+navigate the buffer but forbids changing it; @xref{View Mode}.
@item ^
@kindex ^ @r{(Dired)}
@kindex m @r{(Dired)}
@kindex * m @r{(Dired)}
@findex dired-mark
-Mark the current file with @samp{*} (@code{dired-mark}). With a numeric
-argument @var{n}, mark the next @var{n} files starting with the current
-file. (If @var{n} is negative, mark the previous @minus{}@var{n}
-files.)
+Mark the current file with @samp{*} (@code{dired-mark}). If the
+region is active, mark all files in the region instead; otherwise, if
+a numeric argument @var{n} is supplied, mark the next @var{n} files
+instead, starting with the current file (if @var{n} is negative, mark
+the previous @minus{}@var{n} files).
@item * *
@kindex * * @r{(Dired)}
@kindex u @r{(Dired)}
@kindex * u @r{(Dired)}
@findex dired-unmark
-Remove any mark on this line (@code{dired-unmark}).
+Remove any mark on this line (@code{dired-unmark}). If the region is
+active, unmark all files in the region instead; otherwise, if a
+numeric argument @var{n} is supplied, unmark the next @var{n} files
+instead, starting with the current file (if @var{n} is negative,
+unmark the previous @minus{}@var{n} files).
@item @key{DEL}
@itemx * @key{DEL}
@findex dired-unmark-backward
@cindex unmarking files (in Dired)
Move point to previous line and remove any mark on that line
-(@code{dired-unmark-backward}).
+(@code{dired-unmark-backward}). If the region is active, unmark all
+files in the region instead; otherwise, if a numeric argument @var{n}
+is supplied, unmark the @var{n} preceding files instead, starting with
+the current file (if @var{n} is negative, unmark the next
+@minus{}@var{n} files).
@item * !
@itemx U
@kbd{% m}, except that it searches the file contents instead of the file
name.
-@item C-x u
+@item C-/
+@itemx 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
@cindex recursive copying
The variable @code{dired-recursive-copies} controls whether to copy
directories recursively (like @samp{cp -r}). The default is
-@code{nil}, which means that directories cannot be copied.
+@code{top}, which means to ask before recursively copying a directory.
@item D
@findex dired-do-delete
Rename the specified files (@code{dired-do-rename}). If you rename a
single file, the argument @var{new} is the new name of the file. If
you rename several files, the argument @var{new} is the directory into
-which to move the files (this is like the shell command @code{mv}).
+which to move the files (this is like the shell command @command{mv}).
Dired automatically changes the visited file name of buffers associated
with renamed files so that they refer to the new names.
@cindex hard links (in Dired)
@item H @var{new} @key{RET}
Make hard links to the specified files (@code{dired-do-hardlink}).
-This is like the shell command @code{ln}. The argument @var{new} is
+This is like the shell command @command{ln}. The argument @var{new} is
the directory to make the links in, or (if making just one link) the
name to give the link.
@kindex M @r{(Dired)}
@cindex changing file permissions (in Dired)
@item M @var{modespec} @key{RET}
-Change the mode (also called ``permission bits'') of the specified files
-(@code{dired-do-chmod}). This uses the @code{chmod} program, so
-@var{modespec} can be any argument that @code{chmod} can handle.
+Change the mode (also called @dfn{permission bits}) of the specified
+files (@code{dired-do-chmod}). @var{modespec} can be in octal or
+symbolic notation, like arguments handled by the @command{chmod}
+program.
@findex dired-do-chgrp
@kindex G @r{(Dired)}
@vindex dired-chown-program
The variable @code{dired-chown-program} specifies the name of the
-program to use to do the work (different systems put @code{chown} in
-different places).
+program to use to do the work (different systems put @command{chown}
+in different places).
@findex dired-do-touch
@kindex T @r{(Dired)}
@item
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.
+runs the shell command once for each file, adding the file name 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
@cindex file comparison (in Dired)
@cindex compare files (in Dired)
- Here are two Dired commands that compare specified files using
-@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. 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}).
-
-@findex dired-backup-diff
-@kindex M-= @r{(Dired)}
-@item M-=
-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 one of its backups.
-
-The backup file is the first file given to @code{diff}.
-@end table
+ The @kbd{=} (@code{dired-diff}) command compares the current file
+(the file at point) with another file (read using the minibuffer)
+using the @command{diff} program. The file specified with the
+minibuffer is the first argument of @command{diff}, and file at point
+is the second argument. The output of the @command{diff} program is
+shown in a buffer using Diff mode (@pxref{Comparing Files}).
+
+ If the region is active, the default for the file read using the
+minibuffer is the file at the mark (i.e.@: the ordinary Emacs mark,
+not a Dired mark; @pxref{Setting Mark}). Otherwise, if the file at
+point has a backup file (@pxref{Backup}), that is the default.
@node Subdirectories in Dired
@section Subdirectories in Dired
@cindex subdirectories in Dired
@cindex expanding subdirectories in Dired
- A Dired buffer displays just one directory in the normal case;
-but you can optionally include its subdirectories as well.
+ A Dired buffer usually displays just one directory, but you can
+optionally include its subdirectories as well.
The simplest way to include multiple directories in one Dired buffer is
-to specify the options @samp{-lR} for running @code{ls}. (If you give a
+to specify the options @samp{-lR} for running @command{ls}. (If you give a
numeric argument when you run Dired, then you can specify these options
in the minibuffer.) That produces a recursive directory listing showing
all subdirectories at all levels.
More often, you will want to show only specific subdirectories. You
-can do this with the @kbd{i} command:
+can do this with @kbd{i} (@code{dired-maybe-insert-subdir}):
@table @kbd
@findex dired-maybe-insert-subdir
Insert the contents of a subdirectory later in the buffer.
@end table
-Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
-that describes a file which is a directory. It inserts the contents of
-that directory into the same Dired buffer, and moves there. Inserted
-subdirectory contents follow the top-level directory of the Dired
-buffer, just as they do in @samp{ls -lR} output.
-
-If the subdirectory's contents are already present in the buffer, the
-@kbd{i} command just moves to it.
-
-In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u
-C-@key{SPC}} takes you back to the old position in the buffer (the line
-describing that subdirectory). You can also use @samp{^} to return
-to the parent directory in the same Dired buffer.
-
-Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
-subdirectory's contents. Use @kbd{C-u k} on the subdirectory header
-line to delete the subdirectory (@pxref{Dired Updating}). You can also
-hide and show inserted subdirectories (@pxref{Hiding Subdirectories}).
+@noindent
+If you use this command on a line that describes a file which is a
+directory, it inserts the contents of that directory into the same
+Dired buffer, and moves there. Inserted subdirectory contents follow
+the top-level directory of the Dired buffer, just as they do in
+@samp{ls -lR} output.
+
+ If the subdirectory's contents are already present in the buffer,
+the @kbd{i} command just moves to it.
+
+ In either case, @kbd{i} sets the Emacs mark before moving, so
+@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired
+buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to
+the parent directory in the same Dired buffer (@pxref{Dired
+Visiting}).
+
+ Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
+subdirectory's contents, and use @kbd{C-u k} on the subdirectory
+header line to remove the subdirectory listing (@pxref{Dired
+Updating}). You can also hide and show inserted subdirectories
+(@pxref{Hiding Subdirectories}).
@ifnottex
@include dired-xtra.texi
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.
+buffer as a subdirectory, it removed that subdirectory line from the
+buffer as well. Typing @kbd{C-u k} on the header line for a
+subdirectory also removes the subdirectory line 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
need to know how to use @command{find}.
@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.
+ The format of listing produced by these commands is controlled by
+the variable @code{find-ls-option}. This is a pair of options; the
+first specifying how to call @command{find} to produce the file listing,
+and the second telling Dired to parse the output.
@findex locate
@findex locate-with-filter
@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}
+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.
You can also enter Image-Dired directly by typing @kbd{M-x
image-dired}. This prompts for a directory; specify one that has
image files. This creates thumbnails for all the images in that
-directory, and displays them all in the ``thumbnail buffer.'' This
+directory, and displays them all in the ``thumbnail buffer''. This
takes a long time if the directory contains many image files, and it
asks for confirmation if the number of image files exceeds
@code{image-dired-show-all-from-dir-max-files}.
@kindex + @r{(Dired)}
@findex dired-create-directory
The command @kbd{+} (@code{dired-create-directory}) reads a
-directory name, and creates the directory if it does not already
-exist.
+directory name, and creates that directory. It signals an error if
+the directory already exists.
@cindex searching multiple files via Dired
+@kindex M-s a C-s @r{(Dired)}
+@kindex M-s a M-C-s @r{(Dired)}
+@findex dired-do-isearch
+@findex dired-do-isearch-regexp
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
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
+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
@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.''
+non-@code{nil}, those files are considered ``different''.
For instance, the sequence @code{M-x dired-compare-directories
@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this
in both directories, as always.
@cindex drag and drop, Dired
- On the X window system, Emacs supports the ``drag and drop''
+ 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