EXTENSIONS.org

Several small extension packages to Dirvish are maintained in the subdirectory extensions. They are installed together with Dirvish if you pull the package from MELPA. All of these extensions are inactive by default and will be loaded on demand (usually you don’t have to require them explicitly).

These extensions can augment Dirvish through different ways such as providing extra commands/attributes/preview methods, improving UI by the help of transient.el, integration with external tools, among other things. With them it is possible to adapt Dirvish such that it matches your preference or behaves similar to other familiar file explorers.

Multi-stage copy/pasting of files (dirvish-yank.el)

Here is a quote from dired-ranger that justified the dired-ranger-move/paste commands:

A feature present in most orthodox file managers is a “two-stage” copy/paste process. Roughly, the user first selects some files, “copies” them into a clipboard and then pastes them to the target location. This workflow is missing in dired.

In dired, user first marks the files, then issues the dired-do-copy command which prompts for the destination. The files are then copied there. The dired-dwim-target option makes this a bit friendlier—if two dired windows are opened, the other one is automatically the default target.

With the multi-stage operations, you can gather files from multiple dired buffers into a single “clipboard”, then copy or move all of them to the target location.

Multi-stage copy/paste, asynchronous I/O, work with TRAMP, dirvish-yank has all of them. This package also provides the dirvish-rsync command, which can be seen as a alternative to dired-rsync package. dirvish-yank and friends also handles file operations on the same remote host, see: stsquad/dired-rsync#24.

To copy/move/symlink/hardlink files from A to B, just mark the files in A, go to B, and paste them with dirvish-yank/move/symlink/hardlink.

See also: comparison with dired-ranger

Group files with custom filter stack (dirvish-emerge.el)

This extension lets you split the file list into different groups by various criteria. These groups are then displayed in the same manner as ibuffer.

The variable dirvish-emerge-groups contains filter criteria of groups. Althought you can set this variable globally, a more appropriate way would be set it directory locally. In that case, it is recommended to compose and save this variable to .dir-locals.el by the help of dirvish-emerge-menu, which saves the manual editing.

Placing the point on the group header and hitting TAB folds it. Hitting TAB again expands it. Here is a quick demo.

emerge.mp4

The dirvish-emerge-groups used in the above video is the following (compose and saved to .dir-locals.el using dirvish-emerge-menu):

'(("Recent files" (predicate . recent-files-2h))
  ("Documents" (extensions "pdf" "tex" "bib" "epub"))
  ("Video" (extensions "mp4" "mkv" "webm"))
  ("Pictures" (extensions "jpg" "png" "svg" "gif"))
  ("Audio" (extensions "mp3" "flac" "wav" "ape" "aac"))
  ("Archives" (extensions "gz" "rar" "zip")))

Minibuffer file preview (dirvish-peek.el)

dirvish-peek-mode gives you a preview window when narrowing file candidates using minibuffer. It displays file preview for all of the file name narrowing commands in the same way as dirvish command.

peek.mp4

Figure 1. A demo of find-library and find-file commands after dirvish-peek-mode enabled.

The dirvish-peek-display-alist option allows you to control the window placement of the peek window.

dirvish-peek-mode currently supports vertico, selectrum, ivy and icomplete[-vertical].

Version-control (git) integration (dirvish-vc.el)

This extension gives Dirvish the ablity to display version-control data in different ways. For now we have:

• vc-state: an attribute to display the VC state as a bitmap at left fringe
• git-msg: an attribute to display git commit messages after the file name
• vc-[log|diff|blame]: VC info preview dispatchers

Be sure to put the vc-** preview dispatcher at the beginning of dirvish-preview-dispatchers if you want to enable them by default, otherwise the preview content might be intercepted by other preview dispatchers.

These 3 vc-* preview dispatchers are mutually exclusive, which means you should not set dirvish-preview-dispatchers like this:

;; `vc-diff' will be ignored
(vc-log vc-diff ...)

The dirvish-vc-menu (bound to ? v by default) allows you to call all available VC commands, it also provides a way to cycle through the vc-* preview methods.

vc.mp4

Figure 2. Toggle vc-state and git-msg (attribute), cycle through vc-[log|diff|blame].

Show icons at front of file name (dirvish-icons.el)

This extension provides two attributes: all-the-icons and vscode-icon. To tweak the appearance of the icons, you have these options:

• dirvish-all-the-icons-height: Height of icons from all-the-icons.
• dirvish-all-the-icons-offset: Vertical offset of icons from all-the-icons.
• dirvish-all-the-icons-palette: Coloring style used for all-the-icons.
• dirvish-vscode-icon-size: Image size of icons from vscode-icon.

Toggle Dirvish in side window (dirvish-side.el)

This extension provides the dirvish-side command. It toggles a Dirvish session as a sidebar in the frame. These customization options are available:

• dirvish-side-display-alist: Display actions for the side window.
• dirvish-side-window-parameters: Window parameters for the side window.
• dirvish-side-width: Width of the side window.
• dirvish-side-open-file-window-function: Set window of for opened files.
• dirvish-side-auto-expand: Whether to auto expand parent directories of current file.

When dirvish-side-follow-mode is enabled, the visible side session will select the current buffer’s filename, similar to treemacs-follow-mode in treemacs. It will also visits the latest project-root after switching to a new project.

Setup ls switches on the fly (dirvish-ls.el)

This extension provides commands to changing the ls listing switches like a breeze. No manual editing anymore!

Figure 3. left: dirvish-quicksort right: dirvish-ls-switches-menu

Dirvish as the interface of fd (dirvish-fd.el)

This is the BEST fd frontend, period.

Here is a quick demo.

Peek.2022-05-28.15-08.mp4

Too fast? Let’s break it down:

1. M-x dirvish-fd, input test as the search pattern and confirm
2. Oh, too many results. How about some additional filtering?
3. M-x dirvish-fd-switches-menu
4. Press f (show file only，no directories)
5. Press -e, input ”py,yaml”, meaning search for these 2 extensions only
6. Press -E, input ”Emacs”, exclude the glob in the results
7. Press RET, refresh the results

Feel free to experiment with other switches. A bonus tip: dirvish-quicksort and dirvish-ls-switches-menu also works in this buffer.

If you have orderless installed, you can have an input string that looks like test ~Emacs .\(py\|yaml\)$, by doing this you can skip the -e and -E steps in the above example. The actual matching styles being applied are determined by your orderless config. Also see dirvish-fd-regex-builder.

This extension also provides the dirvish-fd-jump command which allows you to go to any directory in the file system using results from fd command as completions.

Turn Dirvish into a tree browser (dirvish-subtree.el)

This extension gives Dirvish the ability to toggle a directory as subtree (dirvish-subtree-toggle), which can be seen as a stripped-down version of dired-subtree.

You can use dirvish-subtree-toggle to toggle the directory under the cursor as a subtree. Add subtree-state to dirvish-attributes gives you an indicator about whether the directory is expanded or not.

History navigation commands (dirvish-history.el)

Command	Description
dirvish-history-jump	Go to recently visited directories
dirvish-history-go-forward	Go forward history (session locally)
dirvish-history-go-backward	Go backward history (session locally)
dirvish-history-last	Go to most recent used Dirvish buffer

Quick keys for frequently visited places (dirvish-quick-access.el)

This extension gives you the ability of jumping to anywhere in the filesystem with minimal (2 usually) keystrokes. Just define the entries in dirvish-quick-access-entries and access them by calling dirvish-quick-access.

Collapse unique nested paths (dirvish-collapse.el)

This extension provides the collapse attribute.

Often times we find ourselves in a situation where a single file or directory is nested in a chain of nested directories with no other content. This is sometimes due to various mandatory layouts demanded by packaging tools or tools generating these deeply-nested “unique” paths to disambiguate architectures or versions (but we often use only one anyway). If the user wants to access these directories they have to quite needlessly drill-down through varying number of “uninteresting” directories to get to the content.

– from dired-collapse

See also: comparison with dired-collapse

Live-narrowing of Dirvish buffer (dirvish-narrow.el)

This extension provides live filtering of files in dirvish buffers. In general, after calling dirvish-narrow you type a filter string into the minibuffer. After each change the changes automatically reflect in the buffer. Typing RET will exit the live filtering mode and leave the dired buffer in the narrowed state. Typing C-g will cancel the narrowing and restore the original view. To bring it back to the original view after the narrowing, just call revert-buffer (usually bound to g).

If you have orderless installed, you can have an input string that looks like test ~Emacs .\(py\|yaml\)$, meaning:

• match test
• match .py or .yaml files
• exclude results containing Emacs

The actual matching styles being applied are determined by your orderless config. Also see dirvish-narrow-regex-builder.