TL;DR: Grab the sample config. Read following docs in-depth if you want further customizations.
Here are some Dirvish exclusive features or aspects that Dired and Dirvish handled differently.
Dirvish uses dirvish-cache-dir
to store cached images and other persistent data.
Dirvish hides the file details by default. If you want the details at buffer
initialization like in Dired, you can customize the dirvish-hide-details
option.
For some filetypes such as media files or special documents, you may want to
open them with an external application by default. You can achieve this by
customizing the dirvish-open-with-programs
option. By default, it instructs
Emacs to open video/audio files using mpv
.
Dirvish avoids regex-based solutions as much as possible, this also applies to
the parsing of dired-listing/actual-switches
and dirvish-fd-switches
. As a
result, in order to setup dired-listing-switches
and dirvish-fd-switches
correctly, there are a few rules here:
- Make sure to use the long name of
ls
flags whenever possible.- use
--almost-all
instead of-A
- use
--sort=version
instead of-v
- use
- avoid duplicate flags which makes no sense.
These 3 patterns give the same directory listing result, but the
sort
attribute would only get correct information with the last one.--sort=version --sort=time
(duplicate, the latter flag is ignored)-v --sort-time
(same as the above one, meanwhile this also violates rule NO.1)--sort=time
- Use
dirvish-quicksort
instead ofdired-sort-toggle-or-edit
If you insist on using the
dired-sort-toggle-or-edit
command, you’ll have to obey the above rules when entering the ls flags.
A Dirvish session holds a set of Dired buffers and preview buffers that are
always reused during the session. The dired-find-alternate-file
command and
dired-kill-when-opening-new-dired-buffer
option is ignored in Dirvish.
Open a file using dired-find-file
quits the session. Alternatively, you can
quit it explicitly using dirvish-quit
(bound to q
by default) command.
See: the rationale behind buffer management in Dirvish
A session with a layout means it has a companion preview window and possibly
one or more parent windows. The session layout can be toggled, namely turn
on/off the preview and parent windows, using dirvish-layout-toggle
.
You can define multiple layouts in dirvish-layout-recipes
and cycle them through
dirvish-layout-switch
, by doing so you can have various pane-ratio for different
tasks. For example, 1:3 for image preview, 1:3:5 for general file preview, etc.
Apart from the hooks provided by Dired, Dirvish got some additions.
Hook | Description |
---|---|
dirvish-setup-hook | Executed after the root buffer is ready. |
dirvish-after-revert-hook | Executed after revert-buffer . |
dirvish-find-entry-hook | Executed after finding a entry. |
A Dirvish attribute is a visual element that shows up within the file line, which provides extra information for that file.
For now Dirvish ships with these attributes:
subtree-state
: A indicator for directory expanding state.all-the-icons
: File icons provided byall-the-icons.el
.vscode-icon
: File icons provided byvscode-icon.el
.collapse
: Collapse unique nested paths.git-msg
: Append git commit message to filename.vc-state
: The version control state at left fringe.file-size
: Show file size or directories file count at right fringe.file-time
(newly added): Show file modification time before thefile-size
.
Here is an overview of how does these attributes look like:
NOTE: file-time
was added recently (v2.0+), hence not in the screenshot.
To achieve this, the only thing you need to do is put these symbols into
dirvish-attributes
like this (order doesn’t matter):
;; Don't worry, Dirvish is still performant even if you enable all these attributes
(setq dirvish-attributes
'(vc-state subtree-state all-the-icons collapse git-msg file-time file-size))
Dirvish uses mode line and header line to display additional information for the
current directory or session. The mode line only span the directory panes by
default, to make them span all panes, just set dirvish-use-mode-line
to global
.
Setting the same option to nil hides the mode line in dirvish buffers.
To configure the content in the mode line, put the segments you wanted into
dirvish-mode-line-format
. There is also dirvish-mode-line-height
for you to set
the height of the mode line.
The header line can be customized in the same way with dirvish-use-header-line
,
dirvish-header-line-format
and dirvish-header-line-height
.
The dired-switches-in-mode-line
option is ignored in Dirvish.
;; Placement
;; (setq dirvish-use-header-line nil) ; hide header line (show the classic dired header)
;; (setq dirvish-use-mode-line nil) ; hide mode line
(setq dirvish-use-header-line 'global) ; make header line span all panes
;; Height
;;; '(25 . 35) means
;;; - height in single window sessions is 25
;;; - height in full-frame sessions is 35
(setq dirvish-header-line-height '(25 . 35))
(setq dirvish-mode-line-height 25) ; shorthand for '(25 . 25)
;; Segments
;;; 1. the order of segments *matters* here
;;; 2. it's ok to place raw string inside
(setq dirvish-header-line-format
'(:left (path) :right (free-space))
dirvish-mode-line-format
'(:left (sort file-time " " file-size symlink) :right (omit yank index)))
Dirvish uses different strategies towards various filetypes. You may want to
turn off preview for certain file extensions, dirvish-preview-disabled-exts
allows you to do that.
A preview dispatcher represents a strategy for file preview on certain
conditions. The variable dirvish-preview-dispatchers
, which holds all the active
dispatchers, has the default value looks like:
(image gif video audio epub pdf archive)
image
: preview image files, requiresimagemagick
gif
: preview GIF image files with animationvideo
: preview videos files with thumbnail, requiresffmpegthumbnailer
audio
: preview audio files with metadata, requiresmediainfo
epub
: preview epub documents, requires epub-thumbnailpdf
: preview pdf documents viapdf-tools
archive
: preview archive files such as.tar
,.zip
, requirestar
/unzip
Each dispatcher in this list handles the validation and preview content generation for the corresponding filetype. To enable/disable certain preview methods, just modify this list to your preferences.
For example, if for some reason you are not able to install epub-thumbnail or
want to display preview for epub files via packages like nov
, just remove the
epub
dispatcher like this:
(setq dirvish-preview-dispatchers (remove 'epub dirvish-preview-dispatchers))
Some of preview dispatchers, such as image
, generate cache images to improve the
preview experience. Everytime you enter a directory, Dirvish scans the the
content of that directory and computes the fileset of the directory that
requires cache image generation, the corresponding caches are generated later
when Emacs is idle.
You can tweak the behavior of auto caching or turn off this feature completely
by customizing the dirvish-media-auto-cache-threshold
option.
If you don’t want the media properties displayed in the preview buffer, you can
turn off dirvish-show-media-properties
.
Here are several examples to extend the preview capabilities of Dirvish.
The default pdf
preview method uses pdf-tools
to open the document, which works
fine for most of the pdf documents, but it feels sluggish for some documents
especially those big ones.
Dirvish provided an alternative PDF preview dispatcher pdf-preface
which
generates preface image for pdf files and use those preface images as the
preview. This allows the user to preview big pdf files in a non-blocking
fashion.
Note: this dispatcher requires the pdftoppm
executable.
(setq dirvish-preview-dispatchers
(cl-substitute 'pdf-preface 'pdf dirvish-preview-dispatchers))
Let’s assume you don’t like the default directory preview results provided by
Dired, you can create a directory previewer that utilizes the exa
command:
(dirvish-define-preview exa (file)
"Use `exa' to generate directory preview."
:require ("exa") ; tell Dirvish to check if we have the executable
(when (file-directory-p file) ; we only interest in directories here
`(shell . ("exa" "-al" "--color=always" "--icons"
"--group-directories-first" ,file))))
(add-to-list 'dirvish-preview-dispatchers 'exa)
This makes Dirvish use the output from exa
shell command as your preview content
for a directory entry. On a side note, you can customize the corresponding
ansi-color
faces to change the coloring in the preview window.
(set-face-attribute 'ansi-color-blue nil :foreground "#FFFFFF")
The extra commands in this sample config are documented at Extensions. All of
these extensions are inactive by default and will be loaded on demand (usually
you don’t have to require them explicitly if you installed dirvish from MELPA or
/path/to/dirvish/extensions/
is in your load-path
).
(use-package dirvish
:init
(dirvish-override-dired-mode)
:custom
(dirvish-quick-access-entries ; It's a custom option, `setq' won't work
'(("h" "~/" "Home")
("d" "~/Downloads/" "Downloads")
("m" "/mnt/" "Drives")
("t" "~/.local/share/Trash/files/" "TrashCan")))
:config
;; (dirvish-peek-mode) ; Preview files in minibuffer
;; (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode'
(setq dirvish-mode-line-format
'(:left (sort symlink) :right (omit yank index)))
(setq dirvish-attributes
'(all-the-icons file-time file-size collapse subtree-state vc-state git-msg))
(setq delete-by-moving-to-trash t)
(setq dired-listing-switches
"-l --almost-all --human-readable --group-directories-first --no-group")
:bind ; Bind `dirvish|dirvish-side|dirvish-dwim' as you see fit
(("C-c f" . dirvish-fd)
:map dirvish-mode-map ; Dirvish inherits `dired-mode-map'
("a" . dirvish-quick-access)
("f" . dirvish-file-info-menu)
("y" . dirvish-yank-menu)
("N" . dirvish-narrow)
("^" . dirvish-history-last)
("h" . dirvish-history-jump) ; remapped `describe-mode'
("s" . dirvish-quicksort) ; remapped `dired-sort-toggle-or-edit'
("v" . dirvish-vc-menu) ; remapped `dired-view-file'
("TAB" . dirvish-subtree-toggle)
("M-f" . dirvish-history-go-forward)
("M-b" . dirvish-history-go-backward)
("M-l" . dirvish-ls-switches-menu)
("M-m" . dirvish-mark-menu)
("M-t" . dirvish-layout-toggle)
("M-s" . dirvish-setup-menu)
("M-e" . dirvish-emerge-menu)
("M-j" . dirvish-fd-jump)))
Disclaimer: you can skip this section if you don’t care about mouse support.
Emacs 29 added mouse drag-and-drop support for Dired, the following settings will enable it:
(setq dired-mouse-drag-files t) ; added in Emacs 29
(setq mouse-drag-and-drop-region-cross-program t) ; added in Emacs 29
Some keybindings for mouse:
- left click: expanding/collapsing a directory or opening a file
- right click: opening a file/directory
- middle click: opening a file/directory in new window
(setq mouse-1-click-follows-link nil)
(define-key dirvish-mode-map (kbd "<mouse-1>") 'dirvish-subtree-toggle-or-open)
(define-key dirvish-mode-map (kbd "<mouse-2>") 'dired-mouse-find-file-other-window)
(define-key dirvish-mode-map (kbd "<mouse-3>") 'dired-mouse-find-file)
Dirvish integrates TRAMP at its core. Some features such as file preview are
disabled over synchronous TRAMP connections (see below on how to bypass this
limitation). For certain commands such as dirvish-yank
you should configure
your ssh authentication properly to avoid being stuck with a prompt you will not
be able to answer to in the child emacs.
(use-package tramp
:config
;; Enable full-featured Dirvish over TRAMP on certain connections
;; https://www.gnu.org/software/tramp/#Improving-performance-of-asynchronous-remote-processes-1.
(add-to-list 'tramp-connection-properties
(list (regexp-quote "/ssh:YOUR_HOSTNAME:")
"direct-async-process" t))
;; Tips to speed up connections
(setq tramp-verbose 0)
(setq tramp-chunksize 2000)
(setq tramp-use-ssh-controlmaster-options nil))
These packages are only listed here for discoverability.
(use-package dired-x
:config
;; Make dired-omit-mode hide all "dotfiles"
(setq dired-omit-files
(concat dired-omit-files "\\|^\\..*$")))
;; Addtional syntax highlighting for dired
(use-package diredfl
:hook
((dired-mode . diredfl-mode)
;; highlight parent and directory preview as well
(dirvish-directory-view-mode . diredfl-mode))
:config
(set-face-attribute 'diredfl-dir-name nil :bold t))
;; Use `all-the-icons' as Dirvish's icon backend
(use-package all-the-icons)
;; Or, use `vscode-icon' instead
;; (use-package vscode-icon
;; :config
;; (push '("jpg" . "image") vscode-icon-file-alist))
A PR to make dirvish as the default file manager in doom-emacs is under review.
- Install
gls
(GNU ls) from GNU coreutils
brew install coreutils
- Set
insert-directory-program
togls
(setq insert-directory-program "gls")
(setq dirvish-default-layout '(0 0.4 0.6))
Do not display continuation lines globally:
(setq-default truncate-lines t)
Or disable it only in dirvish:
(add-hook 'dirvish-find-entry-hook
(lambda (&rest _) (setq-local truncate-lines t)))
Also see #33
Set dirvish-reuse-session
to nil.
See Parsing switches and the sample config.
Disable all-the-icons-dired
and treemacs-icons-dired
.