# dirvish **Repository Path**: dbv771/dirvish ## Basic Information - **Project Name**: dirvish - **Description**: No description available - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: dev - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-04-03 - **Last Updated**: 2025-04-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README #+AUTHOR: Alex Lu #+EMAIL: alexluigit@gmail.com #+startup: inlineimages content * *Dirvish* [[https://melpa.org/#/dirvish][file:https://melpa.org/packages/dirvish-badge.svg]] [[https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml][file:https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml/badge.svg]] #+begin_quote Wish you a better dired. #+end_quote #+ATTR_ORG: :width 1024 [[./assets/multi-win.png]] Check out this [[https://www.youtube.com][introduction_video_NOT_UPLOADED_YET]]. ** Introduction *Dirvish* is a minimalistic file manager based on *dired*. This package empowers dired by giving it a modern UI in a unintrusive way. Emacs users deserve a file manager better than those popular ones on terminal such as [[https://github.com/ranger/ranger][ranger]], [[https://github.com/vifm/vifm][vifm]], [[https://github.com/gokcehan/lf][lf]] since Emacs is more then a terminal emulator. The name *dirvish* is a tribute to [[https://github.com/justinmk/vim-dirvish][vim-dirvish]]. *** Dependencies | Package | Description | Required | |-------------------+----------------------------------+----------| | =exa= | For directory preview | Yes | | =all-the-icons.el= | Icon support | Optional | | =pdftoppm= | Generate pdf preface image | Optional | | =imagemagick= | Generate image cache | Optional | | =ffmpegthumbnailer= | Generate video thumbnailer | Optional | | =epub-thumbnailer= | Generate epub thumbnailer | Optional | | =zipinfo= | Preview zip files | Optional | | =mediainfo= | Show information for audio files | Optional | *** Installation Dirvish is available from [[https://melpa.org][Melpa]]. **** For =package.el= user You can install it directly via =package-install= if you have melpa in your =package-archives=. **** For =straight.el= user #+begin_src emacs-lisp (straight-use-package 'dirvish) #+end_src Alternatively, install it by using *use-package* and *straight* in tandem. #+begin_src emacs-lisp (use-package dirvish :straight t) #+end_src **** Manual install To install it manually, first clone this repository, #+begin_src bash git clone https://github.com/alexluigit/dirvish #+end_src then add =path/to/dirvish= to your =load-path=. #+begin_src emacs-lisp (add-to-list 'load-path "/path/to/dirvish") (require 'dirvish) #+end_src *** Quickstart After installation, just =M-x= and run =dirvish=. **** "Dirvish-ish" dired Usually =dirvish= takes up the whole frame, but sometimes we prefer managing files inside current window, just like how dired does it. To open a single window dirvish, you can either: - Run it once :: #+begin_src emacs-lisp (dirvish-dired) #+end_src - Override dired entry commands (=dired/dired-jump/dired-jump-other-window/...=) globally :: #+begin_src emacs-lisp (dirvish-override-dired-mode) #+end_src A glimpse of single-window dirvish: [[./assets/dirvish-one-win.png]] **** Dired config Since =dirvish-mode= is just a =major-mode= derived from =dired-mode=, it respects all of your dired config (including keymapping) in principle. As an example, here is an excerpt from my personal dired config: #+begin_src emacs-lisp (setq dired-clean-confirm-killing-deleted-buffers nil) (setq dired-recursive-deletes 'always) (setq delete-by-moving-to-trash t) (setq dired-dwim-target t) (setq dired-listing-switches "-AGhlv --group-directories-first --time-style=long-iso") #+end_src /NOTICE/: You may come across issues relating to buffer killing/reverting mechanism inside of dirvish since this part is still very much WIP (hence related dired config won't work). If you found any inconsistency behaviours between dired and dirvish under same dired config, please report an [[https://github.com/alexluigit/dirvish/issues][issue]]. ** Features *** File preview =dirvish= command places a preview window at right side of frame to show the content of selected file. To toggle it, use =dired-hide-details-mode=, or set =dirvish-enable-preview= to nil. Some additional notes on this: - Native GIF support :: - *Image cache* :: A image cache file, with small filesize that is unlikely to block Emacs when being rendered, is generated when the original image file is larger than 500KB. - Highly customizable :: A preview buffer is created either by an elisp function or by the help of a shell command. If you don't like the way dirvish creates the preview buffer for certain file types, take a look at =dirvish-preview-cmd-alist=. This variable determines how a preview buffer get generated for different file types, customize it to suit your need. *** Multiple instances You can open multiple dirvish instance across diffent widnows / tabs / frames. Each one of them has their own parent/preview buffer list that are being killed during deactivation of this instance. *WIP*: Although every dirvish instance is independent from each other, you can mark files across multiple instance, and paste/move marked files to current one with one keystroke (=dirvish-yank=). *** Drop-in replacement commands *Dired* is superb, but from a modern file manager's (like *ranger*, *lf*) perspective, , some Dired commands are quite unintuitive. Dirvish provides a few drop-in replacement commands for those not-so-modern dired commands, such as =dirvish-sort-by-criteria= is a more user friendly version of =dired-sort-toggle-or-edit=. *** Asynchronous I/O To prevent emacs from getting freezes, dirvish uses external process to deal with heavy I/O task, such as file copy/move, directory preview, or image cache generation etc. *** Bulit-in icon support You don't need [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]] anymore since dirvish have built-in icon support. This native icon solution has several advantages over *dired + all-the-icons-dired*, those are: **** Better integration with line highlighting If you want to highlight current (cursor) line in dired, normally you enable =hl-line-mode= or add it to =dired-mode-hook=, but it doesn't play very well with =all-the-icons-dired-mode= due to conflict overlays. Dirvish handles line highlighting and icon rendering on its own. + hl-line-mode + all-the-icons-dired-mode :: [[./assets/ranger-line.png]] + dirvish :: [[./assets/dirvish-line.png]] **** Lazy rendering Dirvish doesn't render icons for all the files in a directory eagerly, instead it only render icons that are displayed within the viewport. Visiting =/usr/bin= (or any directory with over 1000 files) will no longer freeze your Emacs. *** Minibuffer file preview (extension) *dirvish-minibuffer-preview.el* is an extension for dirvish, it provides =dirvish-minibuf-preview-mode=, which is a feature to preview file when narrowing file/directory candidates using minibuffer. - Why does this feature exist? :: *Dirvish* and *minibuffer* seem unrelated at first glance. But when it comes to display a file preview, they actually share the same mechanism, that is: /get file path under the cursor and update preview window accordingly./ Displaying minibuffer file preview in a "dirvish" way, not only a lot of source code can be reused, but also related user configurations. In other words, you don't have to configure file preview for dirvish and for minibuffer separately, they will always /display the same thing./ For *selectrum* or *vertico* users (only support these 2 completion UIs for now), if you'd like to give this extension a try, all you need is: #+begin_src emacs-lisp (require 'dirvish-minibuffer-preview) (dirvish-minibuf-preview-mode) #+end_src ** Configuration *** Options | Option | Type | Description | default | |---------------------------------+----------+-----------------------------------------+---------------------| | =dirvish-cache-dir= | String | Cache directory | "~/.cache/dirvish" | | =dirvish-trash-dir-alist= | Alist | Setup multiple trash cans. | nil | | =dirvish-history-length= | Integer | The length of history ring | 30 | | =dirvish-enable-preview= | Boolean | Enable file preview | t | | =dirvish-depth= | Integer | Level of dirs to traverse up | 1 | | =dirvish-parent-max-width= | Float | Max width of parent windows | 0.12 | | =dirvish-parent-face-remap-alist= | Alist | See: M-x =describe-variable= | | | =dirvish-preview-width= | Float | Width of preview window | 0.65 | | =dirvish-body-fontsize-increment= | Float | Increase fontsize in dirvish body | 0.1 | | =dirvish-footer-format= | String | See: M-x =describe-variable= | | | =dirvish-header-style= | Option | Style for full-frame dirvish header | large | | =dirvish-header-text-fn= | Function | A function for composing header text | dirvish-header-text | | =dirvish-header-face-remap-alist= | Alist | See: M-x =describe-variable= | | | =dirvish-show-icons= | Boolean | Show icons | t | | =dirvish-icon-delimiter= | String | The delimiter between icon and filename | "\t" | | =dirvish-icon-monochrome= | Boolean | Whether icon inherit =face-at-point= | t | | =dirvish-icon-v-offset= | Float | Icon's vertical offset | 0.01 | | =dirvish-preview-cmd-alist= | Alist | See: M-x =describe-variable= | | *** Hooks | Hook | Description | |----------------------------+-----------------------------------------| | =dirvish-mode-hook= | Hook for parent buffer initialization. | | =dirvish-preview-setup-hook= | Hook for preview buffer initialization. | ** Similar projects *** Ranger.el Although these 2 packages have something in common, unlike *ranger.el*, which tries to become an all-around emulation of ranger, *dirvish* is more bare-bone, meaning it does *NOT* try to port all "goodness" from ranger. Instead, it only aims to: - Provides a better dired UI - Integrates all sensible dired commands ** Issues - Bugs are expected on Windows since dirvish has not been tested on it. - It might have conflicts with packages that controls window placement. - *WIP*: there are still some issues relating to buffer (auto)reverting. - *WIP*: marks does not display correctly when revisit the same dirvish buffer. Feel free to report issues. ** Acknowledgements This package is inspired a lot by [[https://github.com/ralesi/ranger.el][ranger.el]], thanks @ralesi for creating and maintaining it. ** Copying This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.