BREAKING: rewrite the dired module based on dirvish

- Deprecate `+ranger` flag, use dirvish by default See: alexluigit/dirvish#34 - Bump the package version for diredfl and dirvish - Reimplement `+icons`, deprecate package all-the-icons-dired all-the-icons-dired is very slow on large directories, while dirvish render icons lazily. - Use `vc-state` from dirvish, remove diff-hl-dired-mode 1. diff-hl-dired-mode doesn't index the entries in subtrees. 2. It freezes Emacs on big repos, while dirvish does this asynchronously in external process and update the UI in an nonblocking fashion. - Use `git-msg` from dirvish, deprecate package dired-git-info Same reasons as in diff-hl-dired-mode. - Use utilities in dirvish-yank.el, deprecate package dired-rsync `dirvish-yank` has inbuilt support for rsync. - Use dirvish-fd, deprecate package fd-dired `dirvish-fd` is way powerful. - Remove the gnuls check on remote hosts dirvish checks gnu ls availability for each remote host. - Set `dired-hide-details-hide-symlink-targets` to t (default) We have symlink target showing on the modeline - Add a few sensible keybindings
alexluigit · Sep 16, 2022 · b3719e2 · b3719e2
1 parent 0172b18
commit b3719e2
Show file tree

Hide file tree

Showing 6 changed files with 202 additions and 230 deletions.
diff --git a/modules/emacs/dired/README.org b/modules/emacs/dired/README.org
@@ -4,24 +4,29 @@
 #+since:    2.0.0
 
 * Description :unfold:
-This module provides reasonable defaults and augmentations for dired.
+This module provides reasonable defaults and augmentations for [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Dired.html][Dired]], the
+inbuilt file manager for Emacs.  The extra features are mostly introduced by the
+Dired enhancement package [[https://github.com/alexluigit/dirvish][Dirvish]].
 
 ** Maintainers
-/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
+- [[doom-user:][@alexluigit]]
+
+[[doom-contrib-maintainer:][Become a maintainer?]]
 
 ** Module flags
 - +icons ::
   Enables the display of fancy icons depending on file types in dired buffers.
-- +ranger ::
-  Enables dired to be more like [[https://github.com/ranger/ranger][ranger]].
+- +dirvish ::
+  Apply some stylistic defaults to the Dired buffer.
+  + Show file size at right fringe
+  + Collapse directories with only one entry in it automatically.
+  + Use prettified header line and mode line
+  + Hide file details information by default
+  + Enable line highlighting, hide the cursor
 
 ** Packages
-- [[doom-package:][all-the-icons-dired]] if [[doom-module:][+icons]]
-- [[doom-package:][diff-hl]]
+- [[doom-package:][dirvish]]
 - [[doom-package:][diredfl]]
-- [[doom-package:][dired-rsync]]
-- [[doom-package:][fd-dired]]
-- [[doom-package:][ranger]] if [[doom-module:][+ranger]]
 
 ** TODO Hacks
 #+begin_quote
@@ -38,29 +43,125 @@ This module provides reasonable defaults and augmentations for dired.
 This module has no requirements *except on BSDs* like MacOS or FreeBSD, where
 =GNU ls= (aka ~gls~) is required.
 
-* TODO Usage
-#+begin_quote
- 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
-#+end_quote
-
-| Keybind | Description                |
-|---------+----------------------------|
-| [[kbd:][SPC f d]] | Find directory with dired  |
-| [[kbd:][q]]       | Exit dired buffer          |
-| [[kbd:][C-c C-r]] | Run [[doom-package:][dired-rsync]]            |
-| [[kbd:][C-c C-e]] | Rename entries with [[doom-package:][wdired]] |
-
-Other keybindings can be found on the official [[https://www.gnu.org/software/emacs/refcards/pdf/dired-ref.pdf][Dired reference card]].
-
-** Ranger
-If [[doom-module:][+ranger]] is enabled often a buffer will be opened in minimal ranger mode
-(~deer-mode~). In this case [[kbd:][z P]] can be used to toggle between full ranger and
-~deer-mode~.
-
-* TODO Configuration
-#+begin_quote
- 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
-#+end_quote
+Optionally, install these dependencies to improve the preview experience:
+
++ =imagemagick= for image preview
++ =poppler= | =pdf-tools= for pdf preview
++ =ffmpegthumbnailer= for video preview
++ =mediainfo= for audio/video metadata generation
++ =tar= and =unzip= for archive files preview
+
+** macOS
+#+begin_src bash
+  brew install coreutils fd poppler ffmpegthumbnailer mediainfo imagemagick
+#+end_src
+
+** Debian-based
+#+begin_src bash
+  apt install fd-find poppler-utils ffmpegthumbnailer mediainfo imagemagick tar unzip
+#+end_src
+
+** Arch-based
+#+begin_src bash
+  pacman -S fd poppler ffmpegthumbnailer mediainfo imagemagick tar unzip
+#+end_src
+
+** FreeBSD
+#+begin_src bash
+  pkg install gnuls fd-find poppler ffmpegthumbnailer ImageMagick7 gtar
+#+end_src
+
+** Windows (not tested, may not work)
+#+begin_src bash
+  # install via Scoop: https://scoop.sh/
+  scoop install coreutils fd poppler imagemagick unzip
+#+end_src
+
+* Usage
+** Global bindings
+You can access Dired/Dirvish by opening a directory entry in commands like
+~find-file (SPC f f)~. Or you can create a Dired buffer directly with these
+keybindings.
+
+| Keybind                      | Description                        |
+|------------------------------+------------------------------------|
+| [[kbd:][SPC f d]]                      | Find directory with dired          |
+| [[kbd:][SPC o -]]                      | Jump to current directory in dired |
+
+These commands are available but not bound to any keys.
+
+| Command          | Description                    |
+|------------------+--------------------------------|
+| [[kbd:][M-x dirvish]]      | Open dired with preview        |
+| [[kbd:][M-x dirvish-dwim]] | Dirvish with smart layout      |
+| [[kbd:][M-x dirvish-fd]]   | Search files in dired using fd |
+| [[kbd:][M-x dirvish-side]] | Open project sidebar           |
+
+** Dired bindings
+*** Basics
+Note that these are Emacs bindings, if you have enabled ~(evil
++everywhere)~, you should consult =evil-collection= for the actual bindings.
+
+| Keybind | Description                               |
+|---------+-------------------------------------------|
+| [[kbd:][n]]       | Move down a line                          |
+| [[kbd:][p]]       | Move up a line                            |
+| [[kbd:][e]]       | Visit the file or directory on this line  |
+| [[kbd:][(]]       | Toggle visibility of detailed information |
+| [[kbd:][q]]       | Exit dired buffer                         |
+| [[kbd:][^]]       | Go Up a directory                         |
+| [[kbd:][m]]       | Mark a file                               |
+| [[kbd:][u]]       | Unmark a file                             |
+| [[kbd:][D]]       | Delete a file                             |
+| ...     | ...                                       |
+
+This is only a very small sample of dired keybindings, just for you to get a
+sense of Dired.  Other basic keybindings can be found on the official [[https://www.gnu.org/software/emacs/refcards/pdf/dired-ref.pdf][Dired
+reference card]].
+
+*** Extras
+You don't have to memorize all of Dired bindings because this module provided a
+lot of easy-to-read menus such as ~dirvish-mark-menu~ (powered by =transient.el=)
+for you to find the suitable command in a specific context.  All of these
+(sub-)menus are included in ~dirvish-dispatch (?)~, the main help menu.  Some
+extremely useful ones are bound to a separate keys as well.
+
+| Keybind | Description                                   |
+|---------+-----------------------------------------------|
+| [[kbd:][?]]       | Ask for help                                  |
+| [[kbd:][a]]       | Quick access frequently used directories      |
+| [[kbd:][f]]       | Get file information under the cursor         |
+| [[kbd:][y]]       | Paste/link/move marked files here             |
+| [[kbd:][s]]       | Sort buffer with different criteria           |
+| [[kbd:][M-m]]     | Commands relate to marking and actions        |
+| [[kbd:][M-s]]     | Setup user interface for dirvish              |
+| [[kbd:][M-e]]     | "Emerge" important files at the top           |
+
+Other bindings in this module:
+
+| [[kbd:][TAB]]     | Expand or contract directory under the cursor |
+| [[kbd:][M-f]]     | Jump to next dired history entry              |
+| [[kbd:][M-b]]     | Jump to previous dired history entry          |
+| [[kbd:][M-n]]     | Narrow the buffer with user input             |
+| [[kbd:][M-t]]     | Toggle fullscreen (preview)                   |
+| [[kbd:][C-c C-e]] | Rename entries with [[doom-package:][wdired]]                    |
+
+* Configuration
+** Quick access entries
+
+Use the following syntax to configure the entries displayed in
+~dirvish-quick-access~ command.
+
+#+begin_src emacs-lisp
+  ;; in $DOOMDIR/config.el
+  (setq! dirvish-quick-access-entries
+         `(("h" "~/"                          "Home")
+           ("e" ,user-emacs-directory         "Emacs user directory")
+           ("c" "~/Code/"                     "Code")
+           ("d" "~/Downloads/"                "Downloads")
+           ("m" "/mnt/"                       "Mounted drives")
+           ("t" "~/.local/share/Trash/files/" "Trash")))
+#+end_src
 
 * Troubleshooting
 /There are no known problems with this module./ [[doom-report:][Report one?]]

diff --git a/modules/emacs/dired/autoload.el b/modules/emacs/dired/autoload.el