CUSTOMIZING.org

TL;DR: Grab the sample config. Read following docs in-depth if you want further customizations.

---

In relation to Dired

Here are some Dirvish exclusive features or aspects that Dired and Dirvish handled differently.

Cache directory

Dirvish uses dirvish-cache-dir to store cached images and other persistent data.

File details display

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.

Open files externally

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.

Parsing switches

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:

1. Make sure to use the long name of ls flags whenever possible.
   • use --almost-all instead of -A
   • use --sort=version instead of -v
2. 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
3. Use dirvish-quicksort instead of dired-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.

Buffer management

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

Multiple window layouts

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.

Hooks

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.

Dirvish “attributes”

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 by all-the-icons.el.
• vscode-icon: File icons provided by vscode-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 the file-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))

Mode line | Header line

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

File preview

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, requires imagemagick
• gif: preview GIF image files with animation
• video: preview videos files with thumbnail, requires ffmpegthumbnailer
• audio: preview audio files with metadata, requires mediainfo
• epub: preview epub documents, requires epub-thumbnail
• pdf: preview pdf documents via pdf-tools
• archive: preview archive files such as .tar, .zip, requires tar / 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.

Preview PDF files with generated thumbnail

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

Preview directory using exa command

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")

Sample config

Dirvish

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

Mouse settings

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)

TRAMP integration

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

Complementary packages

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

Working with Doom Emacs (WIP)

A PR to make dirvish as the default file manager in doom-emacs is under review.

FAQ

listing directory failed but ‘access-file’ worked error on macOS

1. Install gls (GNU ls) from GNU coreutils

brew install coreutils

1. Set insert-directory-program to gls

(setq insert-directory-program "gls")

How to hide the parent directory?

(setq dirvish-default-layout '(0 0.4 0.6))

How to hide continuation lines?

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 alexluigit#33

How to kill all session buffers on quit?

Set dirvish-reuse-session to nil.

Dirvish does not respect listing switches?

See Parsing switches and the sample config.

Why do I have duplicate icon columns?

Disable all-the-icons-dired and treemacs-icons-dired.