Squashed commit of the following:

commit 720ddad Author: Alex <[email protected]> Date: Sat Oct 1 14:12:50 2022 +0800 feat!(dired): use dirvish by default BREAKING CHANGE: Deprecate `+ranger` flag, use package dirvish by default and rewrite the module based on it. Doing so we can remove these packages and their associated hacks: `all-the-icons-dired`, `dired-rsync`, `fd-dired`, `dired-git-info`, `ranger`. See file log below for details. purcell/diredfl@f9140b2c4215 -> purcell/diredfl@62b559e1d6b6 alexluigit/dirvish@73dcaa404da9 -> alexluigit/dirvish@11a3bec247b9 * modules/ui/vc-gutter/config.el(dired-mode-hook, diff-hl-dired-mode): when dired module is enabled, use `vc-state` from dirvish to render the vc gutter instead of diff-hl-dired-mode, doing so we get better performance and integration with the dired module. * modules/emacs/dired/autoload.el: delete this file since the commands in it are no longer used. * modules/emacs/dired/doctor.el: add deprecate warning for `+ranger` flag * modules/emacs/dired/README.org: rewrite based on the new features * modules/emacs/dired/config.el: - (dirvish-mode-line-format, dired-hide-details-hide-symlink-targets): set `dired-hide-details-hide-symlink-targets` to t, show symlink target on mode-line instead - (dired-listing-switches, +dired-disable-gnu-ls-flags-maybe-h): dirvish has inbuilt gnuls check, so the setup for `dired-listing-switches` can be simplified as such and the `+dired-disable-gnu-ls-flags-maybe-h` can be safely removed. - (+dired/quit-all): dirvish has a fine-tuned machinery for closing dired buffers, so replace this command with `dirvish-quit`. One can set `dirvish-reuse-session` to nil to get similar behavior to `+dired/quit-all`. - (dired-rsync): replace `dired-rsync` with `dirvish-rsync` - (+ranger): deprecate this flag. - (dirvish-attributes, all-the-icons-dired): remove package `all-the-icons-dired`, use `all-the-icons` attribute in dirvish to implement the `+icons` flag. - (fd-dired): use the better alternative dirvish-fd to replace this command/package. - (dirvish-attributes, dired-git-info-mode): use `git-msg` attribute from dirvish to replace dired-git-info-mode. - (dirvish-attributes): add `collapse` attribute for `+dirvish` flag - (dirvish-attributes): add `subtree-state` attribute for `+icons` flag - (dirvish-mode-map): introduce a few new keybindings such as `dirvish-subtree-toggle` - (dirvish-attributes, dirvish-use-header-line, dirvish-mode-line-format, dirvish-hide-cursor, dirvish-hide-details): support classic dired UI when +dirvish is not enabled. Fix: doomemacs#6562 Replace: doomemacs#6568 Ref: https://github.com/alexluigit/dirvish/blob/a877ba816f907daea2d86bd10754bec6484e753a/dirvish-extras.el#L172-L190 Ref: alexluigit/dirvish#34 Ref: https://github.com/alexluigit/dirvish/blob/main/docs/COMPARISON.org#find-dired--fd-dired Ref: https://github.com/alexluigit/dirvish/blob/main/docs/COMPARISON.org#all-the-icons-dired Ref: https://github.com/alexluigit/dirvish/blob/main/docs/COMPARISON.org#dired-git-info--diff-hl--dired-k Ref: https://github.com/alexluigit/dirvish/blob/main/docs/COMPARISON.org#dired-rsync
EthanOQuin · Feb 10, 2023 · bc78c3f · bc78c3f
1 parent 3d2f818
commit bc78c3f
Show file tree

Hide file tree

Showing 6 changed files with 215 additions and 232 deletions.
diff --git a/modules/emacs/dired/README.org b/modules/emacs/dired/README.org
@@ -1,27 +1,34 @@
+← [[doom-module-index:][Back to module index]]              ↖ [[doom-module-history:emacs/dired][History]]  ! [[doom-module-issues:::emacs dired][Issues]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+--------------------------------------------------------------------------------
 #+title:    :emacs dired
 #+subtitle: Making dired pretty [functional]
 #+created:  February 20, 2017
 #+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:diredfl]]
-- [[doom-package:dired-rsync]]
-- [[doom-package:fd-dired]]
-- [[doom-package:ranger]] if [[doom-module:+ranger]]
+- [[doom-package:][dirvish]]
+- [[doom-package:][diredfl]]
 
 ** TODO Hacks
 #+begin_quote
@@ -38,35 +45,133 @@ 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
+| Keybind  | Description                               |
+|----------+-------------------------------------------|
+| [[kbd:][n]]        | Move down a line                          |
+| [[kbd:][p]]        | Move up a line                            |
+| [[kbd:][e]] or [[kbd][RET]] | 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                             |
+| [[kbd:][+]]        | Create a directory                        |
+| ...      | ...                                       |
+
+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]].  If you have enabled ~(evil +everywhere)~, you would get a
+different set of bindings ([[kbd][j/k]] for move down/up a line), consult =evil-collection=
+for the actual bindings.
+
+*** 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?]]
 
 * Frequently asked questions
-/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
+** How to kill all session buffers on quit?
+
+Set ~dirvish-reuse-session~ to nil.
 
 * TODO Appendix
 #+begin_quote

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