nt/INSTALL: Mention problems with MSYS/Cygwin Bash right at the beginning.
[emacs.git] / doc / misc / dired-x.texi
blobeb79778992240c0376f8c8ac7542d8c303c7d87b
1 \input texinfo  @comment -*-texinfo-*-
3 @c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs
4 @c
5 @c Author: Sebastian Kremer <sk@thp.uni-koeln.de>
6 @c      Lawrence R. Dodd <dodd@roebling.poly.edu>
7 @c [Dodd's address no longer valid.]
9 @comment %**start of header (This is for running Texinfo on a region.)
10 @setfilename ../../info/dired-x
11 @settitle Dired Extra User's Manual
13 @include emacsver.texi
15 @iftex
16 @finalout
17 @end iftex
18 @c @setchapternewpage odd               % For book style double sided manual.
19 @comment %**end of header (This is for running Texinfo on a region.)
21 @copying
22 Copyright @copyright{} 1994-1995, 1999, 2001-2011
23 Free Software Foundation, Inc.
25 @quotation
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.3 or
28 any later version published by the Free Software Foundation; with no
29 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
30 and with the Back-Cover Texts as in (a) below.  A copy of the license
31 is included in the section entitled ``GNU Free Documentation License''.
33 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
34 modify this GNU manual.  Buying copies from the FSF supports it in
35 developing GNU and promoting software freedom.''
36 @end quotation
37 @end copying
39 @dircategory Emacs misc features
40 @direntry
41 * Dired-X: (dired-x).           Dired Extra Features.
42 @end direntry
44 @c      @smallbook
45 @tex
46 \overfullrule=0pt
47 %\global\baselineskip 30pt      % For printing in double spaces
48 @end tex
50 @titlepage
51 @sp 6
52 @center @titlefont{Dired Extra}
53 @sp 2
54 @center @titlefont{For The GNU Emacs}
55 @sp 1
56 @center @titlefont{Directory Editor}
57 @sp 4
58 @center Lawrence R@. Dodd
59 @c @center @t{dodd@@roebling.poly.edu}
60 @sp 5
61 @center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>)
62 @page
63 @vskip 0pt plus 1filll
64 @insertcopying
65 @end titlepage
67 @contents
70 @ifnottex
72 @node Top
73 @top Dired Extra
75 @noindent
76 This documents the ``extra'' features for GNU Emacs's Dired Mode that are
77 provided by the file @file{dired-x.el}.
79 @itemize @bullet
81 @item
82 Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>
84 @item
85 For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}.
87 @end itemize
89 @insertcopying
91 @menu
92 * Introduction::
93 * Installation::
94 * Omitting Files in Dired::
95 * Local Variables::
96 * Shell Command Guessing::
97 * Virtual Dired::
98 * Advanced Mark Commands::
99 * Multiple Dired Directories::
100 * Find File At Point::
101 * Miscellaneous Commands::
102 * Bugs::
104 * GNU Free Documentation License::
105 * Concept Index::
106 * Command Index::
107 * Key Index::
108 * Variable Index::
110 @end menu
112 @end ifnottex
114 @node Introduction, Installation, Top, Top
115 @chapter Introduction
117 This documents some @emph{extra} features for GNU Emacs's Dired Mode
118 that are provided by @file{dired-x.el} (derived from Sebastian Kremer's
119 original @file{dired-x.el}).
121 @ifnottex
122 @menu
123 * Features::
124 * Technical Details::
125 @end menu
126 @end ifnottex
128 @node Features, Technical Details, , Introduction
129 @section Features
130 @cindex Features
132 Some features provided by Dired Extra:
134 @enumerate
135 @item
136 Omitting uninteresting files from Dired listing
137 (@pxref{Omitting Files in Dired}).
138 @item
139 Guessing shell commands in Dired buffers
140 (@pxref{Shell Command Guessing}).
141 @item
142 Running Dired command in non-Dired buffers
143 (@pxref{Virtual Dired}).
144 @item
145 Finding a file mentioned in a buffer
146 (@pxref{Find File At Point}).
147 @item
148 Commands using file marking
149 (@pxref{Advanced Mark Commands}).
150 @end enumerate
152 @noindent
153 @file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key
154 Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to
155 @code{dired-jump} (@pxref{Miscellaneous Commands}).  Optionally, it
156 also binds @kbd{C-x C-f} and @kbd{C-x 4 C-f} to
157 @code{dired-x-find-file} and @code{dired-x-find-file-other-window},
158 respectively (@pxref{Find File At Point}).
160 @node Technical Details, , Features, Introduction
161 @section Technical Details
162 @cindex Modified functions
163 @cindex @file{dired-aux.el}
165 When @file{dired-x.el} is loaded, some standard Dired functions from
166 @file{dired.el} and @file{dired-aux.el} offer additional features.
167 @code{dired-add-entry} obeys Dired Omit mode (@pxref{Omitting Files in
168 Dired}), if it is active.  @code{dired-find-buffer-nocreate} and
169 @code{dired-initial-position} respect the value of
170 @code{dired-find-subdir} (@pxref{Miscellaneous Commands}).
171 @code{dired-clean-up-after-deletion} respects the value of
172 @code{dired-clean-up-buffers-too}.  @code{dired-read-shell-command} uses
173 @code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to
174 offer a smarter default command.
176 @node Installation, Omitting Files in Dired, Introduction, Top
177 @chapter Installation
179 @noindent
180 This manual describes the Dired features provided by the file
181 @file{dired-x.el}.  To take advantage of these features, you must load the
182 file and (optionally) set some variables.
184 @noindent
185 In your @file{~/.emacs} file, or in the system-wide initialization file
186 @file{default.el} in the @file{site-lisp} directory, put
188 @example
189 (add-hook 'dired-load-hook
190           (lambda ()
191             (load "dired-x")
192             ;; Set dired-x global variables here.  For example:
193             ;; (setq dired-guess-shell-gnutar "gtar")
194             ;; (setq dired-x-hands-off-my-keys nil)
195             ))
196 (add-hook 'dired-mode-hook
197           (lambda ()
198             ;; Set dired-x buffer-local variables here.  For example:
199             ;; (dired-omit-mode 1)
200             ))
201 @end example
203 @noindent
204 This will load @file{dired-x.el} when Dired is first invoked (for example,
205 when you first type @kbd{C-x d}).
207 @ifnottex
208 @menu
209 * Optional Installation Dired Jump::
210 * Optional Installation File At Point::
211 @end menu
212 @end ifnottex
214 @node Optional Installation Dired Jump, Optional Installation File At Point, , Installation
215 @section Optional Installation Dired Jump
217 @cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window}
219 In order to have @code{dired-jump} and @code{dired-jump-other-window}
220 (@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and
221 @code{dired-x} have been properly loaded you should set-up an autoload
222 for these functions.  In your @file{.emacs} file put
224 @example
225 (autoload 'dired-jump "dired-x"
226   "Jump to Dired buffer corresponding to current buffer." t)
228 (autoload 'dired-jump-other-window "dired-x"
229   "Like \\[dired-jump] (dired-jump) but in other window." t)
231 (define-key global-map "\C-x\C-j" 'dired-jump)
232 (define-key global-map "\C-x4\C-j" 'dired-jump-other-window)
233 @end example
235 @node Optional Installation File At Point, , Optional Installation Dired Jump, Installation
236 @section Optional Installation File At Point
238 @cindex Binding @code{dired-x-find-file}
239 If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over
240 @code{find-file} (@pxref{Find File At Point}), then you will need to set
241 @code{dired-x-hands-off-my-keys}.  To do this, either set it
242 @emph{before} @file{dired-x.el} is loaded, or use @kbd{M-x customize-variable},
243 or call @code{dired-x-bind-find-file} after changing the value.
245 @example
246 (add-hook 'dired-load-hook
247           (lambda ()
248             ;; Bind dired-x-find-file.
249             (setq dired-x-hands-off-my-keys nil)
250             (load "dired-x")
251             ))
252 @end example
254 @node Omitting Files in Dired, Local Variables, Installation, Top
255 @chapter Omitting Files in Dired
257 @cindex Omitting Files in Dired
258 @cindex Uninteresting files
259 @dfn{Omitting} a file means removing it from the directory listing.  Omitting
260 is useful for keeping Dired buffers free of ``uninteresting'' files (for
261 instance, auto-save, auxiliary, backup, and revision control files) so that
262 the user can concentrate on the interesting files.  Like hidden files, omitted
263 files are never seen by Dired.  Omitting differs from hiding in several
264 respects:
266 @itemize @bullet
268 @item
269 Omitting works on individual files, not on directories; an entire directory
270 cannot be omitted (though each of its files could be).
272 @item
273 Omitting is wholesale; if omitting is turned on for a Dired buffer, then all
274 uninteresting files listed in that buffer are omitted.  The user does not omit
275 (or unomit) files one at a time.
277 @item
278 Omitting can be automatic; uninteresting file lines in the buffer can be
279 removed before the user ever sees them.
281 @item
282 Marked files are never omitted.
283 @end itemize
285 @table @kbd
286 @item M-o
287 @kindex M-o
288 @findex dired-omit-mode
289 (@code{dired-omit-mode}) Toggle between displaying and omitting
290 ``uninteresting'' files.
291 @item * O
292 @kindex * O
293 @findex dired-mark-omitted
294 (@code{dired-mark-omitted}) Mark ``uninteresting'' files.
295 @end table
297 @noindent
298 In order to make Dired Omit work you first need to load @file{dired-x.el}
299 inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate
300 @code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}).
302 @ifnottex
303 @menu
304 * Omitting Variables::
305 * Omitting Examples::
306 * Omitting Technical::
307 @end menu
308 @end ifnottex
310 @node Omitting Variables, Omitting Examples, , Omitting Files in Dired
311 @section Omitting Variables
313 @cindex Customizing file omitting
314 The following variables can be used to customize omitting.
316 @table @code
318 @vindex dired-omit-mode
319 @item dired-omit-mode
321 Default: @code{nil}
323 @cindex How to make omitting the default in Dired
324 If non-@code{nil}, ``uninteresting'' files are not listed.
325 Uninteresting files are those whose files whose names match regexp
326 @code{dired-omit-files}, plus those ending with extensions in
327 @code{dired-omit-extensions}.  @kbd{M-o} (@code{dired-omit-mode})
328 toggles its value, which is buffer-local.  Put
330 @example
331 (dired-omit-mode 1)
332 @end example
334 @noindent
335 inside your @code{dired-mode-hook} to have omitting initially turned on in
336 @emph{every} Dired buffer (@pxref{Installation}).  You can then use @kbd{M-o} to
337 unomit in that buffer.
339 To enable omitting automatically only in certain directories you can add
340 a directory local setting
341 (@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) for Dired mode
343 @example
344 ((dired-mode . ((dired-omit-mode . t))))
345 @end example
347 @noindent
348 to a @file{.dir-locals.el} file in that directory.  You can use the
349 command @code{add-dir-local-variable} to do this.
351 @vindex dired-omit-files
352 @item dired-omit-files
354 Default: @code{"^#\\|\\.$"}
356 Files whose names match this buffer-local regexp will not be displayed.
357 This only has effect when @code{dired-omit-mode}'s value is @code{t}.
359 The default value omits the special directories @file{.} and @file{..}  and
360 autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}).
362 @vindex dired-omit-extensions
363 @item dired-omit-extensions
365 Default: The elements of @code{completion-ignored-extensions},
366 @code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions}
367 and @code{dired-texinfo-unclean-extensions}.
369 If non-@code{nil}, a list of extensions (strings) to omit from Dired listings.
370 Its format is the same as that of @code{completion-ignored-extensions}.
372 @vindex dired-omit-localp
373 @item dired-omit-localp
375 Default:  @code{no-dir}
377 The @var{localp} argument @code{dired-omit-expunge} passes to
378 @code{dired-get-filename}.  If it is @code{no-dir}, omitting is much faster,
379 but you can only match against the non-directory part of the file name.  Set it
380 to @code{nil} if you need to match the whole file name or @code{t} to match the
381 file name relative to the buffer's top-level directory.
383 @item dired-omit-marker-char
384 @vindex dired-omit-marker-char
385 @cindex Omitting additional files
386 Default: @kbd{C-o}
388 Temporary marker used by Dired to implement omitting.  Should never be used
389 as marker by the user or other packages.  There is one exception to this rule:
390 by adding
392 @example
393 (setq dired-mark-keys "\C-o")
394 ;; i.e., the value of dired-omit-marker-char
395 ;; (which is not defined yet)
396 @end example
398 @noindent
399 to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a
400 @kbd{C-o} marker, thus causing these files to be omitted in addition to the
401 usually omitted files.  Unfortunately the files you omitted manually this way
402 will show up again after reverting the buffer, unlike the others.
404 @end table
406 @node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired
407 @section Examples of Omitting Various File Types
409 @itemize @bullet
411 @item
412 @cindex RCS files, how to omit them in Dired
413 @cindex Omitting RCS files in Dired
414 If you wish to avoid seeing RCS files and the @file{RCS} directory, then put
416 @example
417 (setq dired-omit-files
418       (concat dired-omit-files "\\|^RCS$\\|,v$"))
419 @end example
421 @noindent
422 in the @code{dired-load-hook} (@pxref{Installation}).  This assumes
423 @code{dired-omit-localp} has its default value of @code{no-dir} to make the
424 @code{^}-anchored matches work.  As a slower alternative, with
425 @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of
426 @code{^} in the regexp.
428 @item
429 @cindex Tib files, how to omit them in Dired
430 @cindex Omitting tib files in Dired
431 If you use @code{tib}, the bibliography program for use with @TeX{} and
432 La@TeX{}, and you
433 want to omit the @file{INDEX} and the @file{*-t.tex} files, then put
435 @example
436 (setq dired-omit-files
437       (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$"))
438 @end example
440 @noindent
441 in the @code{dired-load-hook} (@pxref{Installation}).
443 @item
444 @cindex Dot files, how to omit them in Dired
445 @cindex Omitting dot files in Dired
446 If you do not wish to see @samp{dot} files (files starting with a @file{.}),
447 then put
449 @example
450 (setq dired-omit-files
451       (concat dired-omit-files "\\|^\\..+$"))
452 @end example
454 @noindent
455 in the @code{dired-load-hook} (@pxref{Installation}).
457 @end itemize
459 @node Omitting Technical, , Omitting Examples, Omitting Files in Dired
460 @section Some Technical Details of Omitting
462 Loading @file{dired-x.el} will install Dired Omit by putting
463 @code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will
464 call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup}
465 in your @code{dired-mode-hook}.
467 @node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top
468 @chapter Local Variables for Dired Directories
470 @cindex Local Variables for Dired Directories
471 @vindex dired-local-variables-file
472 @vindex dired-enable-local-variables
473 @noindent
474 This Dired-X feature is obsolete as of Emacs 24.1.  The standard Emacs
475 directory local variables mechanism (@pxref{Directory
476 Variables,,,emacs,The Gnu Emacs manual}) replaces it.  For an example of
477 the new mechanims, @pxref{Omitting Variables}.
479 When Dired visits a directory, it looks for a file whose name is the
480 value of variable @code{dired-local-variables-file} (default: @file{.dired}).
481 If such a file is found, Dired will temporarily insert it into the Dired
482 buffer and run @code{hack-local-variables}.
484 @noindent
485 For example, if the user puts
487 @example
488 Local Variables:
489 dired-actual-switches: "-lat"
490 dired-omit-mode: t
491 End:
492 @end example
494 @noindent
495 into a file called @file{.dired} in a directory then when that directory is
496 viewed it will be
498 @enumerate
499 @item
500 sorted by date
501 @item
502 omitted automatically
503 @end enumerate
505 @noindent
506 You can set @code{dired-local-variables-file} to @code{nil} to suppress this.
507 The value of @code{dired-enable-local-variables} controls if and how these
508 local variables are read.  This variable exists so that it may override the
509 default value of @code{enable-local-variables}.
511 @noindent
512 Please see the GNU Emacs Manual to learn more about local variables.
513 @xref{File Variables,Local Variables in Files,Local Variables in
514 Files,emacs,The GNU Emacs Manual}.
516 @noindent
517 The following variables affect Dired Local Variables
519 @table @code
520 @vindex dired-local-variables-file
521 @item dired-local-variables-file
522 Default: @code{".dired"}
524 If non-@code{nil}, file name for local variables for Dired.  If Dired finds a
525 file with that name in the current directory, it will temporarily insert it
526 into the Dired buffer and run @code{hack-local-variables}.
528 @vindex dired-enable-local-variables
529 @item dired-enable-local-variables
530 Default: @code{t}
532 Controls the use of local-variables lists in Dired.  This variable
533 temporarily overrides the value of @code{enable-local-variables} when
534 the Dired Local Variables are hacked.  It takes the same values as that
535 variable.  A value of @code{nil} means to ignore any Dired Local Variables.
536 @end table
538 @node Shell Command Guessing, Virtual Dired, Local Variables, Top
539 @chapter Shell Command Guessing
540 @cindex Guessing shell commands for files.
542 Based upon the name of a file, Dired tries to guess what shell
543 command you might want to apply to it.  For example, if you have point
544 on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
545 you want to @samp{tar xvf} it and suggest that as the default shell
546 command.
548 The default is mentioned in brackets and you can type @kbd{M-n} to get
549 the default into the minibuffer and then edit it, e.g., to change
550 @samp{tar xvf} to @samp{tar tvf}.  If there are several commands for a given
551 file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
552 @kbd{M-n} several times to see each of the matching commands.
554 Dired only tries to guess a command for a single file, never for a list
555 of marked files.
557 @table @code
558 @item dired-guess-shell-alist-default
559 @vindex dired-guess-shell-alist-default
560 Predefined rules for shell commands.  Set this to @code{nil} to turn guessing off.
561 The elements of @code{dired-guess-shell-alist-user} (defined by the
562 user) will override these rules.@refill
564 @item dired-guess-shell-alist-user
565 @vindex dired-guess-shell-alist-user
566 If non-@code{nil}, a user-defined alist of file regexps and their suggested
567 commands.  These rules take precedence over the predefined rules in the
568 variable @code{dired-guess-shell-alist-default} (to which they are prepended)
569 when @code{dired-do-shell-command} is run).
570 @refill
572 Each element of the alist looks like
574 @example
575 (@var{regexp} @var{command}@dots{})
576 @end example
578 @noindent
579 where each @var{command} can either be a string or a Lisp expression
580 that evaluates to a string.  If several commands are given, all of
581 them will temporarily be pushed onto the history.
583 If @samp{*} in the shell command, that means to substitute the file
584 name.
586 You can set this variable in your @file{~/.emacs}.  For example,
587 to add rules for @samp{.foo} and @samp{.bar} file extensions, write
589 @example
590 (setq dired-guess-shell-alist-user
591       (list
592        (list "\\.foo$" "@var{foo-command}");; fixed rule
593        ;; possibly more rules...
594        (list "\\.bar$";; rule with condition test
595               '(if @var{condition}
596                    "@var{bar-command-1}"
597                  "@var{bar-command-2}"))))
598 @end example
600 @noindent
601 This will override any predefined rules for the same extensions.
603 @item dired-guess-shell-case-fold-search
604 @vindex dired-guess-shell-case-fold-search
605 Default: @code{t}
607 Non-@code{nil} means @code{dired-guess-shell-alist-default} and
608 @code{dired-guess-shell-alist-user} are matched case-insensitively.
610 @item dired-guess-shell-gnutar
611 @vindex dired-guess-shell-gnutar
612 @cindex Passing GNU Tar its @samp{z} switch.
613 Default: @code{nil}
615 If non-@code{nil}, this is the name of the GNU Tar executable (e.g.,
616 @samp{tar} or @samp{gnutar}).  GNU Tar's @samp{z} switch is used for
617 compressed tar files.
618 If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is
619 then used.
621 @item dired-guess-shell-gzip-quiet
622 @vindex dired-guess-shell-gzip-quiet
623 @cindex @code{gzip}
624 Default: @code{t}
626 A non-@code{nil} value means that @samp{-q} is passed to @code{gzip}
627 overriding a verbose option in the @env{GZIP} environment variable.
629 @item dired-guess-shell-znew-switches nil
630 @vindex dired-guess-shell-znew-switches nil
631 @cindex @code{znew}
632 Default: @code{nil}
634 A string of switches passed to @code{znew}.  An example is
635 @samp{-K} which will make @code{znew} keep a @file{.Z} file when it is
636 smaller than the @file{.gz} file.
638 @item dired-shell-command-history nil
639 @vindex dired-shell-command-history nil
641 History list for commands that read dired-shell commands.
642 @end table
644 @node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top
645 @chapter Virtual Dired
647 @cindex Virtual Dired
648 @cindex Perusing @code{ls} listings
649 @cindex @code{ls} listings, how to peruse them in Dired
650 Using @dfn{Virtual Dired} means putting a buffer with Dired-like
651 contents in Dired mode.  The files described by the buffer contents need
652 not actually exist.  This is useful if you want to peruse an @samp{ls -lR}
653 output file, for example one you got from an FTP server.  You can use
654 all motion commands usually available in Dired.  You can also use
655 it to save a Dired buffer in a file and resume it in a later session.
657 @findex dired-virtual
658 @kindex g
659 @findex dired-virtual-revert
660 Type @kbd{M-x dired-virtual} to put the current buffer into virtual
661 Dired mode.  You will be prompted for the top level directory of this
662 buffer, with a default value guessed from the buffer contents.  To
663 convert the virtual to a real Dired buffer again, type @kbd{g} (which
664 calls @code{dired-virtual-revert}) in the virtual Dired buffer and
665 answer @samp{y}.  You don't have to do this, though: you can relist
666 single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory
667 headerline, leaving the buffer in virtual Dired mode all the time.
669 @findex dired-virtual-mode
670 @vindex auto-mode-alist
671 The function @samp{dired-virtual-mode} is specially designed to turn on
672 virtual Dired mode from the @code{auto-mode-alist}.  To edit all
673 @file{*.dired} files automatically in virtual Dired mode, put this into your
674 @file{~/.emacs}:
676 @example
677 (setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode)
678                               auto-mode-alist))
679 @end example
681 @noindent
682 The regexp is a bit more complicated than usual to exclude @file{.dired}
683 local-variable files.
685 @node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top
686 @chapter Advanced Mark Commands
688 @table @kbd
689 @item F
690 @kindex F
691 @cindex Visiting several files at once
692 @cindex Simultaneous visiting of several files
693 @findex dired-do-find-marked-files
694 (@code{dired-do-find-marked-files}) Find all marked files at once displaying
695 them simultaneously.  If optional @var{noselect} is non-@code{nil} then just
696 find the
697 files but do not select.  If you want to keep the Dired buffer displayed, type
698 @kbd{C-x 2} first.  If you want just the marked files displayed and nothing
699 else, type @kbd{C-x 1} first.
701 The current window is split across all files marked, as evenly as possible.
702 Remaining lines go to the bottom-most window.  The number of files that can be
703 displayed this way is restricted by the height of the current window and the
704 variable @code{window-min-height}.
705 @end table
707 @table @code
708 @item dired-mark-extension
709 @findex dired-mark-extension
710 Mark all files with a certain extension for use in later commands.  A @samp{.}
711 is not automatically prepended to the string entered, you must type it
712 explicitly.
714 When called from Lisp, @var{extension} may also be a list of extensions
715 and an optional argument @var{marker-char} specifies the marker used.
717 @item dired-flag-extension
718 @findex dired-flag-extension
719 Flag all files with a certain extension for deletion.  A @samp{.} is
720 @emph{not} automatically prepended to the string entered.
721 @end table
723 @ifnottex
724 @menu
725 * Advanced Cleaning Functions::
726 * Advanced Cleaning Variables::
727 * Special Marking Function::
728 @end menu
729 @end ifnottex
731 @node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands
732 @section Advanced Cleaning Functions
734 @table @code
735 @item dired-clean-patch
736 @findex dired-clean-patch
737 Flag dispensable files created by the @samp{patch} program for deletion.  See
738 variable @code{dired-patch-unclean-extensions}.
740 @item dired-clean-tex
741 @findex dired-clean-tex
742 Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for
743 deletion.  See the following variables (@pxref{Advanced Cleaning Variables}):
745 @itemize @bullet
746 @item
747 @code{dired-tex-unclean-extensions}
748 @item
749 @code{dired-texinfo-unclean-extensions}
750 @item
751 @code{dired-latex-unclean-extensions}
752 @item
753 @code{dired-bibtex-unclean-extensions}
754 @end itemize
756 @item dired-very-clean-tex
757 @findex dired-very-clean-tex
758 Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo},
759 and @file{*.dvi} files for deletion.
760 @end table
762 @node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands
763 @section Advanced Cleaning Variables
765 @noindent Variables used by the above cleaning commands (and in the default value for
766 variable @code{dired-omit-extensions}, @pxref{Omitting Variables})
768 @table @code
769 @item dired-patch-unclean-extensions
770 @vindex dired-patch-unclean-extensions
771 Default: @code{(".rej" ".orig")}
773 List of extensions of dispensable files created by the @samp{patch} program.
775 @item dired-tex-unclean-extensions
776 @vindex dired-tex-unclean-extensions
777 Default:  @code{(".toc" ".log" ".aux")}
779 List of extensions of dispensable files created by @TeX{}.
781 @item dired-texinfo-unclean-extensions
782 @vindex dired-texinfo-unclean-extensions
783 Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"}
784 @code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}
786 List of extensions of dispensable files created by @samp{texinfo}.
788 @item dired-latex-unclean-extensions
789 @vindex dired-latex-unclean-extensions
790 Default: @code{(".idx" ".lof" ".lot" ".glo")}
792 List of extensions of dispensable files created by La@TeX{}.
794 @item dired-bibtex-unclean-extensions
795 @vindex dired-bibtex-unclean-extensions
796 Default:  @code{(".blg" ".bbl")}
798 List of extensions of dispensable files created by Bib@TeX{}.
799 @end table
801 @node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands
802 @section Special Marking Function
804 @table @kbd
805 @item M-(
806 @kindex M-(
807 @findex dired-mark-sexp
808 @cindex Lisp expression, marking files with in Dired
809 @cindex Mark file by Lisp expression
810 (@code{dired-mark-sexp}) Mark files for which @var{predicate} returns
811 non-@code{nil}.  With a prefix argument, unflag those files instead.
813 The @var{predicate} is a Lisp expression that can refer to the following
814 symbols:
815 @table @code
816 @item inode
817 [@i{integer}] the inode of the file (only for @samp{ls -i} output)
818 @item s
819 [@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or,
820 with @samp{-k}, in KBytes)
821 @item mode
822 [@i{string}]  file permission bits, e.g., @samp{-rw-r--r--}
823 @item nlink
824 [@i{integer}] number of links to file
825 @item uid
826 [@i{string}]  owner
827 @item gid
828 [@i{string}]  group  (If the gid is not displayed by @samp{ls}, this
829 will still be set (to the same as uid))
830 @item size
831 [@i{integer}] file size in bytes
832 @item time
833 [@i{string}]  the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17}
834 @item name
835 [@i{string}]  the name of the file
836 @item sym
837 [@i{string}]  if file is a symbolic link, the linked-to name, else @code{""}
838 @end table
840 @noindent
841 For example, use
842 @example
843 (equal 0 size)
844 @end example
845 to mark all zero length files.
847 To find out all not yet compiled Emacs Lisp files in a directory, Dired
848 all @file{.el} files in the lisp directory using the wildcard
849 @samp{*.el}.  Then use @kbd{M-(} with
850 @example
851 (not (file-exists-p (concat name "c")))
852 @end example
853 to mark all @file{.el} files without a corresponding @file{.elc} file.
855 @end table
857 @node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top
858 @chapter Multiple Dired Directories and Non-Dired Commands
860 @cindex Multiple Dired directories
861 @cindex Working directory
862 An Emacs buffer can have but one working directory, stored in the
863 buffer-local variable @code{default-directory}.  A Dired buffer may have
864 several subdirectories inserted, but it still has only one working
865 directory: that of the top-level Dired directory in that buffer.  For
866 some commands it is appropriate that they use the current Dired
867 directory instead of @code{default-directory}, e.g., @code{find-file} and
868 @code{compile}.
870 @findex dired-smart-shell-command
871 @findex shell-command
872 @kindex M-!
873 The command @code{dired-smart-shell-command}, bound to @kbd{M-!} in
874 Dired buffers, is like @code{shell-command}, but it runs with
875 @code{default-directory} bound to the current Dired directory.
877 @node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top
878 @section Find File At Point
879 @cindex Visiting a file mentioned in a buffer
880 @cindex Finding a file at point
882 @file{dired-x} provides a method of visiting or editing a file mentioned in
883 the buffer you are viewing (e.g., a mail buffer, a news article, a
884 @file{README} file, etc.) or to test if that file exists.  You can then modify
885 this in the minibuffer after snatching the file name.
887 When installed @file{dired-x} will substitute @code{dired-x-find-file} for
888 @code{find-file} (normally bound to @kbd{C-x C-f}) and
889 @code{dired-x-find-file-other-window} for @code{find-file-other-window}
890 (normally bound to @kbd{C-x 4 C-f}).
892 In order to use this feature, you will need to set
893 @code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook}
894 (@pxref{Optional Installation File At Point}).
896 @table @code
897 @item dired-x-find-file
898 @findex dired-x-find-file
899 @kindex C-x C-f
901 @code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound
902 to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which
903 case it will use the file name at point as a guess for the file to visit.
905 For example, if the buffer you were reading contained the words
907 @example
908 Available via anonymous ftp in
910    /roebling.poly.edu:/pub/lisp/crypt++.el.gz
911 @end example
913 @noindent
914 then you could move your cursor to the line containing the ftp address and
915 type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument).  The
916 minibuffer would read
918 @example
919 Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz
920 @end example
922 @noindent
923 with the point after the last @code{/}.  If you hit @key{RET}, emacs will visit
924 the file at that address.  This also works with files on your own computer.
926 @item dired-x-find-file-other-window
927 @findex dired-x-find-file-other-window
928 @kindex C-x 4 C-f
930 @code{dired-x-find-file-other-window} behaves exactly like
931 @code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a
932 prefix argument is used.  See @code{dired-x-find-file} for more information.
934 @item dired-x-hands-off-my-keys
935 @vindex dired-x-hands-off-my-keys
936 If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind
937 @code{dired-x-find-file} over @code{find-file} on keyboard.  Similarly, it
938 should not bind @code{dired-x-find-file-other-window} over
939 @code{find-file-other-window}.  If you change this variable after
940 @file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}.  The
941 default value of this variable is @code{t}; by default, the binding is not
942 done.  See @xref{Optional Installation File At Point}.
944 @item dired-x-bind-find-file
945 @findex dired-x-bind-find-file
946 A function, which can be called interactively or in your @file{~/.emacs} file,
947 that uses the value of @code{dired-x-hands-off-my-keys} to determine if
948 @code{dired-x-find-file} should be bound over @code{find-file} and
949 @code{dired-x-find-file-other-window} bound over
950 @code{find-file-other-window}.  See @xref{Optional Installation File At Point}.
951 @end table
953 @node Miscellaneous Commands, Bugs, Find File At Point, Top
954 @chapter Miscellaneous Commands
956 Miscellaneous features not fitting anywhere else:
958 @table @code
959 @item dired-find-subdir
960 @vindex dired-find-subdir
961 Default: @code{nil}
963 If non-@code{nil}, Dired does not make a new buffer for a directory if it can
964 be found (perhaps as subdirectory) in some existing Dired buffer.
966 If there are several Dired buffers for a directory, the most recently
967 used is chosen.
969 Dired avoids switching to the current buffer, so that if you have a
970 normal and a wildcard buffer for the same directory, @kbd{C-x d RET}
971 will toggle between those two.
972 @end table
974 @table @kbd
975 @findex dired-goto-subdir
976 @kindex M-G
977 @item M-G
978 (@code{dired-goto-subdir}) Go to the header line of an inserted directory.
979 This command reads its argument, with completion derived from the names of the
980 inserted subdirectories.
981 @end table
983 @table @code
985 @item dired-jump
986 @findex dired-jump
987 @kindex C-x C-j
988 @cindex Jumping to Dired listing containing file.
989 Bound to @kbd{C-x C-j}.  Jump back to Dired: If in a file, edit the current
990 directory and move to file's line.  If in Dired already, pop up a level and
991 go to old directory's line.  In case the proper Dired file line cannot be
992 found, refresh the Dired buffer and try again.
994 @item dired-jump-other-window
995 @findex dired-jump-other-window
996 @kindex C-x 4 C-j
997 Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window.
999 These functions can be autoloaded so they work even though @file{dired-x.el}
1000 has not been loaded yet (@pxref{Optional Installation Dired Jump}).
1002 @vindex dired-bind-jump
1003 If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be
1004 bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to
1005 @kbd{C-x 4 C-j}.
1007 @item dired-vm
1008 @cindex Reading mail.
1009 @kindex V
1010 @findex dired-vm
1011 Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}.  Run VM on this
1012 file (assumed to be a UNIX mail folder).
1014 @vindex dired-vm-read-only-folders
1015 If you give this command a prefix argument, it will visit the folder
1016 read-only.
1018 If the variable @code{dired-vm-read-only-folders} is @code{t},
1019 @code{dired-vm} will visit all folders read-only.  If it is neither
1020 @code{nil} nor @code{t}, e.g., the symbol @code{if-file-read-only}, only
1021 files not writable by you are visited read-only.
1023 @vindex dired-bind-vm
1024 If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound
1025 to @kbd{V}.  Otherwise, @code{dired-bind-rmail} will be bound.
1027 @item dired-rmail
1028 @cindex Reading mail.
1029 @findex dired-rmail
1030 Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}.  Run Rmail on this
1031 file (assumed to be mail folder in Rmail format).
1033 @item dired-info
1034 @kindex I
1035 @cindex Running info.
1036 @findex dired-info
1037 Bound to @kbd{I}.  Run Info on this file (assumed to be a file in Info
1038 format).
1040 @vindex dired-bind-info
1041 If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
1042 not be bound to @kbd{I}.
1044 @item dired-man
1045 @cindex Running man.
1046 @kindex N
1047 @findex dired-man
1048 Bound to @kbd{N}.  Run man on this file (assumed to be a file in @code{nroff}
1049 format).
1051 @vindex dired-bind-man
1052 If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
1053 be bound to @kbd{N}.
1055 @item dired-do-relsymlink
1056 @cindex Relative symbolic links.
1057 @kindex Y
1058 @findex dired-do-relsymlink
1059 Bound to @kbd{Y}.  Relative symlink all marked (or next ARG) files into a
1060 directory, or make a relative symbolic link to the current file.  This creates
1061 relative symbolic links like
1063 @example
1064     foo -> ../bar/foo
1065 @end example
1067 @noindent
1068 not absolute ones like
1070 @example
1071     foo -> /ugly/path/that/may/change/any/day/bar/foo
1072 @end example
1074 @item dired-do-relsymlink-regexp
1075 @kindex %Y
1076 @findex dired-do-relsymlink-regexp
1077 Bound to @kbd{%Y}.  Relative symlink all marked files containing
1078 @var{regexp} to @var{newname}.  See functions
1079 @code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more
1080 info.
1081 @end table
1083 @node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top
1084 @chapter Bugs
1085 @cindex Bugs
1087 @noindent
1088 If you encounter a bug in this package, or wish to suggest an
1089 enhancement, then please use @kbd{M-x report-emacs-bug} to report it.
1091 @node GNU Free Documentation License, Concept Index, Bugs, Top
1092 @appendix GNU Free Documentation License
1093 @include doclicense.texi
1095 @node     Concept Index, Command Index, GNU Free Documentation License, Top
1096 @unnumbered Concept Index
1097 @printindex cp
1099 @node     Command Index, Key Index, Concept Index, Top
1100 @unnumbered Function Index
1101 @printindex fn
1103 @node     Key Index, Variable Index, Command Index, Top
1104 @unnumbered Key Index
1105 @printindex ky
1107 @node     Variable Index,  , Key Index, Top
1108 @unnumbered Variable Index
1109 @printindex vr
1111 @bye