@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}.
+
@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.
* 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.
-* Extra: Dired Extra Features. Dired-X provides more features.
@end menu
@node Dired Enter
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
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.
+
+@cindex recursive deletion
@vindex dired-recursive-deletes
-The variable @code{dired-recursive-deletes} determines if the delete
-command will delete non-empty directories recursively. The default
-is to delete only empty directories.
+ 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.
@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 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
@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.
+that of an alternate file or directory (@code{dired-find-alternate-file}).
@item o
@kindex o @r{(Dired)}
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}.
+@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)}
@findex dired-unmark-all-files
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.
+character---do not use @key{RET} to terminate it. See the description
+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,
become unmarked, and unmarked files are marked with @samp{*}. Files
marked in any other way are not affected.
-@item * c @var{old} @var{new}
+@item * c @var{old-markchar} @var{new-markchar}
@kindex * c @r{(Dired)}
@findex dired-change-marks
-Replace all marks that use the character @var{old} with marks that use
-the character @var{new} (@code{dired-change-marks}). This command is
-the primary way to create or use marks other than @samp{*} or @samp{D}.
-The arguments are single characters---do not use @key{RET} to terminate
-them.
+Replace all marks that use the character @var{old-markchar} with marks
+that use the character @var{new-markchar} (@code{dired-change-marks}).
+This command is the primary way to create or use marks other than
+@samp{*} or @samp{D}. The arguments are single characters---do not use
+@key{RET} to terminate them.
You can use almost any character as a mark character by means of this
-command, to distinguish various classes of files. If @var{old} is a
-space (@samp{ }), then the command operates on all unmarked files; if
-@var{new} is a space, then the command unmarks the files it acts on.
+command, to distinguish various classes of files. If @var{old-markchar}
+is a space (@samp{ }), then the command operates on all unmarked files;
+if @var{new-markchar} is a space, then the command unmarks the files it
+acts on.
To illustrate the power of this command, here is how to put @samp{D}
flags on all the files that have no marks, while unflagging all those
* 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.)
Copy the specified files (@code{dired-do-copy}). The argument @var{new}
is the directory to copy into, or (if copying a single file) the new
name.
-@vindex dired-recursive-copies
-The variable @code{dired-recursive-copies} determines if directories are
-copied recursively. The default is to not copy recursively.
@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.
+@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.
+
@item D
@findex dired-do-delete
@kindex D @r{(Dired)}
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)}
@findex dired-do-chgrp
@kindex G @r{(Dired)}
-@cindex changing file group ownership (in Dired)
+@cindex changing file group (in Dired)
@item G @var{newgroup} @key{RET}
Change the group of the specified files to @var{newgroup}
(@code{dired-do-chgrp}).
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
more matches. @xref{Tags Search}.
-
-@kindex a @r{(Dired)}
-@findex dired-do-apply
-@cindex apply arbitrary function to many files
-@item a @var{function} @kbd{RET}
-Apply an arbitrary Lisp function to the name of each marked file
-(@code{dired-do-apply}).
@end table
@kindex + @r{(Dired)}
@findex dired-do-shell-command
@kindex ! @r{(Dired)}
-The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell
+@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. 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:
+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:
@itemize @bullet
@item
file.
@end itemize
-What if you want to run the shell command once for each file but with
-the file name inserted in the middle? Or if you want to use the file
-names in a more complicated fashion? Use a shell loop. For example,
-this shell command would run @code{uuencode} on each of the specified
-files, writing the output into a corresponding @file{.uu} file:
+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
-for file in *; do uuencode $file $file >$file.uu; done
+uuencode ? ? > ?.uu
@end example
-@noindent
-In simple cases you can instead use @samp{?} in the command. This is
-similar to @samp{*} but the command will be run on each file
-individually.
+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:
+
+@example
+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.
@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)}
describing that subdirectory).
Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
-subdirectory's contents. Use @kbd{k} to delete the subdirectory.
-@xref{Dired Updating}.
+subdirectory's contents. Use @kbd{C-u k} on the subdirectory header
+line to delete the subdirectory. @xref{Dired Updating}.
@node Subdirectory Motion
@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
@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}
+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
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.
-
-@node Dired Extra Features
-@section Extra Features for Dired
-
-The Dired-X package provides various extra features for Dired mode. You
-can load it with @code{M-x load-library} or customize
-@code{dired-load-hook} to add @code{dired-require-dired-x}.
-@xref{,Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
HCoop / bpt / emacs.git / blobdiff