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 of GNU ls

To ensure Dirvish correctly parses dired-listing-switches, adhere to specific formatting rules when setting this variable. These rules ensure compatibility with the dirvish-ls extension powered by transient, allowing for straightforward decomposition and composition of included switches.

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

These rules should also be followed when setting the dirvish-fd-switches option. For changing the sort criteria of a buffer, dirvish-quicksort is recommended over dired-sort-toggle-or-edit. If you choose to use dired-sort-toggle-or-edit, ensure the entered ls flags adhere to the specified rules.

Additionally, it’s best to avoid using options newly introduced in GNU ls. For instance, while the --time=mtime option might function correctly on your local machine with ls/gls version 9.6, a remote host running GNU ls version 8.3 can not recognize it. Consequently, if dired-listing-switches includes such an switch, Dirvish will display an empty buffer when you attempt to open any path on that remote host.

Buffer management

A Dirvish session maintains a collection of Dired and preview buffers that are reused throughout the session.

When you quit a Dirvish session, either by using dirvish-quit command (bound to q) or by opening a file (which automatically quits the session), all Dired buffers except the index buffer are killed.

The dired-find-alternate-file command is ignored within Dirvish, but this should not be a concern, as Dirvish eliminates the need for manual Dired buffer management.

From Dirvish v2.1 onwards, the dired-kill-when-opening-new-dired-buffer option is honored. This means that opening a new Dired buffer within a Dirvish session will kill the previous one, ensuring that each session primarily retains only its index buffer.

If you prefer Dirvish to kill all Dired buffers when quitting, instead of leaving the last index buffer open, set dirvish-reuse-session to nil.

See: the rationale behind buffer management in Dirvish

Hooks

Apart from the hooks provided by Dired, Dirvish got some additions.

• dirvish-setup-hook: Functions called when directory data for the root buffer is ready.
• dirvish-after-revert-hook: Functions called after running revert-buffer command.
• dirvish-find-entry-hook: Functions called before a Dired buffer is displayed.
• dirvish-preview-setup-hook: Functions called in the regular preview buffer.

find-dired integration

find-dired should work seamlessly with Dirvish. However, there are currently no plans to integrate Dirvish further into its output buffer, as dirvish-fd offers a superior alternative. See Extensions:dirvish-fd.el for more information.

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

Multile layout recipies

In Dirvish, a Dirvish window with an associated layout includes a preview window and, optionally, one or more parent windows. You can toggle the visibility of the session layout (preview and parent windows) using dirvish-layout-toggle.

You can define multiple layouts in dirvish-layout-recipes and cycle through them with dirvish-layout-switch. This allows you to have different pane ratios for various tasks. For example, use a 1:3 ratio for image previews or a 1:3:5 ratio for general file previews.

Mode line | Header line

Dirvish displays information about the current directory or session in the mode line and header line. These features are enabled by default and include sensible default configurations.

Changing its placement, height and format

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 strings in it as separators
(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)))

Special buffers for displaying mode-line and header-line

When Dirvish uses a layout that occupies the entire frame, the mode-line and header-line are displayed in separate buffers and their corresponding windows. These buffers are initialized with dirvish-misc-mode. To customize the settings of these buffers, append your configuration to dirvish-misc-mode-hook.

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

• image: preview image files, requires imagemagick
• gif: preview GIF image files with animation
• video: preview videos files with thumbnail, requires ffmpegthumbnailer on Linux/macOS requires mtn on Windows (special thanks to @samb233!)
• 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
• dired: preview directories using dired (asynchronously)

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. Every time 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.

The dirvish-preview-dired-sync-omit option allows dired preview buffers to sync your dired-omit-mode and its settings from the root window, it is turned off by default.

Dirvish also offers these user options to customize its preview behavior. Refer to the docstrings of these options for detailed information.

• dirvish-preview-buffers-max-count
• dirvish-preview-disabled-exts
• dirvish-preview-environment
• dirvish-preview-large-file-threshold

Customizations for preview buffers

There are several types of buffer can be placed in the preview window in Dirvish.

Directory files listing

The dired preview dispatcher creates buffers in dirvish-directory-view-mode. This mode is also used for the parent directory listing buffers. Consequently, a single hook can configure both the parent buffer and the dired preview buffer.

(add-hook 'dirvish-directory-view-mode-hook #'diredfl-mode)

Regular files with certain major mode

When a regular file with certain major mode is being previewed, you can change its settings by the dirvish-preview-setup-hook.

Special preview buffer

A dirvish-special-preview-mode buffer is displayed in the preview window for all the rest filetypes. This includes cases for shell command output, error/warning info display, image and metadata and etc.

Other use cases

Here are several examples on how 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 eza 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 eza command:

(dirvish-define-preview eza (file)
  "Use `eza' to generate directory preview."
  :require ("eza") ; tell Dirvish to check if we have the executable
  (when (file-directory-p file) ; we only interest in directories here
    `(shell . ("eza" "-al" "--color=always" "--icons=always"
               "--group-directories-first" ,file))))

(setq dirvish-preview-dispatchers
      (cl-substitute 'eza 'dired dirvish-preview-dispatchers))

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 if your theme doesn’t have good integration with the ansi-color package.

(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
        '(nerd-icons file-time file-size collapse subtree-state vc-state git-msg)
        dirvish-side-attributes
        '(vc-state file-size nerd-icons collapse))
  (setq delete-by-moving-to-trash t)
  (setq dired-listing-switches
        "-l --almost-all --human-readable --group-directories-first --no-group")
  :bind ; Bind `dirvish-fd|dirvish-side|dirvish-dwim' as you see fit
  (("C-c f" . dirvish)
   :map dirvish-mode-map          ; Dirvish inherits `dired-mode-map'
   ("?"   . dirvish-dispatch)     ; contains most of sub-menus in dirvish extensions
   ("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))

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 "\\|^\\..*$")))

;; Additional 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 `nerd-icons' as Dirvish's icon backend
(use-package nerd-icons)

;; Or, use `vscode-icon' instead
;; (use-package vscode-icon
;;   :config
;;   (push '("jpg" . "image") vscode-icon-file-alist))