0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Dired
0006: @chapter Dired, the Directory Editor
0007: @c This node is referenced in the tutorial.  When renaming or deleting
0008: @c it, the tutorial needs to be adjusted.
0009: @cindex Dired
0010: @cindex file management
0011: 
0012:   Dired makes an Emacs buffer containing a listing of a directory, and
0013: optionally some of its subdirectories as well.  You can use the normal
0014: Emacs commands to move around in this buffer, and special Dired
0015: commands to operate on the listed files.  Dired works with both local
0016: and remote directories.
0017: 
0018:   The Dired buffer is normally read-only, and inserting text in it is
0019: not allowed (however, the Wdired mode allows that, @pxref{Wdired}).
0020: Ordinary printing characters such as @kbd{d} and @kbd{x} are
0021: redefined for special Dired commands.  Some Dired commands @dfn{mark}
0022: or @dfn{flag} the @dfn{current file} (that is, the file on the current
0023: line); other commands operate on the marked files or on the flagged
0024: files.  You first mark certain files in order to operate on all of
0025: them with one command.
0026: 
0027:   The Dired-X package provides various extra features for Dired mode.
0028: @xref{Top, Dired-X,,dired-x, Dired Extra User's Manual}.
0029: 
0030:   You can also view a list of files in a directory with @kbd{C-x C-d}
0031: (@code{list-directory}).  Unlike Dired, this command does not allow
0032: you to operate on the listed files.  @xref{Directories}.
0033: 
0034: @menu
0035: * Enter: Dired Enter.         How to invoke Dired.
0036: * Navigation: Dired Navigation.   Special motion commands in the Dired buffer.
0037: * Deletion: Dired Deletion.   Deleting files with Dired.
0038: * Flagging Many Files::       Flagging files based on their names.
0039: * Visit: Dired Visiting.      Other file operations through Dired.
0040: * Marks vs Flags::            Flagging for deletion vs marking.
0041: * Operating on Files::        How to copy, rename, print, compress, etc.
0042:                                 either one file or several files.
0043: * Shell Commands in Dired::   Running a shell command on the marked files.
0044: * Transforming File Names::   Using patterns to rename multiple files.
0045: * Comparison in Dired::       Running @code{diff} by way of Dired.
0046: * Subdirectories in Dired::   Adding subdirectories to the Dired buffer.
0047: @ifnottex
0048: * Subdir Switches::           Subdirectory switches in Dired.
0049: @end ifnottex
0050: * Subdirectory Motion::       Moving across subdirectories, and up and down.
0051: * Hiding Subdirectories::     Making subdirectories visible or invisible.
0052: * Updating: Dired Updating.   Discarding lines for files of no interest.
0053: * Find: Dired and Find.       Using @code{find} to choose the files for Dired.
0054: * Wdired::                    Operating on files by editing the Dired buffer.
0055: * Image-Dired::               Viewing image thumbnails in Dired.
0056: * Misc: Misc Dired Features.  Various other features.
0057: @end menu
0058: 
0059: @node Dired Enter
0060: @section Entering Dired
0061: 
0062: @findex dired
0063: @kindex C-x d
0064: @vindex dired-listing-switches
0065:   To invoke Dired, type @kbd{C-x d} (@code{dired}).  This reads a
0066: directory's name using the minibuffer, and opens a @dfn{Dired buffer}
0067: listing the files in that directory.  You can also supply a wildcard
0068: file name pattern as the minibuffer argument, in which case the Dired
0069: buffer lists all files matching that pattern.  A wildcard may appear
0070: in the directory part as well.
0071: For instance,
0072: 
0073: @example
0074: C-x d  ~/foo/*.el  @key{RET}
0075: C-x d  ~/foo/*/*.el  @key{RET}
0076: @end example
0077: 
0078: The former lists all the files with extension @samp{.el} in directory
0079: @samp{foo}.  The latter lists the files with extension @samp{.el}
0080: in all the subdirectories of @samp{foo}.
0081: 
0082: The usual history and completion commands can be used in the minibuffer;
0083: in particular, @kbd{M-n} puts the name of the visited file (if any) in
0084: the minibuffer (@pxref{Minibuffer History}).
0085: 
0086:   You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file})
0087: a directory's name.
0088: 
0089:   The variable @code{dired-listing-switches} specifies the options to
0090: give to @command{ls} for listing the directory; this string
0091: @emph{must} contain @samp{-l}.  If you use a prefix argument with the
0092: @code{dired} command, you can specify the @command{ls} switches with the
0093: minibuffer before you enter the directory specification.  No matter
0094: how they are specified, the @command{ls} switches can include short
0095: options (that is, single characters) requiring no arguments, and long
0096: options (starting with @samp{--}) whose arguments are specified with
0097: @samp{=}.
0098: 
0099: @vindex dired-use-ls-dired
0100:   If your @command{ls} program supports the @samp{--dired} option,
0101: Dired automatically passes it that option; this causes @command{ls} to
0102: emit special escape sequences for certain unusual file names, without
0103: which Dired will not be able to parse those names.  The first time you
0104: run Dired in an Emacs session, it checks whether @command{ls} supports
0105: the @samp{--dired} option by calling it once with that option.  If the
0106: exit code is 0, Dired will subsequently use the @samp{--dired} option;
0107: otherwise it will not.  You can inhibit this check by customizing the
0108: variable @code{dired-use-ls-dired}.  The value @code{unspecified} (the
0109: default) means to perform the check; any other non-@code{nil} value
0110: means to use the @samp{--dired} option; and @code{nil} means not to
0111: use the @samp{--dired} option.
0112: 
0113:   On MS-Windows and MS-DOS systems, and also on some remote systems,
0114: Emacs emulates @command{ls}.  @xref{ls in Lisp}, for options and
0115: peculiarities of this emulation.
0116: 
0117: @findex dired-other-window
0118: @kindex C-x 4 d
0119: @findex dired-other-frame
0120: @kindex C-x 5 d
0121:   To display the Dired buffer in another window, use @kbd{C-x 4 d}
0122: (@code{dired-other-window}).  @kbd{C-x 5 d}
0123: (@code{dired-other-frame}) displays the Dired buffer in a separate
0124: frame.
0125: 
0126: @kindex q @r{(Dired)}
0127: @findex quit-window@r{, in Dired buffers}
0128:   Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and
0129: deletes its window if the window was created just for that buffer.
0130: 
0131: @node Dired Navigation
0132: @section Navigation in the Dired Buffer
0133: 
0134: @kindex C-n @r{(Dired)}
0135: @kindex C-p @r{(Dired)}
0136: @findex dired-next-line
0137: @findex dired-previous-line
0138:   All the usual Emacs cursor motion commands are available in Dired
0139: buffers.  The keys @kbd{C-n} and @kbd{C-p} are redefined to run
0140: @code{dired-next-line} and @code{dired-previous-line}, respectively,
0141: and they put the cursor at the beginning of the file name on the line,
0142: rather than at the beginning of the line.
0143: 
0144: @kindex SPC @r{(Dired)}
0145:   For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
0146: to @kbd{C-n}.  @kbd{p} is equivalent to @kbd{C-p}.  (Moving by lines
0147: is so common in Dired that it deserves to be easy to type.)  @key{DEL}
0148: (move up and unflag) is also often useful simply for moving up
0149: (@pxref{Dired Deletion}).
0150: 
0151: @findex dired-goto-file
0152: @kindex j @r{(Dired)}
0153:   @kbd{j} (@code{dired-goto-file}) prompts for a file name using the
0154: minibuffer, and moves point to the line in the Dired buffer describing
0155: that file.
0156: 
0157: @cindex searching Dired buffers
0158: @findex dired-isearch-filenames
0159: @vindex dired-isearch-filenames
0160: @findex dired-isearch-filenames-regexp
0161: @kindex M-s f C-s @r{(Dired)}
0162: @kindex M-s f M-C-s @r{(Dired)}
0163:   @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward
0164: incremental search in the Dired buffer, looking for matches only
0165: amongst the file names and ignoring the rest of the text in the
0166: buffer.  @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp})
0167: does the same, using a regular expression search.  If you change the
0168: variable @code{dired-isearch-filenames} to @code{t}, then the
0169: usual search commands also limit themselves to the file names; for
0170: instance, @kbd{C-s} behaves like @kbd{M-s f C-s}.  If the value is
0171: @code{dwim}, then search commands match the file names only when point
0172: was on a file name initially.  @xref{Search}, for information about
0173: incremental search.
0174: 
0175:   Some additional navigation commands are available when the Dired
0176: buffer includes several directories.  @xref{Subdirectory Motion}.
0177: 
0178: @node Dired Deletion
0179: @section Deleting Files with Dired
0180: @cindex flagging files (in Dired)
0181: @cindex deleting files (in Dired)
0182: 
0183:   One of the most frequent uses of Dired is to first @dfn{flag} files for
0184: deletion, then delete the files that were flagged.
0185: 
0186: @table @kbd
0187: @item d
0188: Flag this file for deletion (@code{dired-flag-file-deletion}).
0189: @item u
0190: Remove the deletion flag (@code{dired-unmark}).
0191: @item @key{DEL}
0192: Move point to previous line and remove the deletion flag on that line
0193: (@code{dired-unmark-backward}).
0194: @item x
0195: Delete files flagged for deletion (@code{dired-do-flagged-delete}).
0196: @end table
0197: 
0198: @kindex d @r{(Dired)}
0199: @findex dired-flag-file-deletion
0200:   You can flag a file for deletion by moving to the line describing
0201: the file and typing @kbd{d} (@code{dired-flag-file-deletion}).  The
0202: deletion flag is visible as a @samp{D} at the beginning of the line.
0203: This command moves point to the next line, so that repeated @kbd{d}
0204: commands flag successive files.  A numeric prefix argument serves as a
0205: repeat count; a negative count means to flag preceding files.
0206: 
0207:   If the region is active, the @kbd{d} command flags all files in the
0208: region for deletion; in this case, the command does not move point,
0209: and ignores any prefix argument.
0210: 
0211: @kindex u @r{(Dired deletion)}
0212: @kindex DEL @r{(Dired)}
0213:   The reason for flagging files for deletion, rather than deleting
0214: files immediately, is to reduce the danger of deleting a file
0215: accidentally.  Until you direct Dired to delete the flagged files, you
0216: can remove deletion flags using the commands @kbd{u} and @key{DEL}.
0217: @kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes
0218: flags rather than making flags.  @key{DEL}
0219: (@code{dired-unmark-backward}) moves upward, removing flags; it is
0220: like @kbd{u} with argument @minus{}1.  A numeric prefix argument to
0221: either command serves as a repeat count, with a negative count meaning
0222: to unflag in the opposite direction.  If the region is active, these
0223: commands instead unflag all files in the region, without moving point.
0224: 
0225: @kindex x @r{(Dired)}
0226: @findex dired-do-flagged-delete
0227:   To delete flagged files, type @kbd{x}
0228: (@code{dired-do-flagged-delete}).  This command displays a list of all
0229: the file names flagged for deletion, and requests confirmation with
0230: @kbd{yes}.  If you confirm, Dired deletes the flagged files, then
0231: deletes their lines from the text of the Dired buffer.  The Dired
0232: buffer, with somewhat fewer lines, remains selected.
0233: 
0234:   If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
0235: return immediately to Dired, with the deletion flags still present in
0236: the buffer, and no files actually deleted.
0237: 
0238: @cindex recursive deletion
0239: @vindex dired-recursive-deletes
0240:   You can delete empty directories just like other files, but normally
0241: Dired cannot delete directories that are nonempty.  However, if the
0242: variable @code{dired-recursive-deletes} is non-@code{nil}, then Dired
0243: is allowed to delete nonempty directories including all their
0244: contents.  That can be somewhat risky.  If the value of the variable
0245: is @code{always}, Dired will delete nonempty directories recursively,
0246: which is even more risky.
0247: 
0248: Even if you have set @code{dired-recursive-deletes} to @code{nil}, you
0249: might want sometimes to delete directories recursively without being
0250: asked for confirmation for all of them.  For example, you may want
0251: that when you have marked many directories for deletion and you are
0252: very sure that all of them can safely be deleted.  For every nonempty
0253: directory you are asked for confirmation to delete, if you answer
0254: @code{all}, then all the remaining directories will be deleted without
0255: any further questions.
0256: 
0257: @vindex delete-by-moving-to-trash@r{, and Dired}
0258:   If you change the variable @code{delete-by-moving-to-trash} to
0259: @code{t}, the above deletion commands will move the affected files or
0260: directories into the operating system's Trash, instead of deleting
0261: them outright.  @xref{Misc File Ops}.
0262: 
0263:   An alternative way of deleting files is to mark them with @kbd{m}
0264: and delete with @kbd{D}, see @ref{Operating on Files}.
0265: 
0266: @node Flagging Many Files
0267: @section Flagging Many Files at Once
0268: @cindex flagging many files for deletion (in Dired)
0269: 
0270:   The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands
0271: flag many files for deletion, based on their file names:
0272: 
0273: @table @kbd
0274: @item #
0275: Flag all auto-save files (files whose names start and end with @samp{#})
0276: for deletion (@pxref{Auto Save}).
0277: 
0278: @item ~
0279: Flag all backup files (files whose names end with @samp{~}) for deletion
0280: (@pxref{Backup}).
0281: 
0282: @item .@: @r{(Period)}
0283: Flag excess numeric backup files for deletion.  The oldest and newest
0284: few backup files of any one file are exempt; the middle ones are
0285: flagged.
0286: 
0287: @item % &
0288: Flag for deletion all files with certain kinds of names which suggest
0289: you could easily create those files again.
0290: 
0291: @item % d @var{regexp} @key{RET}
0292: Flag for deletion all files whose names match the regular expression
0293: @var{regexp}.
0294: @end table
0295: 
0296: @kindex # @r{(Dired)}
0297: @findex dired-flag-auto-save-files
0298: @cindex deleting auto-save files
0299:   @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose
0300: names look like auto-save files---that is, files whose names begin and
0301: end with @samp{#}.  @xref{Auto Save}.
0302: 
0303: @kindex ~ @r{(Dired)}
0304: @findex dired-flag-backup-files
0305:   @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names
0306: say they are backup files---that is, files whose names end in
0307: @samp{~}.  @xref{Backup}.
0308: 
0309: @kindex . @r{(Dired)}
0310: @vindex dired-kept-versions
0311: @findex dired-clean-directory
0312:   @kbd{.} (period, @code{dired-clean-directory}) flags just some of
0313: the backup files for deletion: all but the oldest few and newest few
0314: backups of any one file.  Normally, the number of newest versions kept
0315: for each file is given by the variable @code{dired-kept-versions}
0316: (@emph{not} @code{kept-new-versions}; that applies only when saving).
0317: The number of oldest versions to keep is given by the variable
0318: @code{kept-old-versions}.
0319: 
0320:   Period with a positive numeric argument, as in @kbd{C-u 3 .},
0321: specifies the number of newest versions to keep, overriding
0322: @code{dired-kept-versions}.  A negative numeric argument overrides
0323: @code{kept-old-versions}, using minus the value of the argument to
0324: specify the number of oldest versions of each file to keep.
0325: 
0326: @kindex % & @r{(Dired)}
0327: @findex dired-flag-garbage-files
0328: @vindex dired-garbage-files-regexp
0329: @cindex deleting some backup files
0330:   @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names
0331: match the regular expression specified by the variable
0332: @code{dired-garbage-files-regexp}.  By default, this matches certain
0333: files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and
0334: @samp{.rej} files produced by @code{patch}.
0335: 
0336: @findex dired-flag-files-regexp
0337: @kindex % d @r{(Dired)}
0338:   @kbd{% d} flags all files whose names match a specified regular
0339: expression (@code{dired-flag-files-regexp}).  Only the non-directory
0340: part of the file name is used in matching.  You can use @samp{^} and
0341: @samp{$} to anchor matches.  You can exclude certain subdirectories
0342: from marking by hiding them while you use @kbd{% d}.  @xref{Hiding
0343: Subdirectories}.
0344: 
0345: @node Dired Visiting
0346: @section Visiting Files in Dired
0347: 
0348:   There are several Dired commands for visiting or examining the files
0349: listed in the Dired buffer.  All of them apply to the current line's
0350: file; if that file is really a directory, these commands invoke Dired on
0351: that subdirectory (making a separate Dired buffer).
0352: 
0353: @table @kbd
0354: @item f
0355: @kindex f @r{(Dired)}
0356: @findex dired-find-file
0357: Visit the file described on the current line, like typing @kbd{C-x C-f}
0358: and supplying that file name (@code{dired-find-file}).  @xref{Visiting}.
0359: 
0360: @item @key{RET}
0361: @itemx e
0362: @kindex RET @r{(Dired)}
0363: @kindex e @r{(Dired)}
0364: Equivalent to @kbd{f}.
0365: 
0366: @ignore  @c This command seems too risky to document at all.
0367: @item a
0368: @kindex a @r{(Dired)}
0369: @findex dired-find-alternate-file
0370: Like @kbd{f}, but replaces the contents of the Dired buffer with
0371: that of an alternate file or directory (@code{dired-find-alternate-file}).
0372: @end ignore
0373: 
0374: @item o
0375: @kindex o @r{(Dired)}
0376: @findex dired-find-file-other-window
0377: Like @kbd{f}, but uses another window to display the file's buffer
0378: (@code{dired-find-file-other-window}).  The Dired buffer remains visible
0379: in the first window.  This is like using @kbd{C-x 4 C-f} to visit the
0380: file.  @xref{Windows}.
0381: 
0382: @item C-o
0383: @kindex C-o @r{(Dired)}
0384: @findex dired-display-file
0385: Visit the file described on the current line, and display the buffer in
0386: another window, but do not select that window (@code{dired-display-file}).
0387: 
0388: @item mouse-1
0389: @itemx mouse-2
0390: @findex dired-mouse-find-file-other-window
0391: Visit the file whose name you clicked on
0392: (@code{dired-mouse-find-file-other-window}).  This uses another window
0393: to display the file, like the @kbd{o} command.
0394: 
0395: @item v
0396: @kindex v @r{(Dired)}
0397: @findex dired-view-file
0398: View the file described on the current line, with View mode
0399: (@code{dired-view-file}).  View mode provides convenient commands to
0400: navigate the buffer but forbids changing it; @xref{View Mode}.
0401: 
0402: @item ^
0403: @kindex ^ @r{(Dired)}
0404: @findex dired-up-directory
0405: Visit the parent directory of the current directory
0406: (@code{dired-up-directory}).  This is equivalent to moving to the line
0407: for @file{..} and typing @kbd{f} there.
0408: @end table
0409: 
0410: @node Marks vs Flags
0411: @section Dired Marks vs.@: Flags
0412: 
0413: @cindex marking many files (in Dired)
0414:   Instead of flagging a file with @samp{D}, you can @dfn{mark} the
0415: file with some other character (usually @samp{*}).  Most Dired
0416: commands to operate on files use the files marked with @samp{*}.  The
0417: only command that operates on flagged files is @kbd{x}, which deletes
0418: them.
0419: 
0420:   Here are some commands for marking with @samp{*}, for unmarking, and
0421: for operating on marks.  (@xref{Dired Deletion}, for commands to flag
0422: and unflag files.)
0423: 
0424: @table @kbd
0425: @item m
0426: @itemx * m
0427: @kindex m @r{(Dired)}
0428: @kindex * m @r{(Dired)}
0429: @findex dired-mark
0430: Mark the current file with @samp{*} (@code{dired-mark}).  If the
0431: region is active, mark all files in the region instead; otherwise, if
0432: a numeric argument @var{n} is supplied, mark the next @var{n} files
0433: instead, starting with the current file (if @var{n} is negative, mark
0434: the previous @minus{}@var{n} files).  If invoked on a subdirectory
0435: header line (@pxref{Subdirectories in Dired}), this command marks all
0436: the files in that subdirectory.
0437: 
0438: @item * *
0439: @kindex * * @r{(Dired)}
0440: @findex dired-mark-executables
0441: @cindex marking executable files (in Dired)
0442: Mark all executable files with @samp{*}
0443: (@code{dired-mark-executables}).  With a numeric argument, unmark all
0444: those files.
0445: 
0446: @item * @@
0447: @kindex * @@ @r{(Dired)}
0448: @findex dired-mark-symlinks
0449: @cindex marking symbolic links (in Dired)
0450: Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
0451: With a numeric argument, unmark all those files.
0452: 
0453: @item * /
0454: @kindex * / @r{(Dired)}
0455: @findex dired-mark-directories
0456: @cindex marking subdirectories (in Dired)
0457: Mark with @samp{*} all files which are directories, except for
0458: @file{.} and @file{..} (@code{dired-mark-directories}).  With a numeric
0459: argument, unmark all those files.
0460: 
0461: @item * s
0462: @kindex * s @r{(Dired)}
0463: @findex dired-mark-subdir-files
0464: Mark all the files in the current subdirectory, aside from @file{.}
0465: and @file{..} (@code{dired-mark-subdir-files}).
0466: 
0467: @item u
0468: @itemx * u
0469: @kindex u @r{(Dired)}
0470: @kindex * u @r{(Dired)}
0471: @findex dired-unmark
0472: Remove any mark on this line (@code{dired-unmark}).  If the region is
0473: active, unmark all files in the region instead; otherwise, if a
0474: numeric argument @var{n} is supplied, unmark the next @var{n} files
0475: instead, starting with the current file (if @var{n} is negative,
0476: unmark the previous @minus{}@var{n} files).
0477: 
0478: @item @key{DEL}
0479: @itemx * @key{DEL}
0480: @kindex * DEL @r{(Dired)}
0481: @findex dired-unmark-backward
0482: @cindex unmarking files (in Dired)
0483: Move point to previous line and remove any mark on that line
0484: (@code{dired-unmark-backward}).  If the region is active, unmark all
0485: files in the region instead; otherwise, if a numeric argument @var{n}
0486: is supplied, unmark the @var{n} preceding files instead, starting with
0487: the current file (if @var{n} is negative, unmark the next
0488: @minus{}@var{n} files).
0489: 
0490: @item * !
0491: @itemx U
0492: @kindex * ! @r{(Dired)}
0493: @kindex U @r{(Dired)}
0494: @findex dired-unmark-all-marks
0495: Remove all marks from all the files in this Dired buffer
0496: (@code{dired-unmark-all-marks}).
0497: 
0498: @item * ? @var{markchar}
0499: @itemx M-@key{DEL}
0500: @kindex * ? @r{(Dired)}
0501: @kindex M-DEL @r{(Dired)}
0502: @findex dired-unmark-all-files
0503: Remove all marks that use the character @var{markchar}
0504: (@code{dired-unmark-all-files}).  If invoked with @kbd{M-@key{DEL}},
0505: the command prompts for @var{markchar}.  That @var{markchar} is a
0506: single character---do not use @key{RET} to terminate it.  See the
0507: description of the @kbd{* c} command below, which lets you replace one
0508: mark character with another.
0509: 
0510: With a numeric argument, this command queries about each marked file,
0511: asking whether to remove its mark.  You can answer @kbd{y} meaning yes,
0512: @kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining
0513: files without asking about them.
0514: 
0515: @item * C-n
0516: @itemx M-@}
0517: @findex dired-next-marked-file
0518: @kindex * C-n @r{(Dired)}
0519: @kindex M-@} @r{(Dired)}
0520: Move down to the next marked file (@code{dired-next-marked-file}).
0521: A file is ``marked'' if it has any kind of mark.
0522: 
0523: @item * C-p
0524: @itemx M-@{
0525: @findex dired-prev-marked-file
0526: @kindex * C-p @r{(Dired)}
0527: @kindex M-@{ @r{(Dired)}
0528: Move up to the previous marked file (@code{dired-prev-marked-file}).
0529: 
0530: @item t
0531: @itemx * t
0532: @kindex t @r{(Dired)}
0533: @kindex * t @r{(Dired)}
0534: @findex dired-toggle-marks
0535: @cindex toggling marks (in Dired)
0536: Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*}
0537: become unmarked, and unmarked files are marked with @samp{*}.  Files
0538: marked in any other way are not affected.
0539: 
0540: @item * c @var{old-markchar} @var{new-markchar}
0541: @kindex * c @r{(Dired)}
0542: @findex dired-change-marks
0543: Replace all marks that use the character @var{old-markchar} with marks
0544: that use the character @var{new-markchar} (@code{dired-change-marks}).
0545: This command is the primary way to create or use marks other than
0546: @samp{*} or @samp{D}.  The arguments are single characters---do not use
0547: @key{RET} to terminate them.
0548: 
0549: You can use almost any character as a mark character by means of this
0550: command, to distinguish various classes of files.  If @var{old-markchar}
0551: is a space (@samp{ }), then the command operates on all unmarked files;
0552: if @var{new-markchar} is a space, then the command unmarks the files it
0553: acts on.
0554: 
0555: To illustrate the power of this command, here is how to put @samp{D}
0556: flags on all the files that have no marks, while unflagging all those
0557: that already have @samp{D} flags:
0558: 
0559: @example
0560: * c D t  * c @key{SPC} D  * c t @key{SPC}
0561: @end example
0562: 
0563: This assumes that no files were already marked with @samp{t}.
0564: 
0565: @item % m @var{regexp} @key{RET}
0566: @itemx * % @var{regexp} @key{RET}
0567: @findex dired-mark-files-regexp
0568: @kindex % m @r{(Dired)}
0569: @kindex * % @r{(Dired)}
0570: Mark (with @samp{*}) all files whose names match the regular expression
0571: @var{regexp} (@code{dired-mark-files-regexp}).  This command is like
0572: @kbd{% d}, except that it marks files with @samp{*} instead of flagging
0573: with @samp{D}.
0574: 
0575: Only the non-directory part of the file name is used in matching.  Use
0576: @samp{^} and @samp{$} to anchor matches.  You can exclude
0577: subdirectories by temporarily hiding them (@pxref{Hiding
0578: Subdirectories}).
0579: 
0580: @item % g @var{regexp} @key{RET}
0581: @findex dired-mark-files-containing-regexp
0582: @kindex % g @r{(Dired)}
0583: @cindex finding files containing regexp matches (in Dired)
0584: Mark (with @samp{*}) all files whose @emph{contents} contain a match for
0585: the regular expression @var{regexp}
0586: (@code{dired-mark-files-containing-regexp}).  This command is like
0587: @kbd{% m}, except that it searches the file contents instead of the file
0588: name.  Note that if a file is visited in an Emacs buffer,
0589: and @code{dired-always-read-filesystem} is @code{nil} (the default), this
0590: command will look in the buffer without revisiting the file, so the results
0591: might be inconsistent with the file on disk if its contents have changed
0592: since it was last visited.  If you don't want this, you may wish to
0593: revert the files you have visited in your buffers, or to turn on
0594: Auto-Revert mode in those buffers, before invoking this command.
0595: @xref{Reverting}.  If you prefer that this command should always
0596: revisit the file, without you having to revert the file or enable
0597: Auto-Revert mode, you might want to set
0598: @code{dired-always-read-filesystem} to non-@code{nil}.
0599: 
0600: @item C-/
0601: @itemx C-x u
0602: @itemx C-_
0603: @kindex C-_ @r{(Dired)}
0604: @findex dired-undo
0605: Undo changes in the Dired buffer, such as adding or removing
0606: marks (@code{dired-undo}).  @emph{This command does not revert the
0607: actual file operations, nor recover lost files!}  It just undoes
0608: changes in the buffer itself.
0609: 
0610: In some cases, using this after commands that operate on files can
0611: cause trouble.  For example, after renaming one or more files,
0612: @code{dired-undo} restores the original names in the Dired buffer,
0613: which gets the Dired buffer out of sync with the actual contents of
0614: the directory.
0615: @end table
0616: 
0617: @node Operating on Files
0618: @section Operating on Files
0619: @cindex operating on files in Dired
0620: 
0621:   This section describes the basic Dired commands to operate on one file
0622: or several files.  All of these commands are capital letters; all of
0623: them use the minibuffer, either to read an argument or to ask for
0624: confirmation, before they act.  All of them let you specify the
0625: files to manipulate in these ways:
0626: 
0627: @itemize @bullet
0628: @item
0629: If you give the command a numeric prefix argument @var{n}, it operates
0630: on the next @var{n} files, starting with the current file.  (If @var{n}
0631: is negative, the command operates on the @minus{}@var{n} files preceding
0632: the current line.)
0633: 
0634: @item
0635: Otherwise, if some files are marked with @samp{*}, the command operates
0636: on all those files.
0637: 
0638: @item
0639: Otherwise, the command operates on the current file only.
0640: @end itemize
0641: 
0642: @noindent
0643: Certain other Dired commands, such as @kbd{!} and the @samp{%}
0644: commands, use the same conventions to decide which files to work on.
0645: 
0646: @vindex dired-dwim-target
0647: @cindex two directories (in Dired)
0648:   Commands which ask for a destination directory, such as those which
0649: copy and rename files or create links for them, try to guess the default
0650: target directory for the operation.  Normally, they suggest the Dired
0651: buffer's default directory, but if the variable @code{dired-dwim-target}
0652: is non-@code{nil}, and if there is another Dired buffer displayed in the
0653: next window, that other buffer's directory is suggested instead.
0654: 
0655:   Here are the file-manipulating Dired commands that operate on files.
0656: 
0657: @table @kbd
0658: @findex dired-do-copy
0659: @kindex C @r{(Dired)}
0660: @cindex copying files (in Dired)
0661: @item C @var{new} @key{RET}
0662: Copy the specified files (@code{dired-do-copy}).  The argument @var{new}
0663: is the directory to copy into, or (if copying a single file) the new
0664: name.  This is like the shell command @code{cp}.
0665: 
0666: @vindex dired-create-destination-dirs
0667: The option @code{dired-create-destination-dirs} controls whether Dired
0668: should create non-existent directories in the destination while
0669: copying/renaming files.  The default value @code{nil} means Dired
0670: never creates such missing directories;  the value @code{always},
0671: means Dired automatically creates them; the value @code{ask}
0672: means Dired asks you for confirmation before creating them.
0673: 
0674: @vindex dired-copy-preserve-time
0675: If @code{dired-copy-preserve-time} is non-@code{nil}, then copying
0676: with this command preserves the modification time of the old file in
0677: the copy, like @samp{cp -p}.
0678: 
0679: @vindex dired-recursive-copies
0680: @cindex recursive copying
0681: The variable @code{dired-recursive-copies} controls whether to copy
0682: directories recursively (like @samp{cp -r}).  The default is
0683: @code{top}, which means to ask before recursively copying a directory.
0684: 
0685: @item D
0686: @findex dired-do-delete
0687: @kindex D @r{(Dired)}
0688: Delete the specified files (@code{dired-do-delete}).  This is like the
0689: shell command @code{rm}.
0690: 
0691: Like the other commands in this section, this command operates on the
0692: @emph{marked} files, or the next @var{n} files.  By contrast, @kbd{x}
0693: (@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files.
0694: 
0695: @findex dired-do-rename
0696: @kindex R @r{(Dired)}
0697: @cindex renaming files (in Dired)
0698: @cindex moving files (in Dired)
0699: @item R @var{new} @key{RET}
0700: Rename the specified files (@code{dired-do-rename}).  If you rename a
0701: single file, the argument @var{new} is the new name of the file.  If
0702: you rename several files, the argument @var{new} is the directory into
0703: which to move the files (this is like the shell command @command{mv}).
0704: 
0705: The option @code{dired-create-destination-dirs} controls whether Dired
0706: should create non-existent directories in @var{new}.
0707: 
0708: Dired automatically changes the visited file name of buffers associated
0709: with renamed files so that they refer to the new names.
0710: 
0711: @findex dired-do-hardlink
0712: @kindex H @r{(Dired)}
0713: @cindex hard links (in Dired)
0714: @item H @var{new} @key{RET}
0715: Make hard links to the specified files (@code{dired-do-hardlink}).
0716: This is like the shell command @command{ln}.  The argument @var{new} is
0717: the directory to make the links in, or (if making just one link) the
0718: name to give the link.
0719: 
0720: @findex dired-do-symlink
0721: @kindex S @r{(Dired)}
0722: @cindex symbolic links (creation in Dired)
0723: @item S @var{new} @key{RET}
0724: Make symbolic links to the specified files (@code{dired-do-symlink}).
0725: This is like @samp{ln -s}.  The argument @var{new} is the directory to
0726: make the links in, or (if making just one link) the name to give the
0727: link.
0728: 
0729: @findex dired-do-chmod
0730: @kindex M @r{(Dired)}
0731: @cindex changing file permissions (in Dired)
0732: @item M @var{modespec} @key{RET}
0733: Change the mode (also called @dfn{permission bits}) of the specified
0734: files (@code{dired-do-chmod}).  @var{modespec} can be in octal or
0735: symbolic notation, like arguments handled by the @command{chmod}
0736: program.
0737: 
0738: @findex dired-do-chgrp
0739: @kindex G @r{(Dired)}
0740: @cindex changing file group (in Dired)
0741: @item G @var{newgroup} @key{RET}
0742: Change the group of the specified files to @var{newgroup}
0743: (@code{dired-do-chgrp}).
0744: 
0745: @findex dired-do-chown
0746: @kindex O @r{(Dired)}
0747: @cindex changing file owner (in Dired)
0748: @item O @var{newowner} @key{RET}
0749: Change the owner of the specified files to @var{newowner}
0750: (@code{dired-do-chown}).  (On most systems, only the superuser can do
0751: this.)
0752: 
0753: @vindex dired-chown-program
0754: The variable @code{dired-chown-program} specifies the name of the
0755: program to use to do the work.  (This variable is necessary because
0756: different systems put @command{chown} in different places).
0757: 
0758: @findex dired-do-touch
0759: @kindex T @r{(Dired)}
0760: @cindex changing file time (in Dired)
0761: @item T @var{timestamp} @key{RET}
0762: Touch the specified files (@code{dired-do-touch}).  This means
0763: updating their modification times to the present time.  This is like
0764: the shell command @code{touch}.
0765: 
0766: @findex dired-do-print
0767: @kindex P @r{(Dired)}
0768: @cindex printing files (in Dired)
0769: @item P @var{command} @key{RET}
0770: Print the specified files (@code{dired-do-print}).  You must specify the
0771: command to print them with, but the minibuffer starts out with a
0772: suitable guess made using the variables @code{lpr-command} and
0773: @code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
0774: @pxref{Printing}).
0775: 
0776: @findex dired-do-compress
0777: @kindex Z @r{(Dired)}
0778: @cindex compressing files (in Dired)
0779: @item Z
0780: Compress the specified files (@code{dired-do-compress}).  If the file
0781: appears to be a compressed file already, uncompress it instead.  Each
0782: marked file is compressed into its own archive; this uses the
0783: @command{gzip} program if it is available, otherwise it uses
0784: @command{compress}.  On a directory name, this command produces a
0785: compressed @file{.tar.gz} archive containing all of the directory's
0786: files, by running the @command{tar} command with output piped to
0787: @command{gzip}.  To allow decompression of compressed directories,
0788: typing @kbd{Z} on a @file{.tar.gz} or @file{.tgz} archive file unpacks
0789: all the files in the archive into a directory whose name is the
0790: archive name with the extension removed.
0791: 
0792: @findex dired-do-compress-to
0793: @kindex c @r{(Dired)}
0794: @item c
0795: Compress the specified files (@code{dired-do-compress-to}) into a
0796: single archive anywhere on the file system. The compression algorithm
0797: is determined by the extension of the archive, see
0798: @code{dired-compress-files-alist}.
0799: 
0800: @findex epa-dired-do-decrypt
0801: @kindex :d @r{(Dired)}
0802: @cindex decrypting files (in Dired)
0803: @item :d
0804: Decrypt the specified files (@code{epa-dired-do-decrypt}).
0805: @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
0806: 
0807: @findex epa-dired-do-verify
0808: @kindex :v @r{(Dired)}
0809: @cindex verifying digital signatures on files (in Dired)
0810: @item :v
0811: Verify digital signatures on the specified files (@code{epa-dired-do-verify}).
0812: @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
0813: 
0814: @findex epa-dired-do-sign
0815: @kindex :s @r{(Dired)}
0816: @cindex signing files (in Dired)
0817: @item :s
0818: Digitally sign the specified files (@code{epa-dired-do-sign}).
0819: @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
0820: 
0821: @findex epa-dired-do-encrypt
0822: @kindex :e @r{(Dired)}
0823: @cindex encrypting files (in Dired)
0824: @item :e
0825: Encrypt the specified files (@code{epa-dired-do-encrypt}).
0826: @xref{Dired integration,,, epa, EasyPG Assistant User's Manual}.
0827: 
0828: @findex dired-do-load
0829: @kindex L @r{(Dired)}
0830: @cindex loading several files (in Dired)
0831: @item L
0832: Load the specified Emacs Lisp files (@code{dired-do-load}).
0833: @xref{Lisp Libraries}.
0834: 
0835: @findex dired-do-byte-compile
0836: @kindex B @r{(Dired)}
0837: @cindex byte-compiling several files (in Dired)
0838: @item B
0839: Byte compile the specified Emacs Lisp files
0840: (@code{dired-do-byte-compile}).  @xref{Byte Compilation,, Byte
0841: Compilation, elisp, The Emacs Lisp Reference Manual}.
0842: 
0843: @kindex A @r{(Dired)}
0844: @findex dired-do-find-regexp
0845: @cindex search multiple files (in Dired)
0846: @item A @var{regexp} @key{RET}
0847: Search all the specified files for the regular expression @var{regexp}
0848: (@code{dired-do-find-regexp}).
0849: 
0850: This command is a variant of @code{xref-find-references}
0851: (@pxref{Identifier Search}), it displays the @file{*xref*} buffer,
0852: where you can navigate between matches and display them as needed
0853: using the commands described in @ref{Xref Commands}.
0854: 
0855: @vindex grep-find-ignored-files @r{(Dired)}
0856: @vindex grep-find-ignored-directories @r{(Dired)}
0857: If any of the marked files are directories, then this command searches
0858: all of the files in those directories, and any of their
0859: subdirectories, recursively, except files whose names match
0860: @code{grep-find-ignored-files} and subdirectories whose names match
0861: @code{grep-find-ignored-directories}.
0862: 
0863: @kindex Q @r{(Dired)}
0864: @findex dired-do-find-regexp-and-replace
0865: @cindex search and replace in multiple files (in Dired)
0866: @item Q @var{regexp} @key{RET} @var{to} @key{RET}
0867: Perform @code{query-replace-regexp} on each of the specified files,
0868: replacing matches for @var{regexp} with the string
0869: @var{to} (@code{dired-do-find-regexp-and-replace}).
0870: 
0871: This command is a variant of @code{xref-query-replace-in-results}.  It
0872: presents an @file{*xref*} buffer that lists all the matches of @var{regexp},
0873: and you can use the special commands in that buffer (@pxref{Xref
0874: Commands}).  In particular, if you exit the query replace loop, you
0875: can use @kbd{r} in that buffer to replace more matches.
0876: @xref{Identifier Search}.
0877: 
0878: Like with @code{dired-do-find-regexp}, if any of the marked files are
0879: directories, this command performs replacements in all of the files in
0880: those directories, and in any of their subdirectories, recursively,
0881: except for files whose names match @code{grep-find-ignored-files} and
0882: subdirectories whose names match @code{grep-find-ignored-directories}.
0883: @end table
0884: 
0885: @node Shell Commands in Dired
0886: @section Shell Commands in Dired
0887: @cindex shell commands, Dired
0888: 
0889: @findex dired-do-shell-command
0890: @kindex ! @r{(Dired)}
0891: @kindex X @r{(Dired)}
0892: The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a
0893: shell command string in the minibuffer, and runs that shell command on
0894: one or more files.  The files that the shell command operates on are
0895: determined in the usual way for Dired commands (@pxref{Operating on
0896: Files}).  The command @kbd{X} is a synonym for @kbd{!}.
0897: 
0898:   The command @kbd{&} (@code{dired-do-async-shell-command}) does the
0899: same, except that it runs the shell command asynchronously.  (You can
0900: also do this with @kbd{!}, by appending a @samp{&} character to the
0901: end of the shell command.)  When the command operates on more than one
0902: file, it runs multiple parallel copies of the specified shell command,
0903: one for each file.  As an exception, if the specified shell command
0904: ends in @samp{;} or @samp{;&}, the shell command is run in the
0905: background on each file sequentially; Emacs waits for each invoked
0906: shell command to terminate before running the next one.
0907: 
0908:   For both @kbd{!} and @kbd{&}, the working directory for the shell
0909: command is the top-level directory of the Dired buffer.
0910: 
0911:   If you tell @kbd{!} or @kbd{&} to operate on more than one file, the
0912: shell command string determines how those files are passed to the
0913: shell command:
0914: 
0915: @itemize @bullet
0916: @item
0917: If you use @samp{*} surrounded by whitespace in the command string,
0918: then the command runs just once, with the list of file names
0919: substituted for the @samp{*}.  The order of file names is the order of
0920: appearance in the Dired buffer.
0921: 
0922: Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
0923: list of file names, putting them into one tar file @file{foo.tar}.
0924: 
0925: If you want to use @samp{*} as a shell wildcard with whitespace around
0926: it, write @samp{*""}.  In the shell, this is equivalent to @samp{*};
0927: but since the @samp{*} is not surrounded by whitespace, Dired does not
0928: treat it specially.
0929: 
0930: @item
0931: Otherwise, if the command string contains @samp{?} surrounded by
0932: whitespace or @samp{`?`}, Emacs runs the shell command once
0933: @emph{for each file}, substituting the current file name for @samp{?}
0934: and @samp{`?`} each time.  You can use both @samp{?} and @samp{`?`} more
0935: than once in the command; the same file name replaces each occurrence.
0936: If you mix them with @samp{*} the command signals an error.
0937: 
0938: @item
0939: If the command string contains neither @samp{*} nor @samp{?} nor @samp{`?`},
0940: Emacs runs the shell command once for each file, adding the file name at the
0941: end.  For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on
0942: each file.
0943: @end itemize
0944: 
0945:   To iterate over the file names in a more complicated fashion, you might
0946: prefer to use an explicit shell loop.  For example, here is how to uuencode
0947: each file, making the output file name by appending @samp{.uu} to the input
0948: file name:
0949: 
0950: @example
0951: for file in * ; do uuencode "$file" "$file" >"$file".uu; done
0952: @end example
0953: 
0954: The same example with @samp{`?`} notation:
0955: @example
0956: uuencode ? ? > `?`.uu
0957: @end example
0958: 
0959:   The @kbd{!} and @kbd{&} commands do not attempt to update the Dired
0960: buffer to show new or modified files, because they don't know what
0961: files will be changed.  Use the @kbd{g} command to update the Dired
0962: buffer (@pxref{Dired Updating}).
0963: 
0964:   @xref{Single Shell}, for information about running shell commands
0965: outside Dired.
0966: 
0967: @node Transforming File Names
0968: @section Transforming File Names in Dired
0969: 
0970:   This section describes Dired commands which alter file names in a
0971: systematic way.  Each command operates on some or all of the marked
0972: files, using a new name made by transforming the existing name.
0973: 
0974:   Like the basic Dired file-manipulation commands (@pxref{Operating on
0975: Files}), the commands described here operate either on the next
0976: @var{n} files, or on all files marked with @samp{*}, or on the current
0977: file.  (To mark files, use the commands described in @ref{Marks vs
0978: Flags}.)
0979: 
0980:   All of the commands described in this section work
0981: @emph{interactively}: they ask you to confirm the operation for each
0982: candidate file.  Thus, you can select more files than you actually
0983: need to operate on (e.g., with a regexp that matches many files), and
0984: then filter the selected names by typing @kbd{y} or @kbd{n} when the
0985: command prompts for confirmation.
0986: 
0987: @table @kbd
0988: @findex dired-upcase
0989: @kindex % u @r{(Dired)}
0990: @cindex upcase file names
0991: @item % u
0992: Rename each of the selected files to an upper-case name
0993: (@code{dired-upcase}).  If the old file names are @file{Foo}
0994: and @file{bar}, the new names are @file{FOO} and @file{BAR}.
0995: 
0996: @item % l
0997: @findex dired-downcase
0998: @kindex % l @r{(Dired)}
0999: @cindex downcase file names
1000: Rename each of the selected files to a lower-case name
1001: (@code{dired-downcase}).  If the old file names are @file{Foo} and
1002: @file{bar}, the new names are @file{foo} and @file{bar}.
1003: 
1004: @item % R @var{from} @key{RET} @var{to} @key{RET}
1005: @kindex % R @r{(Dired)}
1006: @findex dired-do-rename-regexp
1007: @itemx % C @var{from} @key{RET} @var{to} @key{RET}
1008: @kindex % C @r{(Dired)}
1009: @findex dired-do-copy-regexp
1010: @itemx % H @var{from} @key{RET} @var{to} @key{RET}
1011: @kindex % H @r{(Dired)}
1012: @findex dired-do-hardlink-regexp
1013: @itemx % S @var{from} @key{RET} @var{to} @key{RET}
1014: @kindex % S @r{(Dired)}
1015: @findex dired-do-symlink-regexp
1016: These four commands rename, copy, make hard links and make soft links,
1017: in each case computing the new name by regular-expression substitution
1018: from the name of the old file.
1019: @end table
1020: 
1021:   The four regular-expression substitution commands effectively
1022: perform a search-and-replace on the selected file names.  They read
1023: two arguments: a regular expression @var{from}, and a substitution
1024: pattern @var{to}; they match each old file name against
1025: @var{from}, and then replace the matching part with @var{to}.  You can
1026: use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or
1027: part of what the pattern matched in the old file name, as in
1028: @code{replace-regexp} (@pxref{Regexp Replace}).  If the regular
1029: expression matches more than once in a file name, only the first match
1030: is replaced.
1031: 
1032:   For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
1033: selected file by prepending @samp{x-} to its name.  The inverse of this,
1034: removing @samp{x-} from the front of each file name, is also possible:
1035: one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is
1036: @kbd{% R ^x- @key{RET} @key{RET}}.  (Use @samp{^} and @samp{$} to anchor
1037: matches that should span the whole file name.)
1038: 
1039:   Normally, the replacement process does not consider the files'
1040: directory names; it operates on the file name within the directory.  If
1041: you specify a numeric argument of zero, then replacement affects the
1042: entire absolute file name including directory name.  (A non-zero
1043: argument specifies the number of files to operate on.)
1044: 
1045:   You may want to select the set of files to operate on using the same
1046: regexp @var{from} that you will use to operate on them.  To do this,
1047: mark those files with @kbd{% m @var{from} @key{RET}}, then use the
1048: same regular expression in the command to operate on the files.  To
1049: make this more convenient, the @kbd{%} commands to operate on files
1050: use the last regular expression specified in any @kbd{%} command as a
1051: default.
1052: 
1053: @node Comparison in Dired
1054: @section File Comparison with Dired
1055: @cindex file comparison (in Dired)
1056: @cindex compare files (in Dired)
1057: 
1058: @findex dired-diff
1059: @kindex = @r{(Dired)}
1060:   The @kbd{=} (@code{dired-diff}) command compares the current file
1061: (the file at point) with another file (read using the minibuffer)
1062: using the @command{diff} program.  The file specified with the
1063: minibuffer is the first argument of @command{diff}, and file at point
1064: is the second argument.  The output of the @command{diff} program is
1065: shown in a buffer using Diff mode (@pxref{Comparing Files}).
1066: 
1067:   If the region is active, the default for the file read using the
1068: minibuffer is the file at the mark (i.e., the ordinary Emacs mark,
1069: not a Dired mark; @pxref{Setting Mark}).  Otherwise, if the file at
1070: point has a backup file (@pxref{Backup}), that is the default.
1071: 
1072:   You could also compare files using @code{ediff-files}, see
1073: @ref{Major Entry Points,,, ediff, Ediff User's Manual}.
1074: 
1075: @node Subdirectories in Dired
1076: @section Subdirectories in Dired
1077: @cindex subdirectories in Dired
1078: @cindex expanding subdirectories in Dired
1079: 
1080:   A Dired buffer usually displays just one directory, but you can
1081: optionally include its subdirectories as well.
1082: 
1083:   The simplest way to include multiple directories in one Dired buffer is
1084: to specify the options @samp{-lR} for running @command{ls}.  (If you give a
1085: numeric argument when you run Dired, then you can specify these options
1086: in the minibuffer.)  That produces a recursive directory listing showing
1087: all subdirectories at all levels.
1088: 
1089:   More often, you will want to show only specific subdirectories.  You
1090: can do this with @kbd{i} (@code{dired-maybe-insert-subdir}):
1091: 
1092: @table @kbd
1093: @findex dired-maybe-insert-subdir
1094: @kindex i @r{(Dired)}
1095: @item i
1096: @cindex inserted subdirectory (Dired)
1097: @cindex in-situ subdirectory (Dired)
1098: Insert the contents of a subdirectory later in the buffer.
1099: @end table
1100: 
1101: @noindent
1102: If you use this command on a line that describes a file which is a
1103: directory, it inserts the contents of that directory into the same
1104: Dired buffer, and moves there.  Inserted subdirectory contents follow
1105: the top-level directory of the Dired buffer, just as they do in
1106: @samp{ls -lR} output.
1107: 
1108:   If the subdirectory's contents are already present in the buffer,
1109: the @kbd{i} command just moves to it.
1110: 
1111:   In either case, @kbd{i} sets the Emacs mark before moving, so
1112: @kbd{C-u C-@key{SPC}} returns to your previous position in the Dired
1113: buffer (@pxref{Setting Mark}).  You can also use @samp{^} to return to
1114: the parent directory in the same Dired buffer (@pxref{Dired
1115: Visiting}).
1116: 
1117:   Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
1118: subdirectory's contents, and use @kbd{C-u k} on the subdirectory
1119: header line to remove the subdirectory listing (@pxref{Dired
1120: Updating}).  You can also hide and show inserted subdirectories
1121: (@pxref{Hiding Subdirectories}).
1122: 
1123: @ifnottex
1124: @include dired-xtra.texi
1125: @end ifnottex
1126: 
1127: @node Subdirectory Motion
1128: @section Moving Over Subdirectories
1129: 
1130:   When a Dired buffer lists subdirectories, you can use the page motion
1131: commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories
1132: (@pxref{Pages}).
1133: 
1134: @cindex header line (Dired)
1135: @cindex directory header lines
1136:   The following commands move across, up and down in the tree of
1137: directories within one Dired buffer.  They move to @dfn{directory header
1138: lines}, which are the lines that give a directory's name, at the
1139: beginning of the directory's contents.
1140: 
1141: @table @kbd
1142: @findex dired-next-subdir
1143: @kindex C-M-n @r{(Dired)}
1144: @item C-M-n
1145: Go to next subdirectory header line, regardless of level
1146: (@code{dired-next-subdir}).
1147: 
1148: @findex dired-prev-subdir
1149: @kindex C-M-p @r{(Dired)}
1150: @item C-M-p
1151: Go to previous subdirectory header line, regardless of level
1152: (@code{dired-prev-subdir}).
1153: 
1154: @findex dired-tree-up
1155: @kindex C-M-u @r{(Dired)}
1156: @item C-M-u
1157: Go up to the parent directory's header line (@code{dired-tree-up}).
1158: 
1159: @findex dired-tree-down
1160: @kindex C-M-d @r{(Dired)}
1161: @item C-M-d
1162: Go down in the directory tree, to the first subdirectory's header line
1163: (@code{dired-tree-down}).
1164: 
1165: @findex dired-prev-dirline
1166: @kindex < @r{(Dired)}
1167: @item <
1168: Move up to the previous directory-file line (@code{dired-prev-dirline}).
1169: These lines are the ones that describe a directory as a file in its
1170: parent directory.
1171: 
1172: @findex dired-next-dirline
1173: @kindex > @r{(Dired)}
1174: @item >
1175: Move down to the next directory-file line (@code{dired-next-dirline}).
1176: @end table
1177: 
1178: @node Hiding Subdirectories
1179: @section Hiding Subdirectories
1180: @cindex hiding subdirectories (Dired)
1181: @cindex showing hidden subdirectories (Dired)
1182: 
1183:   @dfn{Hiding} a subdirectory means to make it invisible, except for its
1184: header line.
1185: 
1186: @table @kbd
1187: @item $
1188: @findex dired-hide-subdir
1189: @kindex $ @r{(Dired)}
1190: Hide or show the subdirectory that point is in, and move point to the
1191: next subdirectory (@code{dired-hide-subdir}).  This is a toggle.  A
1192: numeric argument serves as a repeat count.
1193: 
1194: @item M-$
1195: @findex dired-hide-all
1196: @kindex M-$ @r{(Dired)}
1197: Hide all subdirectories in this Dired buffer, leaving only their header
1198: lines (@code{dired-hide-all}).  Or, if any subdirectory is currently
1199: hidden, make all subdirectories visible again.  You can use this command
1200: to get an overview in very deep directory trees or to move quickly to
1201: subdirectories far away.
1202: @end table
1203: 
1204:   Ordinary Dired commands never consider files inside a hidden
1205: subdirectory.  For example, the commands to operate on marked files
1206: ignore files in hidden directories even if they are marked.  Thus you
1207: can use hiding to temporarily exclude subdirectories from operations
1208: without having to remove the Dired marks on files in those
1209: subdirectories.
1210: 
1211: @xref{Subdirectories in Dired}, for how to insert a subdirectory
1212: listing, and see @ref{Dired Updating}, for how to delete it.
1213: 
1214: @node Dired Updating
1215: @section Updating the Dired Buffer
1216: @cindex updating Dired buffer
1217: @cindex refreshing displayed files
1218: 
1219:   This section describes commands to update the Dired buffer to reflect
1220: outside (non-Dired) changes in the directories and files, and to delete
1221: part of the Dired buffer.
1222: 
1223: @table @kbd
1224: @item g
1225: Update the entire contents of the Dired buffer (@code{revert-buffer}).
1226: 
1227: @item l
1228: Update the specified files (@code{dired-do-redisplay}).  You specify the
1229: files for @kbd{l} in the same way as for file operations.
1230: 
1231: @item k
1232: Delete the specified @emph{file lines}---not the files, just the lines
1233: (@code{dired-do-kill-lines}).
1234: 
1235: @item s
1236: Toggle between alphabetical order and date/time order
1237: (@code{dired-sort-toggle-or-edit}).
1238: 
1239: @item C-u s @var{switches} @key{RET}
1240: Refresh the Dired buffer using @var{switches} as
1241: @code{dired-listing-switches}.
1242: @end table
1243: 
1244: @kindex g @r{(Dired)}
1245: @findex revert-buffer @r{(Dired)}
1246:   Type @kbd{g} (@code{revert-buffer}) to update the contents of the
1247: Dired buffer, based on changes in the files and directories listed.
1248: This preserves all marks except for those on files that have vanished.
1249: Hidden subdirectories are updated but remain hidden.
1250: 
1251: @kindex l @r{(Dired)}
1252: @findex dired-do-redisplay
1253:   To update only some of the files, type @kbd{l}
1254: (@code{dired-do-redisplay}).  Like the Dired file-operating commands,
1255: this command operates on the next @var{n} files (or previous
1256: @minus{}@var{n} files), or on the marked files if any, or on the
1257: current file.  Updating the files means reading their current status,
1258: then updating their lines in the buffer to indicate that status.
1259: 
1260:   If you use @kbd{l} on a subdirectory header line, it updates the
1261: contents of the corresponding subdirectory.
1262: 
1263: @vindex dired-auto-revert-buffer
1264:   If you use @kbd{C-x d} or some other Dired command to visit a
1265: directory that is already being shown in a Dired buffer, Dired
1266: switches to that buffer but does not update it.  If the buffer is not
1267: up-to-date, Dired displays a warning telling you to type @kbd{g} to
1268: update it.  You can also tell Emacs to revert each Dired buffer
1269: automatically when you revisit it, by setting the variable
1270: @code{dired-auto-revert-buffer} to a non-@code{nil} value.
1271: 
1272: @kindex k @r{(Dired)}
1273: @findex dired-do-kill-lines
1274:   To delete @emph{file lines} from the buffer---without actually
1275: deleting the files---type @kbd{k} (@code{dired-do-kill-lines}).  Like
1276: the file-operating commands, this command operates on the next @var{n}
1277: files, or on the marked files if any.  However, it does not operate on
1278: the current file, since otherwise mistyping @kbd{k} could be annoying.
1279: 
1280:   If you use @kbd{k} to kill the line for a directory file which you
1281: had inserted in the Dired buffer as a subdirectory
1282: (@pxref{Subdirectories in Dired}), it removes the subdirectory listing
1283: as well.  Typing @kbd{C-u k} on the header line for a subdirectory
1284: also removes the subdirectory line from the Dired buffer.
1285: 
1286:   The @kbd{g} command brings back any individual lines that you have
1287: killed in this way, but not subdirectories---you must use @kbd{i} to
1288: reinsert a subdirectory.
1289: 
1290: @cindex Dired sorting
1291: @cindex sorting Dired buffer
1292: @kindex s @r{(Dired)}
1293: @findex dired-sort-toggle-or-edit
1294:   The files in a Dired buffers are normally listed in alphabetical order
1295: by file names.  Alternatively Dired can sort them by date/time.  The
1296: Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches
1297: between these two sorting modes.  The mode line in a Dired buffer
1298: indicates which way it is currently sorted---by name, or by date.
1299: 
1300:   @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for
1301: @code{dired-listing-switches}.
1302: 
1303: @node Dired and Find
1304: @section Dired and @code{find}
1305: @cindex @code{find} and Dired
1306: 
1307:   You can select a set of files for display in a Dired buffer more
1308: flexibly by using the @command{find} utility to choose the files.
1309: 
1310: @findex find-name-dired
1311:   To search for files with names matching a wildcard pattern use
1312: @kbd{M-x find-name-dired}.  It reads arguments @var{directory} and
1313: @var{pattern}, and chooses all the files in @var{directory} or its
1314: subdirectories whose individual names match @var{pattern}.
1315: 
1316:   The files thus chosen are displayed in a Dired buffer, in which the
1317: ordinary Dired commands are available.
1318: 
1319: @findex find-grep-dired
1320:   If you want to test the contents of files, rather than their names,
1321: use @kbd{M-x find-grep-dired}.  This command reads two minibuffer
1322: arguments, @var{directory} and @var{regexp}; it chooses all the files
1323: in @var{directory} or its subdirectories that contain a match for
1324: @var{regexp}.  It works by running the programs @command{find} and
1325: @command{grep}.  See also @kbd{M-x grep-find}, in @ref{Grep
1326: Searching}.  Remember to write the regular expression for
1327: @command{grep}, not for Emacs.  (An alternative method of showing
1328: files whose contents match a given regexp is the @kbd{% g
1329: @var{regexp}} command, see @ref{Marks vs Flags}.)
1330: 
1331: @findex find-dired
1332:   The most general command in this series is @kbd{M-x find-dired},
1333: which lets you specify any condition that @command{find} can test.  It
1334: takes two minibuffer arguments, @var{directory} and @var{find-args};
1335: it runs @command{find} in @var{directory}, passing @var{find-args} to
1336: tell @command{find} what condition to test.  To use this command, you
1337: need to know how to use @command{find}.
1338: 
1339: @vindex find-ls-option
1340:   The format of listing produced by these commands is controlled by
1341: the variable @code{find-ls-option}.  This is a pair of options; the
1342: first specifying how to call @command{find} to produce the file listing,
1343: and the second telling Dired to parse the output.
1344: 
1345: @findex locate
1346: @findex locate-with-filter
1347: @cindex file database (locate)
1348: @vindex locate-command
1349:   The command @kbd{M-x locate} provides a similar interface to the
1350: @command{locate} program.  @kbd{M-x locate-with-filter} is similar, but
1351: keeps only files whose names match a given regular expression.
1352: 
1353:   These buffers don't work entirely like ordinary Dired buffers: file
1354: operations work, but do not always automatically update the buffer.
1355: Reverting the buffer with @kbd{g} deletes all inserted subdirectories,
1356: and erases all flags and marks.
1357: 
1358: @node Wdired
1359: @section Editing the Dired Buffer
1360: 
1361: @cindex wdired mode
1362: @findex wdired-change-to-wdired-mode
1363:   Wdired is a special mode that allows you to perform file operations
1364: by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands
1365: for ``writable'').  To enter Wdired mode, type @kbd{C-x C-q}
1366: (@code{dired-toggle-read-only}) while in a Dired buffer.
1367: Alternatively, use the @samp{Immediate / Edit File Names} menu item.
1368: 
1369: @findex wdired-finish-edit
1370:   While in Wdired mode, you can rename files by editing the file names
1371: displayed in the Dired buffer.  All the ordinary Emacs editing
1372: commands, including rectangle operations and @code{query-replace}, are
1373: available for this.  Once you are done editing, type @kbd{C-c C-c}
1374: (@code{wdired-finish-edit}).  This applies your changes and switches
1375: back to ordinary Dired mode.
1376: 
1377:   Apart from simply renaming files, you can move a file to another
1378: directory by typing in the new file name (either absolute or
1379: relative).  To mark a file for deletion, delete the entire file name.
1380: To change the target of a symbolic link, edit the link target name
1381: which appears next to the link name.
1382: 
1383:   If you edit the file names to create a new subdirectory, Wdired will
1384: automatically create these new directories.  To inhibit this behavior,
1385: set @code{wdired-create-parent-directories} to @code{nil}.
1386: 
1387:   The rest of the text in the buffer, such as the file sizes and
1388: modification dates, is marked read-only, so you can't edit it.
1389: However, if you set @code{wdired-allow-to-change-permissions} to
1390: @code{t}, you can edit the file permissions.  For example, you can
1391: change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file
1392: world-writable.  These changes also take effect when you type @kbd{C-c
1393: C-c}.
1394: 
1395: @node Image-Dired
1396: @section Viewing Image Thumbnails in Dired
1397: @cindex @code{image-dired} mode
1398: @cindex @code{image-dired}
1399: 
1400:   Image-Dired is a facility for browsing image files.  It provides viewing
1401: the images either as thumbnails or in full size, either inside Emacs
1402: or through an external viewer.
1403: 
1404: @kindex C-t d @r{(Image-Dired)}
1405: @findex image-dired-display-thumbs
1406:   To enter Image-Dired, mark the image files you want to look at in
1407: the Dired buffer, using @kbd{m} as usual.  Then type @kbd{C-t d}
1408: (@code{image-dired-display-thumbs}).  This creates and switches to a
1409: buffer containing image-dired, corresponding to the marked files.
1410: 
1411:   You can also enter Image-Dired directly by typing @kbd{M-x
1412: image-dired}.  This prompts for a directory; specify one that has
1413: image files.  This creates thumbnails for all the images in that
1414: directory, and displays them all in the thumbnail buffer.  This
1415: takes a long time if the directory contains many image files, and it
1416: asks for confirmation if the number of image files exceeds
1417: @code{image-dired-show-all-from-dir-max-files}.
1418: 
1419:   With point in the thumbnail buffer, you can type @key{RET}
1420: (@code{image-dired-display-thumbnail-original-image}) to display a
1421: sized version of it in another window.  This sizes the image to fit
1422: the window.  Use the arrow keys to move around in the buffer.  For
1423: easy browsing, use @key{SPC}
1424: (@code{image-dired-display-next-thumbnail-original}) to advance and
1425: display the next image.  Typing @key{DEL}
1426: (@code{image-dired-display-previous-thumbnail-original}) backs up to
1427: the previous thumbnail and displays that instead.
1428: 
1429: @vindex image-dired-external-viewer
1430:   To view the image in its original size, either provide a prefix
1431: argument (@kbd{C-u}) before pressing @key{RET}, or type
1432: @kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to
1433: display the image in an external viewer.  You must first configure
1434: @code{image-dired-external-viewer}.
1435: 
1436:   You can delete images through Image-Dired also.  Type @kbd{d}
1437: (@code{image-dired-flag-thumb-original-file}) to flag the image file
1438: for deletion in the Dired buffer.  You can also delete the thumbnail
1439: image from the thumbnail buffer with @kbd{C-d}
1440: (@code{image-dired-delete-char}).
1441: 
1442:   More advanced features include @dfn{image tags}, which are metadata
1443: used to categorize image files.  The tags are stored in a plain text
1444: file configured by @code{image-dired-db-file}.
1445: 
1446:   To tag image files, mark them in the dired buffer (you can also mark
1447: files in Dired from the thumbnail buffer by typing @kbd{m}) and type
1448: @kbd{C-t t} (@code{image-dired-tag-files}).  This reads the tag name
1449: in the minibuffer.  To mark files having a certain tag, type @kbd{C-t f}
1450: (@code{image-dired-mark-tagged-files}).  After marking image files
1451: with a certain tag, you can use @kbd{C-t d} to view them.
1452: 
1453:   You can also tag a file directly from the thumbnail buffer by typing
1454: @kbd{t t} and you can remove a tag by typing @kbd{t r}.  There is also
1455: a special tag called ``comment'' for each file (it is not a tag in
1456: the exact same sense as the other tags, it is handled slightly
1457: differently).  That is used to enter a comment or description about the
1458: image.  You comment a file from the thumbnail buffer by typing
1459: @kbd{c}.  You will be prompted for a comment.  Type @kbd{C-t c} to add
1460: a comment from Dired (@code{image-dired-dired-comment-files}).
1461: 
1462:   Image-Dired also provides simple image manipulation.  In the
1463: thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees
1464: anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise.  This
1465: rotation is lossless, and uses an external utility called
1466: @command{jpegtran}, which you need to install first.
1467: 
1468: @node Misc Dired Features
1469: @section Other Dired Features
1470: 
1471: @kindex + @r{(Dired)}
1472: @findex dired-create-directory
1473:   The command @kbd{+} (@code{dired-create-directory}) reads a
1474: directory's name, and creates that directory.  It signals an error if
1475: the directory already exists.
1476: 
1477: @findex dired-create-empty-file
1478:   The command (@code{dired-create-empty-file}) reads a
1479: file name, and creates that file.  It signals an error if
1480: the file already exists.
1481: 
1482: @cindex searching multiple files via Dired
1483: @kindex M-s a C-s @r{(Dired)}
1484: @kindex M-s a M-C-s @r{(Dired)}
1485: @findex dired-do-isearch
1486: @findex dired-do-isearch-regexp
1487:   The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a
1488: multi-file incremental search on the marked files.  If a search
1489: fails at the end of a file, typing @kbd{C-s} advances to the next
1490: marked file and repeats the search; at the end of the last marked
1491: file, the search wraps around to the first marked file.  The command
1492: @kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with
1493: a regular expression search.  @xref{Repeat Isearch}, for information
1494: about search repetition.
1495: 
1496: @cindex adding to the kill ring in Dired
1497: @kindex w @r{(Dired)}
1498: @findex dired-copy-filename-as-kill
1499:   The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the
1500: names of the marked (or next @var{n}) files into the kill ring, as if
1501: you had killed them with @kbd{C-w}.  The names are separated by a
1502: space.
1503: 
1504:   With a zero prefix argument, this uses the absolute file name of
1505: each marked file.  With just @kbd{C-u} as the prefix argument, it uses
1506: file names relative to the Dired buffer's default directory.  (This
1507: can still contain slashes if in a subdirectory.)  As a special case,
1508: if point is on a directory header line, @kbd{w} gives you the absolute
1509: name of that directory.  Any prefix argument or marked files are
1510: ignored in this case.
1511: 
1512:   The main purpose of this command is so that you can yank the file
1513: names into arguments for other Emacs commands.  It also displays what
1514: it added to the kill ring, so you can use it to display the list of
1515: currently marked files in the echo area.
1516: 
1517: @kindex W @r{(Dired)}
1518: @findex browse-url-of-dired-file
1519:   If you have an HTML file in the file listing, it can be useful to
1520: view that file with a browser.  The @kbd{W}
1521: (@code{browse-url-of-dired-file}) command will use the standard
1522: configured browser to view that file.
1523: 
1524: @kindex ( @r{(Dired)}
1525: @findex dired-hide-details-mode
1526: @vindex dired-hide-details-hide-symlink-targets
1527: @vindex dired-hide-details-hide-information-lines
1528: @cindex hiding details in Dired
1529:   The command @kbd{(} (@code{dired-hide-details-mode}) toggles whether
1530: details, such as ownership or file permissions, are visible in the
1531: current Dired buffer.  By default, it also hides the targets of
1532: symbolic links, and all lines other than the header line and
1533: file/directory listings.  To change this, customize the options
1534: @code{dired-hide-details-hide-symlink-targets} and
1535: @code{dired-hide-details-hide-information-lines}, respectively.
1536: 
1537: @cindex Dired and version control
1538:   If the directory you are visiting is under version control
1539: (@pxref{Version Control}), then the normal VC diff and log commands
1540: will operate on the selected files.
1541: 
1542: @findex dired-compare-directories
1543:   The command @kbd{M-x dired-compare-directories} is used to compare
1544: the current Dired buffer with another directory.  It marks all the files
1545: that differ between the two directories.  It puts these marks
1546: in all Dired buffers where these files are listed, which of course includes
1547: the current buffer.
1548: 
1549:   The default comparison method (used if you type @key{RET} at the
1550: prompt) is to compare just the file names---file names differ if
1551: they do not appear in the other directory.  You can specify
1552: more stringent comparisons by entering a Lisp expression, which can
1553: refer to the variables @code{size1} and @code{size2}, the respective
1554: file sizes; @code{mtime1} and @code{mtime2}, the last modification
1555: times in seconds, as floating point numbers; and @code{fa1} and
1556: @code{fa2}, the respective file attribute lists (as returned by the
1557: function @code{file-attributes}).  This expression is evaluated for
1558: each pair of like-named files, and files differ if the expression's
1559: value is non-@code{nil}.
1560: 
1561:   For instance, the sequence @kbd{M-x dired-compare-directories
1562: @key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this
1563: directory than in the other, and marks files older in the other
1564: directory than in this one.  It also marks files with no counterpart,
1565: in both directories, as always.
1566: 
1567: @cindex drag and drop, Dired
1568:   On the X Window System, Emacs supports the drag and drop
1569: protocol.  You can drag a file object from another program, and drop
1570: it onto a Dired buffer; this either moves, copies, or creates a link
1571: to the file in that directory.  Precisely which action is taken is
1572: determined by the originating program.  Dragging files out of a Dired
1573: buffer is currently not supported.
1574: