dirvish: a Vim directory browser that is only a list of paths

Each line is just a filepath

The design of vim-dirvish is best understood as a refusal to build a file browser. A Dirvish buffer contains only filepaths, hidden by conceal, so the text you see is a decoration and the text you operate on is a path. Everything you can do with a Vim buffer you can do with a Dirvish buffer. You use plain old y to yank a path and then feed it to :r or :e or whatever. You sort with :sort, filter with :global, and hit R to reload. You append to quickfix with :'<,'>caddb and iterate with :cdo. You script with :Shdo[!], which generates a shell script. And you can turn any buffer into a Dirvish buffer by setting ft=dirvish, which the documentation shows as a pipeline of file names into Vim:

git ls-files | vim +'setf dirvish' -

That last example is the clearest statement of the philosophy. A listing is not a special object that the plugin owns and interprets, it is a buffer whose filetype tells the plugin how to behave, and the content can come from anywhere, including the output of another command. The plugin is described as a path navigator designed to work with Vim's built-in mechanisms and complementary to vim-eunuch and vim-unimpaired, and the feature list calls it simple, flexible, safe, non-intrusive, fast, intuitive, powerful and reliable, with each of those words backed by a specific mechanism. The plugin calls itself safe because it never modifies the filesystem, which is a real property rather than a promise, since there is no code path that can delete anything.

The buffer name is the directory, so @% means what you expect

The second concept is that the buffer name is the directory name, so commands and plugins that work with @% and @# do the right thing. In Vim, @% is the current file name and @# is the alternate file, so naming the buffer after the directory makes those expansions meaningful in a directory context. The documentation shows the pattern for creating things relative to the directory you are browsing:

:!mkdir %foo

for a directory, and :e %foo.txt for a file, both of which expand to a path inside the directory in the buffer name. The same idea supports the :Shdo workflow, where a script buffer can refer back to the Dirvish buffer it came from, and the documentation shows the sequence of :Shdo, mkdir with the alternate file expanded, and Z! to run the script. That is a small design decision with a large convenience payoff, because it means the usual Vim idioms for referring to the current path keep working in a listing, and it means the alternate buffer trick composes with the script generation rather than fighting it.

Editing the buffer is the intended workflow, not a hack

The third concept is that Dirvish buffers are meant to be edited for any purpose, and the documentation is explicit that it is safe and reversible. You can use :sort or :global to rearrange the view, delete lines with d, and then run :%Shdo on the result. You can pipe the visual selection to a shell command to see inline results, for example:

:'<,'>!xargs du -hs

which runs du over the selected files and prints the output in place. You type u to undo, or R to reload. The safety claim rests on the combination of two facts: the buffer holds text, so editing it is ordinary editing, and the plugin does not act on the filesystem, so a misfired d deletes a line of text and not a file. This is a genuinely different relationship between the user and the filesystem from the one netrw offers, where the listing is a widget with its own commands and its own keymaps. The trade-off is the one implied by the whole design, which is that anything you want done to those files has to go through a command you type, not through a keypress in a browser.

The arglist, visual selection and file manipulation plugins

The fourth concept involves the :args list, described as an ad-hoc list of filepaths. Typing x adds files to the window-local arglist, and from there you can iterate with standard commands like :argdo, or with plugin features like ]a from vim-unimpaired. Running :Shdo! with a mapping of [count]. generates a shell script from the arglist, which is how a directory operation becomes something you can inspect before it runs. Visual selection is listed among the features for the same reason: intuitive selection opens multiple files, so a visual selection is a way of building a batch. The extension list shows how much of the surface area is deliberately left to other plugins. There is remote-viewer for browsing ssh:// and other remote paths, dirvish-git.nvim and vim-dirvish-git to show the git status of each file, vim-dirvinist to list files defined by projections, dirvish-do.nvim to add file manipulation keybindings, and vim-dirvish-dovish to add vim-style file manipulation commands. The naming of those last two is a good summary of the whole approach. Dirvish ships the listing, and the plugins that give it teeth are separate projects with their own maintainers.

A rewrite of filebeagle, with a licence to read

The project has a history worth knowing. Dirvish was originally forked, and completely rewritten, from filebeagle by Jeet Sukumaran, and the copyright line reads 2015 Justin M. Keyes. The rewriting is why the plugin has a coherent idea of what it is. The licence is the part to check yourself. GitHub classifies this repository's licence as a custom one it cannot categorise, and the LICENSE file is in the repository root, so the terms are whatever that file says rather than a standard grant you can assume. The feature list makes performance claims, describing the plugin as 2x faster than netrw and as 96% smaller than netrw, with less code and fewer bugs as the stated reason. Those are the project's own numbers, published without a reproducible benchmark in the tree, and a reader should treat them as a claim about the author's own comparison rather than a measurement. The version history is thin, with a single release tag of v1.0 from 2023-06-28 and a last push on 2026-07-05, which fits a plugin whose scope is small and stable rather than one that is churning.

Where dirvish is the wrong tool

The clearest case is a person who wants a file manager. Dirvish never modifies the filesystem, and while the extension ecosystem fills in some of that with file manipulation plugins, the core plugin offers no rename, no move, no delete and no create beyond the :!mkdir example that runs a shell command. If your workflow is to browse and then act on files with a few keystrokes, a graphical or netrw-style browser with those commands built in is the more direct tool, and dirvish is a worse substitute. The second case is a remote or graphical environment where netrw's own features are good enough, since swapping plugins for speed is only worth it if you feel the slowness. The third is a Neovim user expecting a modern plugin architecture, because the plugin is Vim script with the classic autoload/, plugin/, ftplugin/ and syntax/ directory layout, which means it works in both Vim and Neovim but does not come with the API surface a Neovim-first plugin would have. The last point to check before installing is the version floor, since the project states it supports Vim 7.2 and up, and there is no mention of a Neovim-only path or of the modern plugin formats.

Editorial conclusion

Adopt dirvish if you navigate files from inside Vim and want a listing you can sort, filter, pipe and script without leaving the editor, especially alongside vim-unimpaired and vim-eunuch. Do not adopt it as a file manager, because the plugin never modifies the filesystem and provides no rename, move or delete, and do not expect the speed and size claims in its feature list to be a benchmark you can reproduce from the repository. Before you install it, read the LICENSE file yourself, since GitHub classifies the licence as one it cannot categorise, and check that your Vim is 7.2 or newer, which is the version the project states it supports.

Frequently asked questions

Official sources

1. Issues
2. justinmk/vim-dirvish on GitHub
3. README
4. Releases