X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b792ae3605a3824b49f3b7a83300fd3f6b7b1f59..8d892d7fef218001fa8ef828db4a5a864448f950:/man/dired.texi diff --git a/man/dired.texi b/man/dired.texi index 92316f9864..051c735f99 100644 --- a/man/dired.texi +++ b/man/dired.texi @@ -1,6 +1,6 @@ @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 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Dired, Calendar/Diary, Rmail, Top @chapter Dired, the Directory Editor @@ -12,12 +12,19 @@ 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. + The Dired buffer is ``read-only,'' and inserting text in it is not +useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are +used for special Dired commands. Some Dired commands @dfn{mark} or +@dfn{flag} the @dfn{current file} (that is, the file on the current +line); other commands operate on the marked files or on the flagged +files. + The Dired-X package provides various extra features for Dired mode. -@xref{Dired-X,,,dired-x, Dired Extra Version 2 User's Manual}. +@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. @menu * Enter: Dired Enter. How to invoke Dired. -* Commands: Dired Commands. Commands in the Dired buffer. +* Navigation: Dired Navigation. Special motion commands in the Dired buffer. * Deletion: Dired Deletion. Deleting files with Dired. * Flagging Many Files:: Flagging files based on their names. * Visit: Dired Visiting. Other file operations through Dired. @@ -32,6 +39,8 @@ to operate on the files listed. * 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 @@ -40,17 +49,20 @@ to operate on the files listed. @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 which 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 +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. +before you enter the directory specification. No matter how they are +specified, the @code{ls} switches should all be short options (that +is, single characters) requiring no arguments. @findex dired-other-window @kindex C-x 4 d @@ -61,15 +73,8 @@ 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. -@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)} @@ -85,13 +90,21 @@ 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. +@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 @@ -112,6 +125,7 @@ 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} controls whether the delete command will delete non-empty directories (including their @@ -185,16 +199,17 @@ 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 @@ -237,14 +252,18 @@ Visit the file described on the current line, like typing @kbd{C-x C-f} 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)} @@ -260,7 +279,8 @@ file. @xref{Windows}. 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 @@ -270,11 +290,17 @@ to display the file, like the @kbd{o} command. @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 more convenient than moving to +the parent directory's line and typing @kbd{f} there. @end table @node Marks vs Flags @@ -312,7 +338,7 @@ those files. @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. @@ -346,13 +372,17 @@ Move point to previous line and remove any mark on that line (@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 @@ -366,21 +396,27 @@ asking whether to remove its mark. You can answer @kbd{y} meaning yes, 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. @@ -437,7 +473,12 @@ name. @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 @@ -493,6 +534,7 @@ 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. @@ -526,7 +568,7 @@ just one link) the name to give the link. @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 @@ -560,6 +602,12 @@ 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). +@findex dired-do-touch +@kindex T @r{(Dired)} +@cindex changing file time (in Dired) +@item T @var{timestamp} @key{RET} +Change the time of the specified files (@code{dired-do-touch}). + @findex dired-do-print @kindex P @r{(Dired)} @cindex printing files (in Dired) @@ -568,7 +616,7 @@ Print the specified files (@code{dired-do-print}). You must specify the 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)} @@ -638,38 +686,41 @@ 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 @@ -684,7 +735,21 @@ Updating}). @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 @@ -742,7 +807,8 @@ matches that should span the whole filename.) 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, @@ -766,7 +832,10 @@ regular expression specified in any @kbd{%} command as a default. 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)} @@ -905,9 +974,6 @@ 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. - @node Dired Updating @section Updating the Dired Buffer @cindex updating Dired buffer @@ -964,10 +1030,11 @@ 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 -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, then this deletes that subdirectory from the +buffer as well. Typing @kbd{C-u k} on the header line for a subdirectory +is another way to delete a 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 @@ -1008,7 +1075,7 @@ 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{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}.) @@ -1021,16 +1088,112 @@ minibuffer arguments, @var{directory} and @var{find-args}; it runs @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 lines +matching 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, just edit the target name +displayed 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}, the file permission bits can also be edited. 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 + +@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. + + 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 +was pushed onto the kill ring, so you can use it to display the list +of currently marked files in the echo area. 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. + +@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