Remove date from title page.
[emacs.git] / man / dired-x.texi
blobbf2d5288abc1fae79cdd43aaab203dc1e2db25ce
1 \input texinfo  @comment -*-texinfo-*-
3 @c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19
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.]
8 @c Version: 2.53
9 @c Date: 2001/02/25 14:05:46
10 @c Keywords: dired extensions
11 @c dired-x.el REVISION NUMBER: 2
13 @c State: Released
14 @c Ident: dired-x.texi,v 2.53 2001/02/25 14:05:46 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
21 @iftex
22 @finalout
23 @end iftex
24 @c @setchapternewpage odd               % For book style double sided manual.
25 @comment %**end of header (This is for running Texinfo on a region.)
27 @copying
28 Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004,
29 2005, 2006, 2007  Free Software Foundation, Inc.
31 @quotation
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.2 or
34 any later version published by the Free Software Foundation; with the
35 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
36 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
37 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
38 license is included in the section entitled ``GNU Free Documentation
39 License'' in the Emacs manual.
41 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
42 this GNU Manual, like GNU software.  Copies published by the Free
43 Software Foundation raise funds for GNU development.''
45 This document is part of a collection distributed under the GNU Free
46 Documentation License.  If you want to distribute this document
47 separately from the collection, you can do so by adding a copy of the
48 license to the document, as described in section 6 of the license.
49 @end quotation
50 @end copying
52 @dircategory Emacs
53 @direntry
54 * Dired-X: (dired-x).   Dired Extra Features.
55 @end direntry
57 @c      @smallbook
58 @tex
59 \overfullrule=0pt
60 %\global\baselineskip 30pt      % For printing in double spaces
61 @end tex
63 @titlepage
64 @sp 6
65 @c dired-x.el REVISION NUMBER
66 @center @titlefont{Dired Extra Version 2}
67 @sp 2
68 @center @titlefont{For The GNU Emacs}
69 @sp 1
70 @center @titlefont{Directory Editor}
71 @sp 4
72 @center Lawrence R@. Dodd
73 @c @center @t{dodd@@roebling.poly.edu}
74 @sp 5
75 @center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>)
76 @page
77 @vskip 0pt plus 1filll
78 @insertcopying
79 @end titlepage
81 @page
83 @ifnottex
85 @node Top
86 @comment  node-name,  next,  previous,  up
88 @noindent
89 This documents the ``extra'' features for Dired Mode for GNU Emacs that are
90 provided by the file @file{dired-x.el}.
92 @itemize @bullet
94 @item
95 Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>
97 @c dired-x.el REVISION NUMBER
98 @item
99 For @file{dired-x.el} revision 2
101 @c @item
102 @c Revision of this manual: 2.53 (2001/02/25 14:05:46)
104 @c @item
105 @c Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>.  @emph{Please} type
106 @c @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}).
108 @c @item
109 @c You can obtain a copy of this package via anonymous ftp in
110 @c @t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz}
112 @end itemize
114 @menu
115 * Introduction::
116 * Installation::
117 * Omitting Files in Dired::
118 * Local Variables::
119 * Shell Command Guessing::
120 * Virtual Dired::
121 * Advanced Mark Commands::
122 * Multiple Dired Directories::
123 * Find File At Point::
124 * Miscellaneous Commands::
125 * Bugs::
127 * GNU Free Documentation License::
128 * Concept Index::
129 * Command Index::
130 * Key Index::
131 * Variable Index::
133 @end menu
135 @end ifnottex
137 @node Introduction, Installation, Top, Top
138 @comment  node-name,  next,  previous,  up
139 @chapter Introduction
141 This documents the @emph{extra} features for Dired Mode for GNU Emacs.  It
142 is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el}.
144 In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has
145 been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs
146 19 distribution has been removed and some material was modified for agreement
147 with the functions in @file{dired.el} and @file{dired-aux.el}.  For example,
148 the code using @code{gmhist} history functions was replaced with code using
149 the mini-buffer history now built into GNU Emacs.  Finally, a few other
150 features have been added and a few more functions have been bound to keys.
152 @ifnottex
153 @menu
154 * Features::
155 * Technical Details::
156 @end menu
157 @end ifnottex
159 @node Features, Technical Details, , Introduction
160 @comment  node-name,  next,  previous,  up
161 @section Features
162 @cindex Features
164 Some features provided by Dired Extra
166 @enumerate
167 @item
168 Omitting uninteresting files from Dired listing.
169 @itemize @bullet
170 @xref{Omitting Files in Dired}.
171 @end itemize
172 @item
173 Local variables for Dired directories.
174 @itemize @bullet
175 @xref{Local Variables}.
176 @end itemize
177 @item
178 Guessing shell commands in Dired buffers.
179 @itemize @bullet
180 @xref{Shell Command Guessing}.
181 @end itemize
182 @item
183 Running Dired command in non-Dired buffers.
184 @itemize @bullet
185 @xref{Virtual Dired}.
186 @end itemize
187 @item
188 Finding a file mentioned in a buffer
189 @itemize @bullet
190 @xref{Find File At Point}.
191 @end itemize
192 @item
193 Commands using file marking.
194 @itemize @bullet
195 @xref{Advanced Mark Commands}.
196 @end itemize
197 @end enumerate
199 @noindent
200 @file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key
201 Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to
202 @code{dired-jump} (@pxref{Miscellaneous Commands}).  It may also bind @kbd{C-x
203 C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and
204 @code{dired-x-find-file-other-window}, respectively (@pxref{Find File At
205 Point}).
207 @node Technical Details, , Features, Introduction
208 @comment  node-name,  next,  previous,  up
209 @section Technical Details
210 @cindex Redefined functions
211 @cindex @file{dired-aux.el}
213 When loaded this code @emph{redefines} the following functions of GNU Emacs
214 from @file{dired.el}
216 @itemize @bullet
217 @item
218 @code{dired-clean-up-after-deletion}
219 @item
220 @code{dired-find-buffer-nocreate}
221 @item
222 @code{dired-initial-position}
223 @item
224 @code{dired-up-directory}
225 @end itemize
227 @noindent
228 and the following functions from @file{dired-aux.el}
230 @itemize @bullet
231 @item
232 @code{dired-add-entry}
233 @item
234 @code{dired-read-shell-command}
235 @end itemize
237 @node Installation, Omitting Files in Dired, Introduction, Top
238 @comment  node-name,  next,  previous,  up
239 @chapter Installation
241 @noindent
242 This manual describes the Dired features provided by the file
243 @file{dired-x.el}.  To take advantage of these features, you must load the
244 file and (optionally) set some variables.
246 @noindent
247 In your @file{.emacs} file in your home directory, or in the system-wide
248 initialization file @file{default.el} in the @file{site-lisp} directory, put
250 @example
251 (add-hook 'dired-load-hook
252           (lambda ()
253             (load "dired-x")
254             ;; Set dired-x global variables here.  For example:
255             ;; (setq dired-guess-shell-gnutar "gtar")
256             ;; (setq dired-x-hands-off-my-keys nil)
257             ))
258 (add-hook 'dired-mode-hook
259           (lambda ()
260             ;; Set dired-x buffer-local variables here.  For example:
261             ;; (dired-omit-mode 1)
262             ))
263 @end example
265 @noindent
266 This will load @file{dired-x.el} when Dired is first invoked (for example,
267 when you first type @kbd{C-x d}).
269 @ifnottex
270 @menu
271 * Optional Installation Dired Jump::
272 * Optional Installation File At Point::
273 @end menu
274 @end ifnottex
276 @node Optional Installation Dired Jump, Optional Installation File At Point, , Installation
277 @comment  node-name,  next,  previous,  up
278 @section Optional Installation Dired Jump
280 @cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window}
282 In order to have @code{dired-jump} and @code{dired-jump-other-window}
283 (@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and
284 @code{dired-x} have been properly loaded the user should set-up an autoload
285 for these functions.  In your @file{.emacs} file put
287 @example
288 ;; Autoload `dired-jump' and `dired-jump-other-window'.
289 ;; We autoload from FILE dired.el.  This will then load dired-x.el
290 ;; and hence define `dired-jump' and `dired-jump-other-window'.
291 (define-key global-map "\C-x\C-j" 'dired-jump)
292 (define-key global-map "\C-x4\C-j" 'dired-jump-other-window)
294 (autoload (quote dired-jump) "dired" "\
295 Jump to Dired buffer corresponding to current buffer.
296 If in a file, Dired the current directory and move to file's line.
297 If in Dired already, pop up a level and goto old directory's line.
298 In case the proper Dired file line cannot be found, refresh the Dired
299 buffer and try again." t nil)
301 (autoload (quote dired-jump-other-window) "dired" "\
302 Like \\[dired-jump] (dired-jump) but in other window." t nil)
303 @end example
305 Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file
306 @file{../lisp/loaddefs.el} of the Emacs distribution already contains the
307 proper auto-loading for @code{dired-jump} so you need only put
309 @example
310 (define-key global-map "\C-x\C-j" 'dired-jump)
311 @end example
313 @noindent
314 in your @file{.emacs} file in order to have @kbd{C-x C-j} work
315 before @code{dired} is loaded.
317 @node Optional Installation File At Point, , Optional Installation Dired Jump, Installation
318 @comment  node-name,  next,  previous,  up
319 @section Optional Installation File At Point
321 @cindex Binding @code{dired-x-find-file}
322 If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over
323 @code{find-file} (@pxref{Find File At Point}), then you will need to set
324 @code{dired-x-hands-off-my-keys} and make a call to the function
325 @code{dired-x-bind-find-file} in the @code{dired-load-hook}:
327 @example
328 (add-hook 'dired-load-hook
329           (lambda ()
330             (load "dired-x")
331             ;; Bind dired-x-find-file.
332             (setq dired-x-hands-off-my-keys nil)
333             ;; Make sure our binding preference is invoked.
334             (dired-x-bind-find-file)
335             ))
336 @end example
338 Alternatively, you can set the variable @emph{before} @file{dired-x.el} is
339 loaded
341 @example
342 (add-hook 'dired-load-hook
343           (lambda ()
344             ;; Bind dired-x-find-file.
345             (setq dired-x-hands-off-my-keys nil)
346             (load "dired-x")
347             ))
348 @end example
350 @node Omitting Files in Dired, Local Variables, Installation, Top
351 @comment  node-name,  next,  previous,  up
352 @chapter Omitting Files in Dired
354 @cindex Omitting Files in Dired
355 @cindex Uninteresting files
356 @dfn{Omitting} a file means removing it from the directory listing.  Omitting
357 is useful for keeping Dired buffers free of ``uninteresting'' files (for
358 instance, auto-save, auxiliary, backup, and revision control files) so that
359 the user can concentrate on the interesting files.  Like hidden files, omitted
360 files are never seen by Dired.  Omitting differs from hiding in several
361 respects:
363 @itemize @bullet
365 @item
366 Omitting works on individual files, not on directories; an entire directory
367 cannot be omitted (though each of its files could be).
369 @item
370 Omitting is wholesale; if omitting is turned on for a Dired buffer, then all
371 uninteresting files listed in that buffer are omitted.  The user does not omit
372 (or unomit) files one at a time.
374 @item
375 Omitting can be automatic; uninteresting file lines in the buffer can be
376 removed before the user ever sees them.
378 @item
379 Marked files are never omitted.
380 @end itemize
382 @table @kbd
383 @item M-o
384 @kindex M-o
385 @findex dired-omit-mode
386 (@code{dired-omit-mode}) Toggle between displaying and omitting
387 ``uninteresting'' files.
388 @item * O
389 @kindex * O
390 @findex dired-mark-omitted
391 (@code{dired-mark-omitted}) Mark ``uninteresting'' files.
392 @end table
394 @noindent
395 In order to make Dired Omit work you first need to load @file{dired-x.el}
396 inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate
397 @code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}).
399 @ifnottex
400 @menu
401 * Omitting Variables::
402 * Omitting Examples::
403 * Omitting Technical::
404 @end menu
405 @end ifnottex
407 @node Omitting Variables, Omitting Examples, , Omitting Files in Dired
408 @comment  node-name,  next,  previous,  up
410 @section Omitting Variables
412 @cindex Customizing file omitting
413 The following variables can be used to customize omitting.
415 @table @code
417 @vindex dired-omit-mode
418 @item dired-omit-mode
420 Default: @code{nil}
422 @cindex How to make omitting the default in Dired
423 If non-@code{nil}, ``uninteresting'' files are not listed.
424 Uninteresting files are those whose files whose names match regexp
425 @code{dired-omit-files}, plus those ending with extensions in
426 @code{dired-omit-extensions}.  @kbd{M-o} (@code{dired-omit-mode})
427 toggles its value, which is buffer-local.  Put
429 @example
430 (dired-omit-mode 1)
431 @end example
433 @noindent
434 inside your @code{dired-mode-hook} to have omitting initially turned on in
435 @emph{every} Dired buffer (@pxref{Installation}).  You can then use @kbd{M-o} to
436 unomit in that buffer.
438 To enable omitting automatically only in certain directories one can use Dired
439 Local Variables and put
441 @example
442 Local Variables:
443 dired-omit-mode: t
444 End:
445 @end example
447 @noindent
448 into a file @file{.dired} (the default value of
449 @code{dired-local-variables-file}) in that directory (@pxref{Local Variables}).
451 @table @code
452 @findex dired-omit-here-always
453 @item dired-omit-here-always
455 This is an interactive function that creates a local variables file exactly
456 like the example above (if it does not already exist) in the file
457 @code{dired-local-variables-file} in the current directory and then refreshes
458 the directory listing (@pxref{Local Variables}).
459 @end table
461 @vindex dired-omit-files
462 @item dired-omit-files
464 Default: @code{"^#\\|\\.$"}
466 Files whose names match this buffer-local regexp will not be displayed.
467 This only has effect when @code{dired-omit-mode}'s value is @code{t}.
469 The default value omits the special directories @file{.} and @file{..}  and
470 autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}).
472 @vindex dired-omit-extensions
473 @item dired-omit-extensions
475 Default: The elements of @code{completion-ignored-extensions},
476 @code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions}
477 and @code{dired-texinfo-unclean-extensions}.
479 If non-@code{nil}, a list of extensions (strings) to omit from Dired listings.
480 Its format is the same as that of @code{completion-ignored-extensions}.
482 @vindex dired-omit-localp
483 @item dired-omit-localp
485 Default:  @code{no-dir}
487 The @var{localp} argument @code{dired-omit-expunge} passes to
488 @code{dired-get-filename}.  If it is @code{no-dir}, omitting is much faster,
489 but you can only match against the non-directory part of the file name.  Set it
490 to @code{nil} if you need to match the whole file name or @code{t} to match the
491 file name relative to the buffer's top-level directory.
493 @item dired-omit-marker-char
494 @vindex dired-omit-marker-char
495 @cindex Omitting additional files
496 Default: @kbd{C-o}
498 Temporary marker used by Dired to implement omitting.  Should never be used
499 as marker by the user or other packages.  There is one exception to this rule:
500 by adding
502 @example
503 (setq dired-mark-keys "\C-o")
504 ;; i.e., the value of dired-omit-marker-char
505 ;; (which is not defined yet)
506 @end example
508 @noindent
509 to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a
510 @kbd{C-o} marker, thus causing these files to be omitted in addition to the
511 usually omitted files.  Unfortunately the files you omitted manually this way
512 will show up again after reverting the buffer, unlike the others.
514 @end table
516 @node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired
517 @comment  node-name,  next,  previous,  up
518 @section Examples of Omitting Various File Types
520 @itemize @bullet
522 @item
523 @cindex RCS files, how to omit them in Dired
524 @cindex Omitting RCS files in Dired
525 If you wish to avoid seeing RCS files and the @file{RCS} directory, then put
527 @example
528 (setq dired-omit-files
529       (concat dired-omit-files "\\|^RCS$\\|,v$"))
530 @end example
532 @noindent
533 in the @code{dired-load-hook} (@pxref{Installation}).  This assumes
534 @code{dired-omit-localp} has its default value of @code{no-dir} to make the
535 @code{^}-anchored matches work.  As a slower alternative, with
536 @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of
537 @code{^} in the regexp.
539 @item
540 @cindex Tib files, how to omit them in Dired
541 @cindex Omitting tib files in Dired
542 If you use @code{tib}, the bibliography program for use with @TeX{} and
543 La@TeX{}, and you
544 want to omit the @file{INDEX} and the @file{*-t.tex} files, then put
546 @example
547 (setq dired-omit-files
548       (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$"))
549 @end example
551 @noindent
552 in the @code{dired-load-hook} (@pxref{Installation}).
554 @item
555 @cindex Dot files, how to omit them in Dired
556 @cindex Omitting dot files in Dired
557 If you do not wish to see @samp{dot} files (files starting with a @file{.}),
558 then put
560 @example
561 (setq dired-omit-files
562       (concat dired-omit-files "\\|^\\..+$"))
563 @end example
565 @noindent
566 in the @code{dired-load-hook} (@pxref{Installation}).
568 @end itemize
570 @node Omitting Technical, , Omitting Examples, Omitting Files in Dired
571 @comment  node-name,  next,  previous,  up
572 @section Some Technical Details of Omitting
574 Loading @file{dired-x.el} will install Dired Omit by putting
575 @code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will
576 call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup}
577 in your @code{dired-mode-hook}.
579 @node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top
580 @comment  node-name,  next,  previous,  up
581 @chapter Local Variables for Dired Directories
583 @cindex Local Variables for Dired Directories
584 @vindex dired-local-variables-file
585 @vindex dired-enable-local-variables
586 @noindent
587 When Dired visits a directory, it looks for a file whose name is the value of
588 variable @code{dired-local-variables-file} (default: @file{.dired}).  If such
589 a file is found, Dired will temporarily insert it into the Dired buffer and
590 run @code{hack-local-variables}.
592 @noindent
593 For example, if the user puts
595 @example
596 Local Variables:
597 dired-actual-switches: "-lat"
598 dired-omit-mode: t
599 End:
600 @end example
602 @noindent
603 into a file called @file{.dired} in a directory then when that directory is
604 viewed it will be
606 @enumerate
607 @item
608 sorted by date
609 @item
610 omitted automatically
611 @end enumerate
613 @noindent
614 You can set @code{dired-local-variables-file} to @code{nil} to suppress this.
615 The value of @code{dired-enable-local-variables} controls if and how these
616 local variables are read.  This variable exists so that if may override the
617 default value of @code{enable-local-variables}.
619 @noindent
620 Please see the GNU Emacs Manual to learn more about local variables.
621 @xref{File Variables,Local Variables in Files,Local Variables in
622 Files,emacs,The GNU Emacs Manual}.
624 @noindent
625 The following variables affect Dired Local Variables
627 @table @code
628 @vindex dired-local-variables-file
629 @item dired-local-variables-file
630 Default: @code{".dired"}
632 If non-@code{nil}, file name for local variables for Dired.  If Dired finds a
633 file with that name in the current directory, it will temporarily insert it
634 into the Dired buffer and run @code{hack-local-variables}.
636 @vindex dired-enable-local-variables
637 @item dired-enable-local-variables
638 Default: @code{t}
640 Controls the use of local-variables lists in Dired.  The value can be @code{t},
641 @code{nil}, or something else.  A value of @code{t} means local-variables
642 lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means
643 they are ignored; anything else means query.  This variable temporarily
644 overrides the value of @code{enable-local-variables} when the Dired Local
645 Variables are hacked.
646 @end table
648 @node Shell Command Guessing, Virtual Dired, Local Variables, Top
649 @comment  node-name,  next,  previous,  up
650 @chapter Shell Command Guessing
651 @cindex Guessing shell commands for files.
653 Based upon the name of a file, Dired tries to guess what shell
654 command you might want to apply to it.  For example, if you have point
655 on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
656 you want to @samp{tar xvf} it and suggest that as the default shell
657 command.
659 The default is mentioned in brackets and you can type @kbd{M-p} to get
660 the default into the minibuffer and then edit it, e.g., to change
661 @samp{tar xvf} to @samp{tar tvf}.  If there are several commands for a given
662 file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
663 @kbd{M-p} several times to see each of the matching commands.
665 Dired only tries to guess a command for a single file, never for a list
666 of marked files.
668 @table @code
669 @item dired-guess-shell-alist-default
670 @vindex dired-guess-shell-alist-default
671 Predefined rules for shell commands.  Set this to @code{nil} to turn guessing off.
672 The elements of @code{dired-guess-shell-alist-user} (defined by the
673 user) will override these rules.@refill
675 @item dired-guess-shell-alist-user
676 @vindex dired-guess-shell-alist-user
677 If non-@code{nil}, a user-defined alist of file regexps and their suggested
678 commands.  These rules take precedence over the predefined rules in the
679 variable @code{dired-guess-shell-alist-default} (to which they are prepended)
680 when @code{dired-do-shell-command} is run).
681 @refill
683 Each element of the alist looks like
685 @example
686 (@var{regexp} @var{command}@dots{})
687 @end example
689 @noindent
690 where each @var{command} can either be a string or a Lisp expression
691 that evaluates to a string.  If several commands are given, all of
692 them will temporarily be pushed onto the history.
694 If @samp{*} in the shell command, that means to substitute the file
695 name.
697 You can set this variable in your @file{~/.emacs}.  For example,
698 to add rules for @samp{.foo} and @samp{.bar} file extensions, write
700 @example
701 (setq dired-guess-shell-alist-user
702       (list
703        (list "\\.foo$" "@var{foo-command}");; fixed rule
704        ;; possibly more rules...
705        (list "\\.bar$";; rule with condition test
706               '(if @var{condition}
707                    "@var{bar-command-1}"
708                  "@var{bar-command-2}"))))
709 @end example
711 @noindent
712 This will override any predefined rules for the same extensions.
714 @item dired-guess-shell-gnutar
715 @vindex dired-guess-shell-gnutar
716 @cindex Passing GNU Tar its @samp{z} switch.
717 Default: @code{nil}
719 If non-@code{nil}, this is the name of the GNU Tar executable (e.g.,
720 @samp{tar} or @samp{gnutar}).  GNU Tar's @samp{z} switch is used for
721 compressed tar files.
722 If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is
723 then used.
725 @item dired-guess-shell-gzip-quiet
726 @vindex dired-guess-shell-gzip-quiet
727 @cindex @code{gzip}
728 Default: @code{t}
730 A non-@code{nil} value means that @samp{-q} is passed to @code{gzip}
731 overriding a verbose option in the @env{GZIP} environment variable.
733 @item dired-guess-shell-znew-switches nil
734 @vindex dired-guess-shell-znew-switches nil
735 @cindex @code{znew}
736 Default: @code{nil}
738 A string of switches passed to @code{znew}.  An example is
739 @samp{-K} which will make @code{znew} keep a @file{.Z} file when it is
740 smaller than the @file{.gz} file.
742 @item dired-shell-command-history nil
743 @vindex dired-shell-command-history nil
745 History list for commands that read dired-shell commands.
746 @end table
748 @node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top
749 @comment  node-name,  next,  previous,  up
750 @chapter Virtual Dired
752 @cindex Virtual Dired
753 @cindex Perusing @code{ls} listings
754 @cindex @code{ls} listings, how to peruse them in Dired
755 Using @dfn{Virtual Dired} means putting a buffer with Dired-like
756 contents in Dired mode.  The files described by the buffer contents need
757 not actually exist.  This is useful if you want to peruse an @samp{ls -lR}
758 output file, for example one you got from an FTP server.  You can use
759 all motion commands usually available in Dired.  You can also use
760 it to save a Dired buffer in a file and resume it in a later session.
762 @findex dired-virtual
763 @kindex g
764 @findex dired-virtual-revert
765 Type @kbd{M-x dired-virtual} to put the current buffer into virtual
766 Dired mode.  You will be prompted for the top level directory of this
767 buffer, with a default value guessed from the buffer contents.  To
768 convert the virtual to a real Dired buffer again, type @kbd{g} (which
769 calls @code{dired-virtual-revert}) in the virtual Dired buffer and
770 answer @samp{y}.  You don't have to do this, though: you can relist
771 single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory
772 headerline, leaving the buffer in virtual Dired mode all the time.
774 @findex dired-virtual-mode
775 @vindex auto-mode-alist
776 The function @samp{dired-virtual-mode} is specially designed to turn on
777 virtual Dired mode from the @code{auto-mode-alist}.  To edit all
778 @file{*.dired} files automatically in virtual Dired mode, put this into your
779 @file{~/.emacs}:
781 @example
782 (setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode)
783                               auto-mode-alist))
784 @end example
786 @noindent
787 The regexp is a bit more complicated than usual to exclude @file{.dired}
788 local-variable files.
790 @node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top
791 @comment  node-name,  next,  previous,  up
792 @chapter Advanced Mark Commands
794 @table @kbd
795 @item F
796 @kindex F
797 @cindex Visiting several files at once
798 @cindex Simultaneous visiting of several files
799 @findex dired-do-find-marked-files
800 (@code{dired-do-find-marked-files}) Find all marked files at once displaying
801 them simultaneously.  If optional @var{noselect} is non-@code{nil} then just
802 find the
803 files but do not select.  If you want to keep the Dired buffer displayed, type
804 @kbd{C-x 2} first.  If you want just the marked files displayed and nothing
805 else, type @kbd{C-x 1} first.
807 The current window is split across all files marked, as evenly as possible.
808 Remaining lines go to the bottom-most window.  The number of files that can be
809 displayed this way is restricted by the height of the current window and the
810 variable @code{window-min-height}.
811 @end table
813 @table @code
814 @item dired-mark-extension
815 @findex dired-mark-extension
816 Mark all files with a certain extension for use in later commands.  A @samp{.}
817 is not automatically prepended to the string entered, you must type it
818 explicitly.
820 When called from Lisp, @var{extension} may also be a list of extensions
821 and an optional argument @var{marker-char} specifies the marker used.
823 @item dired-flag-extension
824 @findex dired-flag-extension
825 Flag all files with a certain extension for deletion.  A @samp{.} is
826 @emph{not} automatically prepended to the string entered.
827 @end table
829 @ifnottex
830 @menu
831 * Advanced Cleaning Functions::
832 * Advanced Cleaning Variables::
833 * Special Marking Function::
834 @end menu
835 @end ifnottex
837 @node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands
838 @comment  node-name,  next,  previous,  up
840 @section Advanced Cleaning Functions
842 @table @code
843 @item dired-clean-patch
844 @findex dired-clean-patch
845 Flag dispensable files created by the @samp{patch} program for deletion.  See
846 variable @code{dired-patch-unclean-extensions}.
848 @item dired-clean-tex
849 @findex dired-clean-tex
850 Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for
851 deletion.  See the following variables (@pxref{Advanced Cleaning Variables}):
853 @itemize @bullet
854 @item
855 @code{dired-tex-unclean-extensions}
856 @item
857 @code{dired-texinfo-unclean-extensions}
858 @item
859 @code{dired-latex-unclean-extensions}
860 @item
861 @code{dired-bibtex-unclean-extensions}
862 @end itemize
864 @item dired-very-clean-tex
865 @findex dired-very-clean-tex
866 Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo},
867 and @file{*.dvi} files for deletion.
868 @end table
870 @node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands
871 @comment  node-name,  next,  previous,  up
873 @section Advanced Cleaning Variables
875 @noindent Variables used by the above cleaning commands (and in the default value for
876 variable @code{dired-omit-extensions}, @pxref{Omitting Variables})
878 @table @code
879 @item dired-patch-unclean-extensions
880 @vindex dired-patch-unclean-extensions
881 Default: @code{(".rej" ".orig")}
883 List of extensions of dispensable files created by the @samp{patch} program.
885 @item dired-tex-unclean-extensions
886 @vindex dired-tex-unclean-extensions
887 Default:  @code{(".toc" ".log" ".aux")}
889 List of extensions of dispensable files created by @TeX{}.
891 @item dired-texinfo-unclean-extensions
892 @vindex dired-texinfo-unclean-extensions
893 Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"}
894 @code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}
896 List of extensions of dispensable files created by @samp{texinfo}.
898 @item dired-latex-unclean-extensions
899 @vindex dired-latex-unclean-extensions
900 Default: @code{(".idx" ".lof" ".lot" ".glo")}
902 List of extensions of dispensable files created by La@TeX{}.
904 @item dired-bibtex-unclean-extensions
905 @vindex dired-bibtex-unclean-extensions
906 Default:  @code{(".blg" ".bbl")}
908 List of extensions of dispensable files created by Bib@TeX{}.
909 @end table
911 @node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands
912 @comment  node-name,  next,  previous,  up
914 @section Special Marking Function
916 @table @kbd
917 @item M-(
918 @kindex M-(
919 @findex dired-mark-sexp
920 @cindex Lisp expression, marking files with in Dired
921 @cindex Mark file by Lisp expression
922 (@code{dired-mark-sexp}) Mark files for which @var{predicate} returns
923 non-@code{nil}.  With a prefix argument, unflag those files instead.
925 The @var{predicate} is a Lisp expression that can refer to the following
926 symbols:
927 @table @code
928 @item inode
929 [@i{integer}] the inode of the file (only for @samp{ls -i} output)
930 @item s
931 [@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or,
932 with @samp{-k}, in KBytes)
933 @item mode
934 [@i{string}]  file permission bits, e.g., @samp{-rw-r--r--}
935 @item nlink
936 [@i{integer}] number of links to file
937 @item uid
938 [@i{string}]  owner
939 @item gid
940 [@i{string}]  group  (If the gid is not displayed by @samp{ls}, this
941 will still be set (to the same as uid))
942 @item size
943 [@i{integer}] file size in bytes
944 @item time
945 [@i{string}]  the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17}
946 @item name
947 [@i{string}]  the name of the file
948 @item sym
949 [@i{string}]  if file is a symbolic link, the linked-to name, else @code{""}
950 @end table
952 @noindent
953 For example, use
954 @example
955 (equal 0 size)
956 @end example
957 to mark all zero length files.
959 To find out all not yet compiled Emacs Lisp files in a directory, Dired
960 all @file{.el} files in the lisp directory using the wildcard
961 @samp{*.el}.  Then use @kbd{M-(} with
962 @example
963 (not (file-exists-p (concat name "c")))
964 @end example
965 to mark all @file{.el} files without a corresponding @file{.elc} file.
967 @end table
969 @node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top
970 @comment  node-name,  next,  previous,  up
971 @chapter Multiple Dired Directories and Non-Dired Commands
973 @cindex Multiple Dired directories
974 @cindex Working directory
975 An Emacs buffer can have but one working directory, stored in the
976 buffer-local variable @code{default-directory}.  A Dired buffer may have
977 several subdirectories inserted, but it still has only one working
978 directory: that of the top-level Dired directory in that buffer.  For
979 some commands it is appropriate that they use the current Dired
980 directory instead of @code{default-directory}, e.g., @code{find-file} and
981 @code{compile}.
983 A general mechanism is provided for special handling of the working
984 directory in special major modes:
986 @table @code
987 @item default-directory-alist
988 @vindex default-directory-alist
989 Default: @code{((dired-mode . (dired-current-directory)))}
991 Alist of major modes and their notion of @code{default-directory}, as a
992 Lisp expression to evaluate.  A resulting value of @code{nil} is ignored
993 in favor of @code{default-directory}.
995 @item dired-default-directory
996 @findex dired-default-directory
997 Use this function like you would use the variable
998 @code{default-directory}, except that @code{dired-default-directory}
999 also consults the variable @code{default-directory-alist}.
1000 @end table
1002 @node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top
1003 @comment  node-name,  next,  previous,  up
1005 @section Find File At Point
1006 @cindex Visiting a file mentioned in a buffer
1007 @cindex Finding a file at point
1009 @file{dired-x} provides a method of visiting or editing a file mentioned in
1010 the buffer you are viewing (e.g., a mail buffer, a news article, a
1011 @file{README} file, etc.) or to test if that file exists.  You can then modify
1012 this in the minibuffer after snatching the file name.
1014 When installed @file{dired-x} will substitute @code{dired-x-find-file} for
1015 @code{find-file} (normally bound to @kbd{C-x C-f}) and
1016 @code{dired-x-find-file-other-window} for @code{find-file-other-window}
1017 (normally bound to @kbd{C-x 4 C-f}).
1019 In order to use this feature, you will need to set
1020 @code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook}
1021 (@pxref{Optional Installation File At Point}).
1023 @table @code
1024 @item dired-x-find-file
1025 @findex dired-x-find-file
1026 @kindex C-x C-f
1028 @code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound
1029 to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which
1030 case it will use the file name at point as a guess for the file to visit.
1032 For example, if the buffer you were reading contained the words
1034 @example
1035 Available via anonymous ftp in
1037    /roebling.poly.edu:/pub/lisp/crypt++.el.gz
1038 @end example
1040 @noindent
1041 then you could move your cursor to the line containing the ftp address and
1042 type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument).  The
1043 minibuffer would read
1045 @example
1046 Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz
1047 @end example
1049 @noindent
1050 with the point after the last @code{/}.  If you hit @key{RET}, emacs will visit
1051 the file at that address.  This also works with files on your own computer.
1053 @item dired-x-find-file-other-window
1054 @findex dired-x-find-file-other-window
1055 @kindex C-x 4 C-f
1057 @code{dired-x-find-file-other-window} behaves exactly like
1058 @code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a
1059 prefix argument is used.  See @code{dired-x-find-file} for more information.
1061 @item dired-x-hands-off-my-keys
1062 @vindex dired-x-hands-off-my-keys
1063 If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind
1064 @code{dired-x-find-file} over @code{find-file} on keyboard.  Similarly, it
1065 should not bind @code{dired-x-find-file-other-window} over
1066 @code{find-file-other-window}.  If you change this variable after
1067 @file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}.  The
1068 default value of this variable is @code{t}; by default, the binding is not
1069 done.  See @xref{Optional Installation File At Point}.
1071 @item dired-x-bind-find-file
1072 @findex dired-x-bind-find-file
1073 A function, which can be called interactively or in your @file{~/.emacs} file,
1074 that uses the value of @code{dired-x-hands-off-my-keys} to determine if
1075 @code{dired-x-find-file} should be bound over @code{find-file} and
1076 @code{dired-x-find-file-other-window} bound over
1077 @code{find-file-other-window}.  See @xref{Optional Installation File At Point}.
1078 @end table
1080 @node Miscellaneous Commands, Bugs, Find File At Point, Top
1081 @comment  node-name,  next,  previous,  up
1082 @chapter Miscellaneous Commands
1084 Miscellaneous features not fitting anywhere else:
1086 @table @code
1087 @item dired-find-subdir
1088 @vindex dired-find-subdir
1089 Default: @code{nil}
1091 If non-@code{nil}, Dired does not make a new buffer for a directory if it can
1092 be found (perhaps as subdirectory) in some existing Dired buffer.
1094 If there are several Dired buffers for a directory, the most recently
1095 used is chosen.
1097 Dired avoids switching to the current buffer, so that if you have a
1098 normal and a wildcard buffer for the same directory, @kbd{C-x d RET}
1099 will toggle between those two.
1100 @end table
1102 @table @kbd
1103 @findex dired-goto-subdir
1104 @kindex M-G
1105 @item M-G
1106 (@code{dired-goto-subdir}) Go to the header line of an inserted directory.
1107 This command reads its argument, with completion derived from the names of the
1108 inserted subdirectories.
1109 @end table
1111 @table @code
1112 @item dired-smart-shell-command
1113 @findex dired-smart-shell-command
1114 @findex shell-command
1115 @kindex M-!
1116 Like function @code{shell-command}, but in the current Dired directory.
1117 Bound to @kbd{M-!} in Dired buffers.
1119 @item dired-jump
1120 @findex dired-jump
1121 @kindex C-x C-j
1122 @cindex Jumping to Dired listing containing file.
1123 Bound to @kbd{C-x C-j}.  Jump back to Dired: If in a file, edit the current
1124 directory and move to file's line.  If in Dired already, pop up a level and
1125 go to old directory's line.  In case the proper Dired file line cannot be
1126 found, refresh the Dired buffer and try again.
1128 @item dired-jump-other-window
1129 @findex dired-jump-other-window
1130 @kindex C-x 4 C-j
1131 Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window.
1133 These functions can be autoloaded so they work even though @file{dired-x.el}
1134 has not been loaded yet (@pxref{Optional Installation Dired Jump}).
1136 @vindex dired-bind-jump
1137 If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be
1138 bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to
1139 @kbd{C-x 4 C-j}.
1141 @item dired-vm
1142 @cindex Reading mail.
1143 @kindex V
1144 @findex dired-vm
1145 Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}.  Run VM on this
1146 file (assumed to be a UNIX mail folder).
1148 @vindex dired-vm-read-only-folders
1149 If you give this command a prefix argument, it will visit the folder
1150 read-only.  This only works in VM 5, not VM 4.
1152 If the variable @code{dired-vm-read-only-folders} is @code{t},
1153 @code{dired-vm} will
1154 visit all folders read-only.  If it is neither @code{nil} nor @code{t}, e.g.,
1155 the symbol @code{if-file-read-only}, only files not writable by you are
1156 visited read-only.  This is the recommended value if you run VM 5.
1158 @vindex dired-bind-vm
1159 If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound
1160 to @kbd{V}.  Otherwise, @code{dired-bind-rmail} will be bound.
1162 @item dired-rmail
1163 @cindex Reading mail.
1164 @findex dired-rmail
1165 Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}.  Run Rmail on this
1166 file (assumed to be mail folder in Rmail/BABYL format).
1168 @item dired-info
1169 @kindex I
1170 @cindex Running info.
1171 @findex dired-info
1172 Bound to @kbd{I}.  Run Info on this file (assumed to be a file in Info
1173 format).
1175 @vindex dired-bind-info
1176 If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
1177 not be bound to @kbd{I}.
1179 @item dired-man
1180 @cindex Running man.
1181 @kindex N
1182 @findex dired-man
1183 Bound to @kbd{N}.  Run man on this file (assumed to be a file in @code{nroff}
1184 format).
1186 @vindex dired-bind-man
1187 If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
1188 be bound to @kbd{N}.
1190 @item dired-do-relsymlink
1191 @cindex Relative symbolic links.
1192 @kindex Y
1193 @findex dired-do-relsymlink
1194 Bound to @kbd{Y}.  Relative symlink all marked (or next ARG) files into a
1195 directory, or make a relative symbolic link to the current file.  This creates
1196 relative symbolic links like
1198 @example
1199     foo -> ../bar/foo
1200 @end example
1202 @noindent
1203 not absolute ones like
1205 @example
1206     foo -> /ugly/path/that/may/change/any/day/bar/foo
1207 @end example
1209 @item dired-do-relsymlink-regexp
1210 @kindex %Y
1211 @findex dired-do-relsymlink-regexp
1212 Bound to @kbd{%Y}.  Relative symlink all marked files containing
1213 @var{regexp} to @var{newname}.  See functions
1214 @code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more
1215 info.
1216 @end table
1218 @node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top
1219 @comment  node-name,  next,  previous,  up
1220 @chapter Bugs
1221 @cindex Bugs
1222 @findex dired-x-submit-report
1224 @noindent
1225 If you encounter a bug in this package, wish to suggest an
1226 enhancement, or want to make a smart remark, then type
1228 @example
1229 @kbd{M-x dired-x-submit-report}
1230 @end example
1232 @noindent
1233 to set up an outgoing mail buffer, with the proper address to the
1234 @file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field.
1235 This command also inserts information that the Dired X maintainer can use to
1236 recreate your exact setup, making it easier to verify your bug or social
1237 maladjustment.
1239 Lawrence R. Dodd
1240 @c <dodd@@roebling.poly.edu>
1242 @node GNU Free Documentation License, Concept Index, Bugs, Top
1243 @appendix GNU Free Documentation License
1244 @include doclicense.texi
1246 @node     Concept Index, Command Index, GNU Free Documentation License, Top
1247 @comment  node-name,  next,  previous,  up
1248 @unnumbered Concept Index
1249 @printindex cp
1251 @node     Command Index, Key Index, Concept Index, Top
1252 @comment  node-name,  next,  previous,  up
1253 @unnumbered Function Index
1254 @printindex fn
1256 @node     Key Index, Variable Index, Command Index, Top
1257 @comment  node-name,  next,  previous,  up
1258 @unnumbered Key Index
1259 @printindex ky
1261 @node     Variable Index,  , Key Index, Top
1262 @comment  node-name,  next,  previous,  up
1263 @unnumbered Variable Index
1264 @printindex vr
1266 @setchapternewpage odd
1267 @c @summarycontents
1268 @contents
1270 @bye
1271 @c dired-x.texi ends here.
1273 @ignore
1274    arch-tag: 201727aa-9318-4c74-a0d7-4f51c550c4de
1275 @end ignore