1 \input texinfo @comment -*-texinfo-*-
3 @c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19
5 @c Author: Sebastian Kremer <sk@thp.uni-koeln.de>
6 @c Lawrence R. Dodd <dodd@roebling.poly.edu>
7 @c Maintainer: Lawrence R. Dodd <dodd@roebling.poly.edu>
9 @c Date: 1994/08/09 16:51:31
10 @c Keywords: dired extensions
11 @c dired-x.el REVISION NUMBER: 2
14 @c Ident: dired-x.texi,v 2.52 1994/08/09 16:51:31 dodd Released
16 @comment %**start of header (This is for running Texinfo on a region.)
17 @c FOR GNU EMACS USE ../info/dired-x BELOW
18 @setfilename ../info/dired-x
19 @c dired-x.el REVISION NUMBER
20 @settitle Dired Extra Version 2 User's Manual
24 * Dired-X: (dired-x). Dired Extra Features.
30 @c @setchapternewpage odd % For book style double sided manual.
31 @comment %**end of header (This is for running Texinfo on a region.)
35 %\global\baselineskip 30pt % For printing in double spaces
39 @node Copyright, Top, (dir), (dir)
40 @comment node-name, next, previous, up
41 This documents the ``extra'' features for Dired Mode for GNU Emacs 19 found in
42 the file @file{dired-x.el}.
44 Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
46 Permission is granted to make and distribute verbatim copies of this
47 manual provided the copyright notice and this permission notice are
48 preserved on all copies.
50 Permission is granted to copy and distribute modified versions of
51 this manual under the conditions for verbatim copying, provided that
52 the entire resulting derived work is distributed under the terms of
53 a permission notice identical to this one.
55 Permission is granted to copy and distribute translations of this
56 manual into another language, under the above conditions for
57 modified versions, except that this permission notice may be stated
58 in a translation approved by the Free Software Foundation.
60 The file used to create this is called @file{dired-x.texi}, but the
61 original work that was altered to make that file was called
62 @file{dired.texi} written by Sebastian Kremer.
65 Permission is granted to process this file through TeX and print the
66 results, provided the printed document carries copying permission
67 notice identical to this one except for the removal of this paragraph
68 (this paragraph not being relevant to the printed manual).
76 @c dired-x.el REVISION NUMBER
77 @center @titlefont{Dired Extra Version 2}
79 @center @titlefont{For The GNU Emacs 19}
81 @center @titlefont{Directory Editor}
83 @center Manual Revision: 2.52
84 @center 1994/08/09 16:51:31
86 @center Lawrence R@. Dodd
87 @center @t{dodd@@roebling.poly.edu}
89 @center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>)
91 @vskip 0pt plus 1filll
92 Copyright @copyright{} 1993, 1994 Free Software Foundation
94 Permission is granted to make and distribute verbatim copies of
95 this manual provided the copyright notice and this permission notice
96 are preserved on all copies.
98 Permission is granted to copy and distribute modified versions of
99 this manual under the conditions for verbatim copying, provided that
100 the entire resulting derived work is distributed under the terms of
101 a permission notice identical to this one.
103 Permission is granted to copy and distribute translations of this
104 manual into another language, under the above conditions for
105 modified versions, except that this permission notice may be stated
106 in a translation approved by the Free Software Foundation.
108 The file used to create this is called @file{dired-x.texi}, but the
109 original work that was altered to make that file was called
110 @file{dired.texi} written by Sebastian Kremer.
118 @node Top, Introduction, Copyright, (dir)
119 @comment node-name, next, previous, up
122 This documents the ``extra'' features for Dired Mode for GNU Emacs 19 that are
123 provided by the file @file{dired-x.el}.
128 Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>
130 @c dired-x.el REVISION NUMBER
132 For @file{dired-x.el} revision 2
135 Revision of this manual: 2.52 (1994/08/09 16:51:31)
138 Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>. @emph{Please} type
139 @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}).
142 You can obtain a copy of this package via anonymous ftp in
143 @t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz}
150 * Omitting Files in Dired::
152 * Shell Command Guessing::
154 * Advanced Mark Commands::
155 * Multiple Dired Directories::
156 * Find File At Point::
157 * Miscellaneous Commands::
169 @node Introduction, Features, Top, Top
170 @comment node-name, next, previous, up
171 @chapter Introduction
173 This documents the @emph{extra} features for Dired Mode for GNU Emacs 19. It
174 is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el} and is
175 GNU Emacs v19 compatible.
177 In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has
178 been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs
179 19 distribution has been removed and some material was modified for agreement
180 with the functions in @file{dired.el} and @file{dired-aux.el}. For example,
181 the code using @code{gmhist} history functions was replaced with code using
182 the mini-buffer history now built into GNU Emacs 19. Finally, a few other
183 features have been added and a few more functions have been bound to keys.
185 Please note that @file{dired-x.el} and this texinfo file @file{dired-x.texi}
186 are bundled with GNU Emacs versions 19.23 and later.
191 * Technical Details::
195 @node Features, Technical Details, Introduction, Introduction
196 @comment node-name, next, previous, up
200 Some features provided by Dired Extra
204 Omitting of uninteresting files from dired listing.
206 @xref{Omitting Files in Dired}.
209 Local variables for dired directories.
211 @xref{Local Variables}.
214 Guessing shell commands in dired buffers.
216 @xref{Shell Command Guessing}.
219 Running dired command in non-dired buffers.
221 @xref{Virtual Dired}.
224 Finding a file mentioned in a buffer
226 @xref{Find File At Point}.
229 Commands using file marking.
231 @xref{Advanced Mark Commands}.
236 @file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key
237 Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to
238 @code{dired-jump} (@pxref{Miscellaneous Commands}). It may also bind @kbd{C-x
239 C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and
240 @code{dired-x-find-file-other-window}, respectively (@pxref{Find File At
243 @node Technical Details, Installation, Features, Introduction
244 @comment node-name, next, previous, up
245 @section Technical Details
246 @cindex Redefined functions
247 @cindex @file{dired-aux.el}
249 When loaded this code @emph{redefines} the following functions of GNU Emacs
254 @code{dired-clean-up-after-deletion}
256 @code{dired-find-buffer-nocreate}
258 @code{dired-initial-position}
260 @code{dired-up-directory}
264 and the following functions from @file{dired-aux.el}
268 @code{dired-add-entry}
270 @code{dired-read-shell-command}
273 One drawback is that @file{dired-x.el} will load @file{dired-aux.el} as soon
274 as dired is loaded. Thus, the advantage of separating out non-essential dired
275 stuff into @file{dired-aux.el} and only loading when necessary will be lost
276 when @file{dired-x.el} is used.
278 @node Installation, Optional Installation Dired Jump, Technical Details, Top
279 @comment node-name, next, previous, up
280 @chapter Installation
283 This manual describes the dired features provided by the file
284 @file{dired-x.el}. To take advantage of these features, you must load the
285 file and (optionally) set some variables.
288 In your @file{.emacs} file in your home directory, or in the system-wide
289 initialization file @file{default.el} in the @file{site-lisp} directory, put
292 (add-hook 'dired-load-hook
295 ;; Set dired-x global variables here. For example:
296 ;; (setq dired-guess-shell-gnutar "gtar")
297 ;; (setq dired-x-hands-off-my-keys nil)
299 (add-hook 'dired-mode-hook
301 ;; Set dired-x buffer-local variables here. For example:
302 ;; (setq dired-omit-files-p t)
307 This will load @file{dired-x.el} when dired is first invoked (for example,
308 when you first do @kbd{C-x d}).
312 * Optional Installation Dired Jump::
313 * Optional Installation File At Point::
318 @node Optional Installation Dired Jump, Optional Installation File At Point, Installation, Installation
319 @comment node-name, next, previous, up
320 @section Optional Installation Dired Jump
322 @cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window}
324 In order to have @code{dired-jump} and @code{dired-jump-other-window}
325 (@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and
326 @code{dired-x} have been properly loaded the user should set-up an autoload
327 for these functions. In your @file{.emacs} file put
330 ;;; Autoload `dired-jump' and `dired-jump-other-window'.
331 ;;; We autoload from FILE dired.el. This will then load dired-x.el
332 ;;; and hence define `dired-jump' and `dired-jump-other-window'.
333 (define-key global-map "\C-x\C-j" 'dired-jump)
334 (define-key global-map "\C-x4\C-j" 'dired-jump-other-window)
336 (autoload (quote dired-jump) "dired" "\
337 Jump to dired buffer corresponding to current buffer.
338 If in a file, dired the current directory and move to file's line.
339 If in dired already, pop up a level and goto old directory's line.
340 In case the proper dired file line cannot be found, refresh the dired
341 buffer and try again." t nil)
343 (autoload (quote dired-jump-other-window) "dired" "\
344 Like \\[dired-jump] (dired-jump) but in other window." t nil)
347 Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file
348 @file{../lisp/loaddefs.el} of the Emacs distribution already contains the
349 proper auto-loading for @code{dired-jump} so you need only put
352 (define-key global-map "\C-x\C-j" 'dired-jump)
355 @noindent in your @file{.emacs} file in order to have @kbd{C-x C-j} work
356 before @code{dired} is loaded.
358 @node Optional Installation File At Point, Special Notes, Optional Installation Dired Jump, Installation
359 @comment node-name, next, previous, up
360 @section Optional Installation File At Point
362 @cindex Binding @code{dired-x-find-file}
363 If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over
364 @code{find-file} (@pxref{Find File At Point}), then you will need to set
365 @code{dired-x-hands-off-my-keys} and make a call to the function
366 @code{dired-x-bind-find-file} in the @code{dired-load-hook}:
369 (add-hook 'dired-load-hook
372 ;; Bind dired-x-find-file.
373 (setq dired-x-hands-off-my-keys nil)
374 ;; Make sure our binding preference is invoked.
375 (dired-x-bind-find-file)
379 Alternatively, you can set the variable @emph{before} @file{dired-x.el} is
383 (add-hook 'dired-load-hook
385 ;; Bind dired-x-find-file.
386 (setq dired-x-hands-off-my-keys nil)
391 @node Special Notes, Omitting Files in Dired, Optional Installation File At Point, Installation
392 @comment node-name, next, previous, up
393 @section Special Notes
395 If @file{dired-x.el} was @emph{not} bundled with the version of GNU Emacs
396 installed at your site (i.e., not in the default @file{../lisp} directory)
397 then you must put the file @file{dired-x.el} in a directory known to GNU
398 Emacs. Examine the variable @code{load-path} for a list of these directories.
399 If you wish to add a new directory on this list of directories use something
400 like this in your @file{.emacs} file
404 (setq load-path (append
405 load-path ; default at top
407 "/the/directory/where/you/put/dired-x")))
410 @noindent If you wish to put the new directory at the head of the list (where
411 it will be found first) then you should use instead
415 (setq load-path (append
417 "/the/directory/where/you/put/dired-x")
418 load-path)) ; default at bottom
421 You must also byte compile the file (for example, hitting @kbd{B} in
422 @code{dired-mode}). When byte-compiling @file{dired-x.el} you may get
423 messages about functions @code{vm-visit-folder}, @code{Man-notify-when-ready},
424 and @code{reporter-submit-bug-report} not being defined. These are warnings
425 and should be ignored.
427 @noindent CAUTION: If you are using a version of GNU Emacs earlier than 19.20
428 than you may have to edit @file{dired.el}. The copy of @file{dired.el} in GNU
429 Emacs versions earlier than 19.20 incorrectly had the call to @code{run-hooks}
430 @emph{before} the call to @code{provide}. In such a case, it is possible that
431 byte-compiling and/or loading dired can cause an infinite loop. To prevent
432 this, make sure the line of code
435 (run-hooks 'dired-load-hook)
438 @noindent is the @emph{last} executable line in the file @file{dired.el}.
439 That is, make sure it comes @emph{after} the line
445 @node Omitting Files in Dired, Omitting Variables, Special Notes, Top
446 @comment node-name, next, previous, up
447 @chapter Omitting Files in Dired
449 @cindex Omitting Files in Dired
450 @dfn{Omitting} a file means removing it from the directory listing. Omitting
451 is useful for keeping Dired buffers free of ``uninteresting'' files (for
452 instance, auto-save, auxiliary, backup, and revision control files) so that
453 the user can concentrate on the interesting files. Like hidden files, omitted
454 files are never seen by Dired. Omitting differs from hiding in several
460 Omitting works on individual files, not on directories; an entire directory
461 cannot be omitted (though each of its files could be).
464 Omitting is wholesale; if omitting is turned on for a dired buffer, then all
465 uninteresting files listed in that buffer are omitted. The user does not omit
466 (or unomit) files one at a time.
469 Omitting can be automatic; uninteresting file lines in the buffer can be
470 removed before the user ever sees them.
473 Marked files are never omitted.
479 @findex dired-omit-toggle
480 (@code{dired-omit-toggle}) Toggle between displaying and omitting
481 ``uninteresting'' files. With a prefix argument, don't toggle and just mark
482 the files, but don't actually omit them.
486 In order to make Dired Omit work you first need to load @file{dired-x.el}
487 inside @code{dired-load-hook} (@pxref{Installation}) and then set
488 @code{dired-omit-files-p} in some way (@pxref{Omitting Variables}).
492 * Omitting Variables::
493 * Omitting Examples::
494 * Omitting Technical::
498 @node Omitting Variables, Omitting Examples, Omitting Files in Dired, Omitting Files in Dired
499 @comment node-name, next, previous, up
501 @section Omitting Variables
503 The following variables can be used to customize omitting.
507 @vindex dired-omit-files-p
508 @item dired-omit-files-p
512 @cindex How to make omitting the default in Dired
513 If non-@code{nil}, ``uninteresting'' files are not listed. Uninteresting
514 files are those whose filenames match regexp @code{dired-omit-files}, plus
515 those ending with extensions in @code{dired-omit-extensions}. @kbd{M-o}
516 (@code{dired-omit-toggle}) toggles its value, which is buffer-local. Put
519 (setq dired-omit-files-p t)
522 inside your @code{dired-mode-hook} to have omitting initially turned on in
523 @emph{every} Dired buffer (@pxref{Installation}). You can then use @kbd{M-o} to
524 unomit in that buffer.
526 To enable omitting automatically only in certain directories one can use Dired
527 Local Variables and put
531 dired-omit-files-p: t
536 into a file @file{.dired} (the default value of
537 @code{dired-local-variables-file}) in that directory (@pxref{Local Variables}).
540 @findex dired-omit-here-always
541 @item dired-omit-here-always
543 This is an interactive function that creates a local variables file exactly
544 like the example above (if it does not already exist) in the file
545 @code{dired-local-variables-file} in the current directory and then refreshes
546 the directory listing (@pxref{Local Variables}).
549 @vindex dired-omit-files
550 @item dired-omit-files
552 Default: @code{"^#\\|\\.$"}
554 Filenames matching this buffer-local regexp will not be displayed.
555 This only has effect when @code{dired-omit-files-p} is t.
557 The default value omits the special directories @file{.} and @file{..} and
558 autosave files (plus other files ending in ``.'') (@pxref{Omitting Examples}).
560 @vindex dired-omit-extensions
561 @item dired-omit-extensions
563 Default: The elements of @code{completion-ignored-extensions} (as defined in
564 the file @file{loaddefs.el} of the GNU Emacs distribution),
565 @code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions}
566 and @code{dired-texinfo-unclean-extensions}.
568 If non-@code{nil}, a list of extensions (strings) to omit from Dired listings.
569 Its format is the same as that of @code{completion-ignored-extensions}.
571 @vindex dired-omit-localp
572 @item dired-omit-localp
574 Default: @code{'no-dir}
576 The @var{localp} argument @code{dired-omit-expunge} passes to
577 @code{dired-get-filename}. If it is @code{'no-dir}, omitting is much faster,
578 but you can only match against the non-directory part of the filename. Set it
579 to @code{nil} if you need to match the whole pathname or @code{t} to match the
580 pathname relative to the buffer's top-level directory.
582 @item dired-omit-marker-char
583 @vindex dired-omit-marker-char
584 @cindex Omitting additional files
587 Temporary marker used by by Dired to implement omitting. Should never be used
588 as marker by the user or other packages. There is one exception to this rule:
592 (setq dired-mark-keys "\C-o")
593 ;; i.e., the value of dired-omit-marker-char
594 ;; (which is not defined yet)
597 anywhere in your @file{~/.emacs}, you will bind the @kbd{C-o} key to insert a
598 @kbd{C-o} marker, thus causing these files to be omitted in addition to the
599 usually omitted files. Unfortunately the files you omitted manually this way
600 will show up again after reverting the buffer, unlike the others.
604 @node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired
605 @comment node-name, next, previous, up
606 @section Examples of Omitting Various File Types
611 @cindex RCS files, how to omit them in Dired
612 @cindex Omitting RCS files in Dired
613 If you wish to avoid seeing RCS files and the RCS directory, then put
616 (setq dired-omit-files
617 (concat dired-omit-files "\\|^RCS$\\|,v$"))
620 in the @code{dired-load-hook} (@pxref{Installation}). This assumes
621 @code{dired-omit-localp} has its default value of @code{'no-dir} to make the
622 @code{^}-anchored matches work. As a slower alternative, with
623 @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of
624 @code{^} in the regexp.
627 @cindex Tib files, how to omit them in Dired
628 @cindex Omitting tib files in Dired
629 If you use tib, the bibliography program for use with @TeX{} and La@TeX{}, you
630 might want to omit the @file{INDEX} and the @file{-t.tex} files, then put
633 (setq dired-omit-files
634 (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$"))
638 in the @code{dired-load-hook} (@pxref{Installation}).
641 @cindex Dot files, how to omit them in Dired
642 @cindex Omitting dot files in Dired
643 If you do not wish to see @samp{dot} files (files starting with a @samp{.}),
647 (setq dired-omit-files
648 (concat dired-omit-files "\\|^\\..+$"))
652 in the @code{dired-load-hook} (@pxref{Installation}).
656 @node Omitting Technical, Local Variables, Omitting Examples, Omitting Files in Dired
657 @comment node-name, next, previous, up
658 @section Some Technical Details of Omitting
660 Loading @file{dired-x.el} will install Dired Omit by putting
661 @code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will
662 call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup}
663 in your @code{dired-mode-hook}.
665 @node Local Variables, Shell Command Guessing, Omitting Technical, Top
666 @comment node-name, next, previous, up
667 @chapter Local Variables for Dired Directories
669 @cindex Local Variables for Dired Directories
670 @vindex dired-local-variables-file
671 @vindex dired-enable-local-variables
673 When Dired visits a directory, it looks for a file whose name is the value of
674 variable @code{dired-local-variables-file} (default: @file{.dired}). If such
675 a file is found, Dired will temporarily insert it into the Dired buffer and
676 run @code{hack-local-variables}.
679 For example, if the user puts
683 dired-actual-switches: "-lat"
684 dired-omit-files-p: t
689 into a file called @file{.dired} in a directory then when that directory is
696 omitted automatically
700 You can set @code{dired-local-variables-file} to @code{nil} to suppress this.
701 The value of @code{dired-enable-local-variables} controls if and how these
702 local variables are read. This variable exists so that if may override the
703 default value of @code{enable-local-variables}.
706 Please see the GNU Emacs Manual to learn more about local variables.
707 @xref{File Variables,Local Variables in Files,Local Variables in
708 Files,emacs,The GNU Emacs Manual}.
711 The following variables affect Dired Local Variables
714 @vindex dired-local-variables-file
715 @item dired-local-variables-file
716 Default: @code{".dired"}
718 If non-@code{nil}, filename for local variables for Dired. If Dired finds a
719 file with that name in the current directory, it will temporarily insert it
720 into the dired buffer and run `hack-local-variables'.
722 @vindex dired-enable-local-variables
723 @item dired-enable-local-variables
726 Controls use of local-variables lists in dired. The value can be @code{t},
727 @code{nil}, or something else. A value of @code{t} means local-variables
728 lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means
729 they are ignored; anything else means query. This variable temporarily
730 overrides the value of @code{enable-local-variables} when the Dired Local
731 Variables are hacked.
734 @node Shell Command Guessing, Virtual Dired, Local Variables, Top
735 @comment node-name, next, previous, up
736 @chapter Shell Command Guessing
737 @cindex Guessing shell commands for files.
739 Based upon the name of a filename, Dired tries to guess what shell
740 command you might want to apply to it. For example, if you have point
741 on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
742 you want to @samp{tar xvf} it and suggest that as the default shell
745 The default will be mentioned in brackets and you can type @kbd{M-p} to get
746 the default into the minibuffer so that you can edit it, e.g., changing
747 @samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given
748 file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
749 @kbd{M-p} several times to see each of the matching commands.
751 Dired only tries to guess a command for a single file, never for a list
755 @item dired-guess-shell-alist-default
756 @vindex dired-guess-shell-alist-default
757 Predefined rules for shell commands. Set this to @code{nil} to turn guessing off.
758 The elements of @code{dired-guess-shell-alist-user} (defined by the
759 user) will override these rules.@refill
761 @item dired-guess-shell-alist-user
762 @vindex dired-guess-shell-alist-user
763 If non-@code{nil}, a user-defined alist of file regexps and their suggested
764 commands. These rules take precedence over the predefined rules in the
765 variable @code{dired-guess-shell-alist-default} (to which they are prepended)
766 when @code{dired-do-shell-command} is run).
769 Each element of the alist looks like
772 (@var{regexp} @var{command}@dots{})
775 where each @var{command} can either be a string or a lisp expression
776 that evaluates to a string. If several @var{COMMAND}s are given, all
777 will temporarily be pushed on the history.
779 You can set this variable in your @file{~/.emacs}. For example,
780 to add rules for @samp{.foo} and @samp{.bar} file extensions, write
783 (setq dired-guess-shell-alist-user
785 (list "\\.foo$" "@var{foo-command}");; fixed rule
786 ;; possibly more rules...
787 (list "\\.bar$";; rule with condition test
789 "@var{bar-command-1}"
790 "@var{bar-command-2}"))))
794 This will override any predefined rules for the same extensions.
796 @item dired-guess-shell-gnutar
797 @vindex dired-guess-shell-gnutar
798 @cindex Passing GNU tar its `z' switch.
801 If non-@code{nil}, name of the GNU tar executable (e.g., @samp{"tar"} or
802 @samp{"gnutar"}). GNU tar's @samp{z} switch is used for compressed tar files.
803 If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is
806 @item dired-guess-shell-gzip-quiet
807 @vindex dired-guess-shell-gzip-quiet
811 A non-@code{nil} value means that @code{-q} is passed to gzip overriding a
812 verbose GNU zip's @samp{GZIP} environment variable.
814 @item dired-guess-shell-znew-switches nil
815 @vindex dired-guess-shell-znew-switches nil
819 A string of switches passed to GNU zip's @file{znew}. An example is
820 @samp{"-K"} which will make @file{znew} keep a .Z file when it is smaller than
823 @item dired-shell-command-history nil
824 @vindex dired-shell-command-history nil
826 History list for commands that read dired-shell commands.
829 @node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top
830 @comment node-name, next, previous, up
831 @chapter Virtual Dired
833 @cindex Virtual Dired
834 @cindex Perusing ls listings
835 @cindex ls listings, how to peruse them in Dired
836 Using @dfn{Virtual Dired} means putting a buffer with Dired-like
837 contents in Dired mode. The files described by the buffer contents need
838 not actually exist. This is useful if you want to peruse an @samp{ls -lR}
839 output file, for example one you got from an FTP server. You can use
840 all motion commands usually available in Dired. You can also use
841 it to save a Dired buffer in a file and resume it in a later session.
843 @findex dired-virtual
845 @findex dired-virtual-revert
846 Type @kbd{M-x dired-virtual} to put the current buffer into virtual
847 Dired mode. You will be prompted for the top level directory of this
848 buffer, with a default value guessed from the buffer contents. To
849 convert the virtual to a real Dired buffer again, type @kbd{g} (which
850 calls @code{dired-virtual-revert}) in the virtual Dired buffer and
851 answer @samp{y}. You don't have to do this, though: you can relist
852 single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory
853 headerline, leaving the buffer in virtual Dired mode all the time.
855 @findex dired-virtual-mode
856 @vindex auto-mode-alist
857 The function @samp{dired-virtual-mode} is specially designed to turn on
858 virtual Dired mode from the @code{auto-mode-alist}. To edit all
859 @file{*.dired} files automatically in virtual Dired mode, put this into your
863 (setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode)
867 The regexp is a bit more complicated than usual to exclude ".dired"
868 local variable files.
870 @node Advanced Mark Commands, Advanced Cleaning Functions, Virtual Dired, Top
871 @comment node-name, next, previous, up
872 @chapter Advanced Mark Commands
877 @cindex Visiting several files at once
878 @cindex Simultaneous visiting of several files
879 @findex dired-do-find-marked-files
880 (@code{dired-do-find-marked-files}) Find all marked files at once displaying
881 simultaneously. If optional NOSELECT is non-@code{nil} then just find the
882 files but do not select. If you want to keep the dired buffer displayed, type
883 @kbd{C-x 2} first. If you want just the marked files displayed and nothing
884 else, type @kbd{C-x 1} first.
886 The current window is split across all files marked, as evenly as possible.
887 Remaining lines go to the bottom-most window. The number of files that can be
888 displayed this way is restricted by the height of the current window and the
889 variable @code{window-min-height}.
893 @item dired-mark-extension
894 @findex dired-mark-extension
895 Mark all files with a certain extension for use in later commands. A @samp{.}
896 is not automatically prepended to the string entered.
898 When called from lisp, @var{extension} may also be a list of extensions
899 and an optional argument @var{marker-char} specifies the marker used.
901 @item dired-flag-extension
902 @findex dired-flag-extension
903 Flag all files with a certain extension for deletion. A @samp{.} is
904 @emph{not} automatically prepended to the string entered.
909 * Advanced Cleaning Functions::
910 * Advanced Cleaning Variables::
911 * Special Marking Function::
915 @node Advanced Cleaning Functions, Advanced Cleaning Variables, Advanced Mark Commands, Advanced Mark Commands
916 @comment node-name, next, previous, up
918 @section Advanced Cleaning Functions
921 @item dired-clean-patch
922 @findex dired-clean-patch
923 Flag dispensable files created by the @samp{patch} program for deletion. See
924 variable @code{dired-patch-unclean-extensions}.
926 @item dired-clean-tex
927 @findex dired-clean-tex
928 Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for
929 deletion. See the following variables (@pxref{Advanced Cleaning Variables}):
933 @code{dired-tex-unclean-extensions}
935 @code{dired-texinfo-unclean-extensions}
937 @code{dired-latex-unclean-extensions}
939 @code{dired-bibtex-unclean-extensions}
942 @item dired-very-clean-tex
943 @findex dired-very-clean-tex
944 Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, and ".dvi"
948 @node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands
949 @comment node-name, next, previous, up
951 @section Advanced Cleaning Variables
953 @noindent Variables used by the above cleaning commands (and in the default value for
954 variable @code{dired-omit-extensions}, @pxref{Omitting Variables})
957 @item dired-patch-unclean-extensions
958 @vindex dired-patch-unclean-extensions
959 Default: @code{'(".rej" ".orig")}
961 List of extensions of dispensable files created by the @samp{patch} program.
963 @item dired-tex-unclean-extensions
964 @vindex dired-tex-unclean-extensions
965 Default: @code{'(".toc" ".log" ".aux")}
967 List of extensions of dispensable files created by @TeX{}.
969 @item dired-texinfo-unclean-extensions
970 @vindex dired-texinfo-unclean-extensions
971 Default: @code{'(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"}
972 @code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}
974 List of extensions of dispensable files created by @samp{texinfo}.
976 @item dired-latex-unclean-extensions
977 @vindex dired-latex-unclean-extensions
978 Default: @code{'(".idx" ".lof" ".lot" ".glo")}
980 List of extensions of dispensable files created by La@TeX{}.
982 @item dired-bibtex-unclean-extensions
983 @vindex dired-bibtex-unclean-extensions
984 Default: @code{'(".blg" ".bbl")}
986 List of extensions of dispensable files created by Bib@TeX{}.
989 @node Special Marking Function, Multiple Dired Directories, Advanced Cleaning Variables, Advanced Mark Commands
990 @comment node-name, next, previous, up
992 @section Special Marking Function
997 @findex dired-mark-sexp
998 @cindex Lisp expression, marking files with in Dired
999 @cindex Mark file by lisp expression
1000 (@code{dired-mark-sexp}) Mark files for which @var{predicate} returns
1001 non-@code{nil}. With a prefix argument, unflag those files instead.
1003 The @var{predicate} is a lisp expression that can refer to the following
1007 [@i{integer}] the inode of the file (only for @samp{ls -i} output)
1009 [@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or,
1010 with @samp{-k}, in KBytes)
1012 [@i{string}] file permission bits, e.g., @samp{"-rw-r--r--"}
1014 [@i{integer}] number of links to file
1018 [@i{string}] group (If the gid is not displayed by @samp{ls}, this
1019 will still be set (to the same as uid))
1021 [@i{integer}] file size in bytes
1023 [@i{string}] the time that @samp{ls} displays, e.g., @samp{"Feb 12 14:17"}
1025 [@i{string}] the name of the file
1027 [@i{string}] if file is a symbolic link, the linked-to name, else @samp{""}
1035 to mark all zero length files.
1037 To find out all not yet compiled Emacs lisp files in a directory, dired
1038 all @file{.el} files in the lisp directory using the wildcard
1039 @samp{*.el}. Then use @kbd{M-(} with
1041 (not (file-exists-p (concat name "c")))
1043 to mark all @file{.el} files without a corresponding @file{.elc} file.
1047 @node Multiple Dired Directories, Find File At Point, Special Marking Function, Top
1048 @comment node-name, next, previous, up
1049 @chapter Multiple Dired Directories and Non-Dired Commands
1051 @cindex Multiple Dired directories
1052 @cindex Working directory
1053 An Emacs buffer can have but one working directory, stored in the
1054 buffer-local variable @code{default-directory}. A Dired buffer may have
1055 several subdirectories inserted, but still has but one working
1056 directory: that of the top level Dired directory in that buffer. For
1057 some commands it is appropriate that they use the current Dired
1058 directory instead of @code{default-directory}, e.g., @code{find-file} and
1061 A general mechanism is provided for special handling of the working
1062 directory in special major modes:
1065 @item default-directory-alist
1066 @vindex default-directory-alist
1067 Default: @code{((dired-mode . (dired-current-directory)))}
1069 Alist of major modes and their opinion on @code{default-directory}, as a
1070 lisp expression to evaluate. A resulting value of @code{nil} is ignored
1071 in favor of @code{default-directory}.
1073 @item default-directory
1074 @findex default-directory
1075 Function with usage like variable @code{default-directory}, but knows about the
1076 special cases in variable @code{default-directory-alist}.
1079 @node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top
1080 @comment node-name, next, previous, up
1082 @section Find File At Point
1083 @cindex Visiting a file mentioned in a buffer
1084 @cindex Finding a file at point
1086 @file{dired-x} provides a method of visiting or editing a file mentioned in
1087 the buffer you are viewing (e.g., a mail buffer, a news article, a README
1088 file, etc.) or to test if that file exists. You can then modify this in the
1089 minibuffer after snatching the filename.
1091 When installed @file{dired-x} will substitute @code{dired-x-find-file} for
1092 @code{find-file} (normally bound to @kbd{C-x C-f}) and
1093 @code{dired-x-find-file-other-window} for @code{find-file-other-window}
1094 (normally bound to @kbd{C-x 4 C-f}).
1096 In order to use this feature, you will need to set
1097 @code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook}
1098 (@pxref{Optional Installation File At Point}).
1101 @item dired-x-find-file
1102 @findex dired-x-find-file
1105 @code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound
1106 to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which
1107 case it will use the filename at point as a guess for the file to visit.
1109 For example, if the buffer you were reading contained the words
1112 Available via anonymous ftp in
1114 /roebling.poly.edu:/pub/lisp/crypt++.el.gz
1117 then you could move your cursor to the line containing the ftp address and
1118 type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The
1119 minibuffer would read
1122 Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz
1125 with the point after the last @code{/}. If you hit return emacs will visit
1126 the file at that address. This also works with files on your own computer.
1128 @item dired-x-find-file-other-window
1129 @findex dired-x-find-file-other-window
1132 @code{dired-x-find-file-other-window} behaves exactly like
1133 @code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a
1134 prefix argument is used. See @code{dired-x-find-file} for more information.
1136 @item dired-x-hands-off-my-keys
1137 @vindex dired-x-hands-off-my-keys
1138 If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind
1139 @code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it
1140 should not bind @code{dired-x-find-file-other-window} over
1141 @code{find-file-other-window}. If you change this variable after
1142 @file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The
1143 default value of this variable is @kbd{t}; by default, the binding is not
1144 done. See @xref{Optional Installation File At Point}.
1146 @item dired-x-bind-find-file
1147 @findex dired-x-bind-find-file
1148 A function, which can be called interactively or in your @file{~/.emacs} file,
1149 that uses the value of @code{dired-x-hands-off-my-keys} to determine if
1150 @code{dired-x-find-file} should be bound over @code{find-file} and
1151 @code{dired-x-find-file-other-window} bound over
1152 @code{find-file-other-window}. See @xref{Optional Installation File At Point}.
1155 @node Miscellaneous Commands, Bugs, Find File At Point, Top
1156 @comment node-name, next, previous, up
1157 @chapter Miscellaneous Commands
1159 Miscellaneous features not fitting anywhere else:
1162 @item dired-find-subdir
1163 @vindex dired-find-subdir
1166 If non-@code{nil}, Dired does not make a new buffer for a directory if it can
1167 be found (perhaps as subdirectory) in some existing Dired buffer.
1169 If there are several Dired buffers for a directory, the most recently
1172 Dired avoids switching to the current buffer, so that if you have a
1173 normal and a wildcard buffer for the same directory, @kbd{C-x d RET}
1174 will toggle between those two.
1178 @findex dired-goto-file
1181 (@code{dired-goto-file}) Goto file line of a file (or directory).
1183 @findex dired-goto-subdir
1186 (@code{dired-goto-subdir}) Goto headerline of an inserted directory.
1187 This commands reads its argument with completion over the names of the
1188 inserted subdirectories.
1193 @cindex Adding to the kill ring in dired.
1195 @findex dired-copy-filename-as-kill
1196 (@code{dired-copy-filename-as-kill}) The @kbd{w} command puts the names
1197 of the marked (or next @var{N}) files into the kill ring, as if you had
1198 killed them with @kbd{C-w}. With a zero prefix argument @var{N}=0, use the
1199 complete pathname of each file. With a raw (just @kbd{C-u}) prefix argument,
1200 use the relative pathname of each marked file. As a special case, if no
1201 prefix argument is given and point is on a directory headerline, it
1202 gives you the name of that directory, without looking for marked files.
1204 @vindex dired-marked-files
1205 The list of names is also stored onto the variable @code{dired-marked-files}
1206 for use, e.g., in the @kbd{M-:} (@code{eval-expression}) command.
1208 As this command also displays what was pushed onto the kill ring you can
1209 use it to display the list of currently marked files in the
1210 echo area (unless you happen to be on a subdirectory headerline).
1212 You can then feed the file name to other Emacs commands with @kbd{C-y}.
1213 For example, say you want to rename a long filename to a slightly
1214 different name. First type @kbd{w} to push the old name onto the kill
1215 ring. Then type @kbd{R} to rename it and use @kbd{C-y} inside @kbd{R}'s
1216 minibuffer prompt to insert the old name at a convenient place.
1220 @cindex Toggling marks.
1221 @findex dired-do-toggle
1222 (@code{dired-do-toggle}) Toggle marks. That is, currently marked
1223 files become unmarked and vice versa. Files marked with other flags
1224 (such as `D') are not affected. The special directories `.' and `..'
1229 @item dired-smart-shell-command
1230 @findex dired-smart-shell-command
1231 @findex shell-command
1233 Like function @code{shell-command}, but in the current Dired directory.
1234 Bound to @kbd{M-!} in Dired buffers.
1239 @cindex Jumping to dired listing containing file.
1240 Bound to @kbd{C-x C-j}. Jump back to dired: If in a file, dired the current
1241 directory and move to file's line. If in Dired already, pop up a level and
1242 goto old directory's line. In case the proper Dired file line cannot be
1243 found, refresh the Dired buffer and try again.
1245 @item dired-jump-other-window
1246 @findex dired-jump-other-window
1248 Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window.
1250 These functions can be autoloaded so they work even though @file{dired-x.el}
1251 has not been loaded yet (@pxref{Optional Installation Dired Jump}).
1253 @vindex dired-bind-jump
1254 If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be
1255 bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to
1259 @cindex Reading mail.
1262 Bound to @kbd{V} if @code{dired-bind-vm} is t. Run VM on this file (assumed
1263 to be a UNIX mail folder).
1265 @vindex dired-vm-read-only-folders
1266 If you give this command a prefix argument, it will visit the folder
1267 read-only. This only works in VM~5, not VM~4.
1269 If the variable @code{dired-vm-read-only-folders} is t, @code{dired-vm} will
1270 visit all folders read-only. If it is neither @code{nil} nor @code{t}, e.g.,
1271 the symbol @code{'if-file-read-only}, only files not writable by you are
1272 visited read-only. This is the recommended value if you run VM 5.
1274 @vindex dired-bind-vm
1275 If the variable @code{dired-bind-vm} is t, @code{dired-vm} will be bound to
1276 @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound.
1279 @cindex Reading mail.
1281 Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this
1282 file (assumed to be mail folder in Rmail/BABYL format).
1286 @cindex Running info.
1288 Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info
1291 @vindex dired-bind-info
1292 If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
1296 @cindex Running man.
1299 Bound to @kbd{N}. Run man on this file (assumed to be a file in nroff
1302 @vindex dired-bind-man
1303 If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
1306 @item dired-do-relative-symlink
1307 @cindex Relative symbolic links.
1309 @findex dired-do-relative-symlink
1310 Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a
1311 directory, or make a relative symbolic link to the current file. This creates
1312 relative symbolic links like
1316 not absolute ones like
1318 foo -> /ugly/path/that/may/change/any/day/bar/foo
1320 @item dired-do-relative-symlink-regexp
1322 @findex dired-do-relative-symlink-regexp
1323 Bound to @kbd{%Y}. Relative symlink all marked files containing REGEXP to
1324 NEWNAME. See functions `dired-do-rename-regexp' and `dired-do-relsymlink' for
1328 @node Bugs, Concept Index, Miscellaneous Commands, Top
1329 @comment node-name, next, previous, up
1332 @findex dired-x-submit-report
1335 If you encounter a bug in this package, wish to suggest an
1336 enhancement, or want to make a smart remark, then type
1339 @kbd{M-x dired-x-submit-report}
1343 to set up an outgoing mail buffer, with the proper address to the
1344 @file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field.
1345 This command also inserts information that the Dired X maintainer can use to
1346 recreate your exact setup, making it easier to verify your bug or social
1349 Lawrence R. Dodd <dodd@@roebling.poly.edu>
1351 @node Concept Index, Command Index, Bugs, Top
1352 @comment node-name, next, previous, up
1353 @unnumbered Concept Index
1356 @node Command Index, Key Index, Concept Index, Top
1357 @comment node-name, next, previous, up
1358 @unnumbered Function Index
1361 @node Key Index, Variable Index, Command Index, Top
1362 @comment node-name, next, previous, up
1363 @unnumbered Key Index
1366 @node Variable Index, , Key Index, Top
1367 @comment node-name, next, previous, up
1368 @unnumbered Variable Index
1375 @c dired-x.texi ends here.