comparison man/dired.texi @ 35056:c9c43bb7f1d2

Add index entries for many Dired commands and features.

35055:daf01616a3e7

@c   Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Dired, Calendar/Diary, Rmail, Top
@chapter Dired, the Directory Editor
@cindex Dired

  Dired makes an Emacs buffer containing a listing of a directory, and
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.

return immediately to Dired, with the deletion flags still present in
the buffer, and no files actually deleted.

@node Flagging Many Files
@section Flagging Many Files at Once

@table @kbd
@item #
Flag all auto-save files (files whose names start and end with @samp{#})
for deletion (@pxref{Auto Save}).

keep.@refill

@kindex & @r{(Dired)}
@findex dired-flag-garbage-files
@vindex dired-garbage-files-regexp
  @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
match the regular expression specified by the variable
@code{dired-garbage-files-regexp}.  By default, this matches certain
files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files
produced by @code{patch}.

@kindex # @r{(Dired)}
@kindex ~ @r{(Dired)}
@findex dired-flag-auto-save-files
@findex dired-flag-backup-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 table

@node Marks vs Flags
@section Dired Marks vs. Flags

@cindex marking in Dired
  Instead of flagging a file with @samp{D}, you can @dfn{mark} the file
with some other character (usually @samp{*}).  Most Dired commands to
operate on files, aside from ``expunge'' (@kbd{x}), look for files
marked with @samp{*}.

files.)

@item * *
@kindex * * @r{(Dired)}
@findex dired-mark-executables
Mark all executable files with @samp{*}
(@code{dired-mark-executables}).  With a numeric argument, unmark all
those files.

@item * @@
@kindex * @@ @r{(Dired)}
@findex dired-mark-symlinks
Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
With a numeric argument, unmark all those files.

@item * /
@kindex * / @r{(Dired)}
@findex dired-mark-directories
Mark with @samp{*} all files which are actually directories, except for
@file{.} and @file{..} (@code{dired-mark-directories}).  With a numeric
argument, unmark all those files.

@item * s

@item @key{DEL}
@itemx * @key{DEL}
@kindex * DEL @r{(Dired)}
@findex dired-unmark-backward
Move point to previous line and remove any mark on that line
(@code{dired-unmark-backward}).

@item * !
@kindex * ! @r{(Dired)}

Move up to the previous marked file (@code{dired-prev-marked-file})

@item * t
@kindex * t @r{(Dired)}
@findex dired-do-toggle
Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*}
become unmarked, and unmarked files are marked with @samp{*}.  Files
marked in any other way are not affected.

@item * c @var{old} @var{new}

@samp{^} and @samp{$} to anchor matches.  Exclude subdirectories by
hiding them (@pxref{Hiding Subdirectories}).

@item % g @var{regexp} @key{RET}
@findex dired-mark-files-containing-regexp
@kindex % m @r{(Dired)}
Mark (with @samp{*}) all files whose @emph{contents} contain a match for
the regular expression @var{regexp}
(@code{dired-mark-files-containing-regexp}).  This command is like
@kbd{% m}, except that it searches the file contents instead of the file
name.

commands, also use these conventions to decide which files to work on.)

@table @kbd
@findex dired-do-copy
@kindex C @r{(Dired)}
@item C @var{new} @key{RET}
Copy the specified files (@code{dired-do-copy}).  The argument @var{new}
is the directory to copy into, or (if copying a single file) the new
name.
@vindex dired-recursive-copies

files, or the next @var{n} files.  By contrast, @kbd{x}
(@code{dired-expunge}) deletes all @dfn{flagged} files.

@findex dired-do-rename
@kindex R @r{(Dired)}
@item R @var{new} @key{RET}
Rename the specified files (@code{dired-do-rename}).  The argument
@var{new} is the directory to rename into, or (if renaming a single
file) the new name.

Dired automatically changes the visited file name of buffers associated
with renamed files so that they refer to the new names.

@findex dired-do-hardlink
@kindex H @r{(Dired)}
@item H @var{new} @key{RET}
Make hard links to the specified files (@code{dired-do-hardlink}).  The
argument @var{new} is the directory to make the links in, or (if making
just one link) the name to give the link.

@findex dired-do-symlink
@kindex S @r{(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
making just one link) the name to give the link.

@findex dired-do-chmod
@kindex M @r{(Dired)}
@item M @var{modespec} @key{RET}
Change the mode (also called ``permission bits'') of the specified files
(@code{dired-do-chmod}).  This uses the @code{chmod} program, so
@var{modespec} can be any argument that @code{chmod} can handle.

@findex dired-do-chgrp
@kindex G @r{(Dired)}
@item G @var{newgroup} @key{RET}
Change the group of the specified files to @var{newgroup}
(@code{dired-do-chgrp}).

@findex dired-do-chown
@kindex O @r{(Dired)}
@item O @var{newowner} @key{RET}
Change the owner of the specified files to @var{newowner}
(@code{dired-do-chown}).  (On most systems, only the superuser can do
this.)

program to use to do the work (different systems put @code{chown} in
different places).

@findex dired-do-print
@kindex P @r{(Dired)}
@item P @var{command} @key{RET}
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}).

@findex dired-do-compress
@kindex Z @r{(Dired)}
@item Z
Compress the specified files (@code{dired-do-compress}).  If the file
appears to be a compressed file already, it is uncompressed instead.

@findex dired-do-load
@kindex L @r{(Dired)}
@item L
Load the specified Emacs Lisp files (@code{dired-do-load}).
@xref{Lisp Libraries}.

@findex dired-do-byte-compile
@kindex B @r{(Dired)}
@item B
Byte compile the specified Emacs Lisp files
(@code{dired-do-byte-compile}).  @xref{Byte Compilation,, Byte
Compilation, elisp, The Emacs Lisp Reference Manual}.

@kindex A @r{(Dired)}
@findex dired-do-search
@item A @var{regexp} @key{RET}
Search all the specified files for the regular expression @var{regexp}
(@code{dired-do-search}).

This command is a variant of @code{tags-search}.  The search stops at
the first match it finds; use @kbd{M-,} to resume the search and find
the next match.  @xref{Tags Search}.

@kindex Q @r{(Dired)}
@findex dired-do-query-replace
@item Q @var{from} @key{RET} @var{to} @key{RET}
Perform @code{query-replace-regexp} on each of the specified files,
replacing matches for @var{from} (a regular expression) with the string
@var{to} (@code{dired-do-query-replace}).

query replace loop, you can use @kbd{M-,} to resume the scan and replace
more matches.  @xref{Tags Search}.

@kindex a @r{(Dired)}
@findex dired-do-apply
@item a @var{function} @kbd{RET}
Apply an arbitrary Lisp function to the name of each marked file
(@code{dired-do-apply}).
@end table

  Here are commands that alter file names in a systematic way:

@table @kbd
@findex dired-upcase
@kindex % u @r{(Dired)}
@item % u
Rename each of the selected files to an upper-case name
(@code{dired-upcase}).  If the old file names are @file{Foo}
and @file{bar}, the new names are @file{FOO} and @file{BAR}.

@item % l
@findex dired-downcase
@kindex % l @r{(Dired)}
Rename each of the selected files to a lower-case name
(@code{dired-downcase}).  If the old file names are @file{Foo} and
@file{bar}, the new names are @file{foo} and @file{bar}.

@item % R @var{from} @key{RET} @var{to} @key{RET}

this easier, the @kbd{%} commands to operate on files use the last
regular expression specified in any @kbd{%} command as a default.

@node Comparison in Dired
@section File Comparison with Dired

  Here are two Dired commands that compare specified files using
@code{diff}.

@table @kbd

  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

  This section describes commands to update the Dired buffer to reflect
outside (non-Dired) changes in the directories and files, and to delete
part of the Dired buffer.

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}.
Remember to write the regular expression for @code{grep}, not for Emacs.

@findex find-dired
  The most general command in this series is @kbd{M-x find-dired}, which
lets you specify any condition that @code{find} can test.  It takes two
minibuffer arguments, @var{directory} and @var{find-args}; it runs

35056:c9c43bb7f1d2

@c   Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Dired, Calendar/Diary, Rmail, Top
@chapter Dired, the Directory Editor
@cindex Dired
@cindex file management

  Dired makes an Emacs buffer containing a listing of a directory, and
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.

return immediately to Dired, with the deletion flags still present in
the buffer, and no files actually deleted.

@node Flagging Many Files
@section Flagging Many Files at Once
@cindex flagging many files for deletion (in Dired)

@table @kbd
@item #
Flag all auto-save files (files whose names start and end with @samp{#})
for deletion (@pxref{Auto Save}).

keep.@refill

@kindex & @r{(Dired)}
@findex dired-flag-garbage-files
@vindex dired-garbage-files-regexp
@cindex deleting some backup files
  @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
match the regular expression specified by the variable
@code{dired-garbage-files-regexp}.  By default, this matches certain
files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files
produced by @code{patch}.

@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 table

@node Marks vs Flags
@section Dired Marks vs. Flags

@cindex marking many files (in Dired)
  Instead of flagging a file with @samp{D}, you can @dfn{mark} the file
with some other character (usually @samp{*}).  Most Dired commands to
operate on files, aside from ``expunge'' (@kbd{x}), look for files
marked with @samp{*}.

files.)

@item * *
@kindex * * @r{(Dired)}
@findex dired-mark-executables
@cindex marking executable files (in Dired)
Mark all executable files with @samp{*}
(@code{dired-mark-executables}).  With a numeric argument, unmark all
those files.

@item * @@
@kindex * @@ @r{(Dired)}
@findex dired-mark-symlinks
@cindex marking symlinks (in Dired)
Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
With a numeric argument, unmark all those files.

@item * /
@kindex * / @r{(Dired)}
@findex dired-mark-directories
@cindex marking subdirectories (in Dired)
Mark with @samp{*} all files which are actually directories, except for
@file{.} and @file{..} (@code{dired-mark-directories}).  With a numeric
argument, unmark all those files.

@item * s

@item @key{DEL}
@itemx * @key{DEL}
@kindex * DEL @r{(Dired)}
@findex dired-unmark-backward
@cindex unmarking files (in Dired)
Move point to previous line and remove any mark on that line
(@code{dired-unmark-backward}).

@item * !
@kindex * ! @r{(Dired)}

Move up to the previous marked file (@code{dired-prev-marked-file})

@item * t
@kindex * t @r{(Dired)}
@findex dired-do-toggle
@cindex toggling marks (in Dired)
Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*}
become unmarked, and unmarked files are marked with @samp{*}.  Files
marked in any other way are not affected.

@item * c @var{old} @var{new}

@samp{^} and @samp{$} to anchor matches.  Exclude subdirectories by
hiding them (@pxref{Hiding Subdirectories}).

@item % g @var{regexp} @key{RET}
@findex dired-mark-files-containing-regexp
@kindex % g @r{(Dired)}
@cindex finding files containing regexp matches (in Dired)
Mark (with @samp{*}) all files whose @emph{contents} contain a match for
the regular expression @var{regexp}
(@code{dired-mark-files-containing-regexp}).  This command is like
@kbd{% m}, except that it searches the file contents instead of the file
name.

commands, also use these conventions to decide which files to work on.)

@table @kbd
@findex dired-do-copy
@kindex C @r{(Dired)}
@cindex copying files (in Dired)
@item C @var{new} @key{RET}
Copy the specified files (@code{dired-do-copy}).  The argument @var{new}
is the directory to copy into, or (if copying a single file) the new
name.
@vindex dired-recursive-copies

files, or the next @var{n} files.  By contrast, @kbd{x}
(@code{dired-expunge}) deletes all @dfn{flagged} files.

@findex dired-do-rename
@kindex R @r{(Dired)}
@cindex renaming files (in Dired)
@item R @var{new} @key{RET}
Rename the specified files (@code{dired-do-rename}).  The argument
@var{new} is the directory to rename into, or (if renaming a single
file) the new name.

Dired automatically changes the visited file name of buffers associated
with renamed files so that they refer to the new names.

@findex dired-do-hardlink
@kindex H @r{(Dired)}
@cindex hard links (in Dired)
@item H @var{new} @key{RET}
Make hard links to the specified files (@code{dired-do-hardlink}).  The
argument @var{new} is the directory to make the links in, or (if making
just one link) the name to give the link.

@findex dired-do-symlink
@kindex S @r{(Dired)}
@cindex symlinks (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
making just one link) the name to give the link.

@findex dired-do-chmod
@kindex M @r{(Dired)}
@cindex changing file permissions (in Dired)
@item M @var{modespec} @key{RET}
Change the mode (also called ``permission bits'') of the specified files
(@code{dired-do-chmod}).  This uses the @code{chmod} program, so
@var{modespec} can be any argument that @code{chmod} can handle.

@findex dired-do-chgrp
@kindex G @r{(Dired)}
@cindex changing file group ownership (in Dired)
@item G @var{newgroup} @key{RET}
Change the group of the specified files to @var{newgroup}
(@code{dired-do-chgrp}).

@findex dired-do-chown
@kindex O @r{(Dired)}
@cindex changing file owner (in Dired)
@item O @var{newowner} @key{RET}
Change the owner of the specified files to @var{newowner}
(@code{dired-do-chown}).  (On most systems, only the superuser can do
this.)

program to use to do the work (different systems put @code{chown} in
different places).

@findex dired-do-print
@kindex P @r{(Dired)}
@cindex printing files (in Dired)
@item P @var{command} @key{RET}
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}).

@findex dired-do-compress
@kindex Z @r{(Dired)}
@cindex compressing files (in Dired)
@item Z
Compress the specified files (@code{dired-do-compress}).  If the file
appears to be a compressed file already, it is uncompressed instead.

@findex dired-do-load
@kindex L @r{(Dired)}
@cindex loading several files (in Dired)
@item L
Load the specified Emacs Lisp files (@code{dired-do-load}).
@xref{Lisp Libraries}.

@findex dired-do-byte-compile
@kindex B @r{(Dired)}
@cindex byte-compiling several files (in Dired)
@item B
Byte compile the specified Emacs Lisp files
(@code{dired-do-byte-compile}).  @xref{Byte Compilation,, Byte
Compilation, elisp, The Emacs Lisp Reference Manual}.

@kindex A @r{(Dired)}
@findex dired-do-search
@cindex search multiple files (in Dired)
@item A @var{regexp} @key{RET}
Search all the specified files for the regular expression @var{regexp}
(@code{dired-do-search}).

This command is a variant of @code{tags-search}.  The search stops at
the first match it finds; use @kbd{M-,} to resume the search and find
the next match.  @xref{Tags Search}.

@kindex Q @r{(Dired)}
@findex dired-do-query-replace
@cindex search and replace in multiple files (in Dired)
@item Q @var{from} @key{RET} @var{to} @key{RET}
Perform @code{query-replace-regexp} on each of the specified files,
replacing matches for @var{from} (a regular expression) with the string
@var{to} (@code{dired-do-query-replace}).

query replace loop, you can use @kbd{M-,} to resume the scan and replace
more matches.  @xref{Tags Search}.

@kindex a @r{(Dired)}
@findex dired-do-apply
@cindex apply arbitrary function to many files
@item a @var{function} @kbd{RET}
Apply an arbitrary Lisp function to the name of each marked file
(@code{dired-do-apply}).
@end table

  Here are commands that alter file names in a systematic way:

@table @kbd
@findex dired-upcase
@kindex % u @r{(Dired)}
@cindex upcase file names
@item % u
Rename each of the selected files to an upper-case name
(@code{dired-upcase}).  If the old file names are @file{Foo}
and @file{bar}, the new names are @file{FOO} and @file{BAR}.

@item % l
@findex dired-downcase
@kindex % l @r{(Dired)}
@cindex downcase file names
Rename each of the selected files to a lower-case name
(@code{dired-downcase}).  If the old file names are @file{Foo} and
@file{bar}, the new names are @file{foo} and @file{bar}.

@item % R @var{from} @key{RET} @var{to} @key{RET}

this easier, the @kbd{%} commands to operate on files use the last
regular expression specified in any @kbd{%} command as a default.

@node Comparison in Dired
@section File Comparison with Dired
@cindex file comparison (in Dired)
@cindex compare files (in Dired)

  Here are two Dired commands that compare specified files using
@code{diff}.

@table @kbd

  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
@cindex refreshing displayed files

  This section describes commands to update the Dired buffer to reflect
outside (non-Dired) changes in the directories and files, and to delete
part of the Dired buffer.

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}.
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}.)

@findex find-dired
  The most general command in this series is @kbd{M-x find-dired}, which
lets you specify any condition that @code{find} can test.  It takes two
minibuffer arguments, @var{directory} and @var{find-args}; it runs