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.

In addition to implementing the core logic described above, this extension also supports several frequently used commands. To transfer files from source to destination, mark the desired files, navigate to the destination, and use one of the dirvish-yank, dirvish-move, dirvish-symlink, dirvish-relative-symlink or dirvish-hardlink commands to complete the transfer. All of these commands are executed ASYNCHRONOUSLY without any extra setups.

See also: comparison with dired-ranger

Integration with rsync command (dirvish-rsync.el)

This extension introduces dirvish-rsync, which requires rsync executable, mirroring the functionality of Alex Bennée’s dired-rsync. It also provides a transient menu dirvish-rsync-switches-menu, for temporary adjustments to dirvish-rsync-args.

Compare to dired-rsync

• dirvish-rsync also handles file operations on the same remote host. See: stsquad/dired-rsync#24.
• dirvish-rsync takes advantages of the same multi-stage action mechanism in dirvish-yank. Meaning that you should mark files first then goto target directory and invoke dirvish-rsync there, instead of trying to do it in the way of dired-do-copy.
• It gathers marked files from multiple Dired buffers.

User options

Configure dirvish-rsync-program and dirvish-rsync-args to specify the executable path and command line arguments of rsync.

dirvish-rsync-r2r-ssh-port, dirvish-rsync-r2r-ssh-user and dirvish-rsync-r2r-use-direct-connection are provided to deal with the remote to remote connections (thanks to @dvzubarev).

Use dirvish-rsync-shortcut-key-for-yank-menu and dirvish-rsync-use-yank-menu to adjust the shortcut key of dirvish-rsync in dirvish-yank-menu.

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

This extension organizes your file list into groups based on your chosen criteria, presented similarly to ibuffer. You can collapse and expand these groups by pressing TAB on the group header. For a quick demonstration, see this video:

emerge.mp4

The variable dirvish-emerge-groups specifies filter criteria for groups. In the video, the value used appears to be:

;; Header string |    Type    |    Criterias
'(("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")))

Avoid manually editing this variable. The recommended way to modify, compose, apply, or save it (to .dir-locals.el) is with the dirvish-emerge-menu transient menu, which is how the value above was created.

While you can set this variable globally, saving it to .dir-locals.el is more preferable because:

• Different directory types may require different groups to be emerged.
• Applying these filters in large directories can take a significant amount of time.

To ensure the groups defined in dirvish-emerge-groups are emerged upon entering a directory, add dirvish-emerge-mode to dirvish-setup-hook.

(add-hook 'dirvish-setup-hook 'dirvish-emerge-mode)

Minibuffer file preview (dirvish-peek.el)

This extension introduces dirvish-peek-mode, a minor mode that enables file previews within the minibuffer as you narrow down candidates. By leveraging dirvish.el for its core functionality, it delivers a seamless and consistent preview experience.

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-attributes: like dirvish-attributes, but for side window.
• dirvish-side-mode-line-format: like dirvish-mode-line-format, but for side window.
• dirvish-side-header-line-format: like dirvish-header-line-format, but for side window.
• 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 command (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 enhances Dirvish with the dirvish-subtree-toggle command, a streamlined alternative to dired-subtree for toggling a directory under the cursor as a subtree.

• To visually indicate the expansion state of directories, add subtree-state to dirvish-attributes.
• Customize the appearance of the expansion indicator using dirvish-subtree-state-style and dirvish-subtree-icon-scale-factor to adjust its placement and size. See this related issue
• To hide the indicator when no directories are expanded, set dirvish-subtree-always-show-state to nil.

History navigation (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.