branch: elpa/dirvish
commit ea4d1ed66b1f7d4b59c8e4e4c13495208ee09f95
Author: Alex Lu <hellosimon1...@hotmail.com>
Commit: Alex Lu <hellosimon1...@hotmail.com>
refactor: move `dirvish-dispatch` to extras and update docs
The `dirvish-renaming-menu` is also autoloaded now. (closes #299)
---
README.org | 37 ++++++-----
dirvish-extras.el | 34 ++++++++++
dirvish-widgets.el | 3 +-
dirvish.el | 32 +--------
docs/CUSTOMIZING.org | 129 ++++++++++++-------------------------
docs/FAQ.org | 52 +++++++++++++++
extensions/dirvish-emerge.el | 1 +
extensions/dirvish-fd.el | 1 +
extensions/dirvish-history.el | 1 +
extensions/dirvish-ls.el | 1 +
extensions/dirvish-quick-access.el | 1 +
extensions/dirvish-subtree.el | 1 +
extensions/dirvish-vc.el | 1 +
extensions/dirvish-yank.el | 1 +
14 files changed, 158 insertions(+), 137 deletions(-)
diff --git a/README.org b/README.org
index 6a98c8e4a0..a305443fa1 100644
--- a/README.org
+++ b/README.org
@@ -76,24 +76,15 @@ You might also want to install
[[https://gitlab.com/movie_thumbnailer/mtn][mtn]]
* Installation
-Dirvish is available on [[https://melpa.org/#/dirvish][Melpa]]. Just type
=M-x package-install RET dirvish RET=
-into Emacs 27.1+. =el-get= users can get the recipe from
[[https://github.com/alexluigit/dirvish/issues/90][here]].
-
-For straight.el users, it is simply:
-#+begin_src emacs-lisp
- (straight-use-package 'dirvish)
-#+end_src
+Dirvish is available from
[[https://elpa.nongnu.org/nongnu/dirvish.html][Nongnu-Elpa]] and
[[https://melpa.org/#/dirvish][Melpa]]. You can install it directly
+via =M-x package-install RET dirvish RET= on Emacs 28.1+. After installation,
+activate Dirvish globally with =M-x dirvish-override-dired-mode RET=.
* Quickstart
-After installation, let Dirvish take over Dired globally:
-#+begin_src emacs-lisp
-(dirvish-override-dired-mode)
-#+end_src
-
+ =M-x dirvish RET=
- Welcome to Dirvish! Press =?= for help.
+ Welcome to Dirvish! Use your favorite dired commands here!
+ =M-x dired= | =dired-jump= | ... =RET=
@@ -103,13 +94,28 @@ After installation, let Dirvish take over Dired globally:
If the selected window is the only window, open Dirvish, otherwise open
Dired.
-* Resources
++ =M-x dirvish-dispatch RET=
+
+ This is a help/cheatsheet menu powered by ~transient.el~, the same library
used
+ to implement keyboard-driven menus in Magit and many Dirvish extensions. If
+ you prefer this interaction style, consider binding these menus to
+ ~dirvish-mode-map~. See [[file:docs/CUSTOMIZING.org][example config]] for
details.
+
+* Documentation
+
+For more dirvish customization options and features, see our documentation:
+ [[file:docs/CUSTOMIZING.org][Customizing]]
+ [[file:docs/EXTENSIONS.org][Extensions]]
++ [[file:docs/FAQ.org][FAQ]]
++ [[file:docs/EMACS-NEWCOMERS.org][Absolute beginner's guide]]
+
+* Resources
+
+To delve deeper into Dirvish, explore these resources:
+
+ [[file:docs/COMPARISON.org][Related projects]]
+ [[file:docs/CHANGELOG.org][Changelog]]
-+ [[file:docs/EMACS-NEWCOMERS.org][Absolute beginner's guide]]
+ [[https://github.com/alexluigit/dirvish/discussions][Discussions]]
* Acknowledgements
@@ -138,6 +144,7 @@ Thanks Fox Kiester (@noctuid) for the awesome
[[https://github.com/alexluigit/di
The name *dirvish* is a tribute to
[[https://github.com/justinmk/vim-dirvish][vim-dirvish]].
-----
+[[https://elpa.nongnu.org/nongnu/dirvish.html][file:https://elpa.nongnu.org/nongnu/dirvish.svg]]
[[https://melpa.org/#/dirvish][file:https://melpa.org/packages/dirvish-badge.svg]]
[[https://stable.melpa.org/#/dirvish][file:https://stable.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]]
diff --git a/dirvish-extras.el b/dirvish-extras.el
index 4d167bbbd2..f4e1c8aa6a 100644
--- a/dirvish-extras.el
+++ b/dirvish-extras.el
@@ -29,10 +29,13 @@
;; - `dirvish-mark-menu'
;; - `dirvish-epa-dired-menu'
;; - `dirvish-setup-menu'
+;; - `dirvish-dired-cheatsheet'
+;; - `dirvish-dispatch'
;;; Code:
(require 'dirvish)
+(require 'transient)
(declare-function tramp-file-name-user "tramp")
(declare-function tramp-file-name-host "tramp")
@@ -370,6 +373,7 @@ current layout defined in `dirvish-layout-recipes'."
(require 'dired-aux)
(transient-setup 'dirvish-mark-menu))
+;;;###autoload (autoload 'dirvish-renaming-menu "dirvish-extras" nil t)
(transient-define-prefix dirvish-renaming-menu ()
"Help Menu for file renaming in Dired."
[:description
@@ -415,5 +419,35 @@ current layout defined in `dirvish-layout-recipes'."
(":" " GnuPG helpers" dirvish-epa-dired-menu)
("h" " More info about Dired" describe-mode)])
+;;;###autoload (autoload 'dirvish-dispatch "dirvish-extras" nil t)
+(transient-define-prefix dirvish-dispatch ()
+ "Main menu for Dired/Dirvish."
+ [:description
+ (lambda () (dirvish--format-menu-heading
+ "Dirvish main menu"
+ "NOTICE: these commands require relevant Dirvish extensions"))
+ "" "Actions & Essential commands"
+ ("u" "User interface setup" dirvish-setup-menu)
+ ("c" "Dired cheatsheet" dirvish-dired-cheatsheet)
+ ("/" "Perform fd search" dirvish-fd)
+ ("@" "Find all dirs by fd" dirvish-fd-jump)
+ ("R" "Rsync marked files" dirvish-rsync)
+ ("n" "Live narrowing" dirvish-narrow)
+ "Transient commands"
+ ("a" "Quick access" dirvish-quick-access)
+ ("h" "Go to history entries" dirvish-history-menu)
+ ("s" "Sort current buffer" dirvish-quicksort)
+ ("l" "Setup listing switches" dirvish-ls-switches-menu)
+ ("f" "Setup fd-find switches" dirvish-fd-switches-menu
+ :if (lambda () (dirvish-prop :fd-arglist)))
+ ("S" "Setup rsync switches" dirvish-rsync-switches-menu)
+ ("m" "Manage marks" dirvish-mark-menu)
+ ("e" "Manage emerged groups" dirvish-emerge-menu)
+ ("t" "Manage subtrees" dirvish-subtree-menu)
+ ("r" "Rename files" dirvish-renaming-menu)
+ ("v" "Version control system" dirvish-vc-menu)
+ ("y" "Yank marked files" dirvish-yank-menu)
+ ("i" "Get file information" dirvish-file-info-menu)])
+
(provide 'dirvish-extras)
;;; dirvish-extras.el ends here
diff --git a/dirvish-widgets.el b/dirvish-widgets.el
index 6ffcc7e53d..b6cc564424 100644
--- a/dirvish-widgets.el
+++ b/dirvish-widgets.el
@@ -436,8 +436,7 @@ GROUP-TITLES is a list of group titles."
(win (dv-preview-window dv))
((window-live-p win))
(width (window-width win))
- (files (hash-table-keys dirvish--attrs-hash))
- ((< (length files)
+ ((< (hash-table-count dirvish--attrs-hash)
(or (car dirvish-media-auto-cache-threshold) 0))))
(cl-loop
with fns = '(dirvish-image-dp dirvish-video-dp dirvish-epub-dp)
diff --git a/dirvish.el b/dirvish.el
index 668db755c2..c7a9e83db2 100644
--- a/dirvish.el
+++ b/dirvish.el
@@ -22,7 +22,7 @@
;;; Code:
(require 'dired)
-(require 'transient)
+(require 'cl-lib)
(eval-when-compile (require 'project))
(declare-function ansi-color-apply-on-region "ansi-color")
(declare-function dirvish-fd-find "dirvish-fd")
@@ -269,7 +269,6 @@ input for `dirvish-redisplay-debounce' seconds."
(defvar dirvish-mode-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map dired-mode-map)
- (define-key map (kbd "?") 'dirvish-dispatch)
(define-key map (kbd "q") 'dirvish-quit) map)
"Keymap used in dirvish buffers.")
(defvar dirvish-redisplay-debounce-timer nil)
@@ -1402,34 +1401,5 @@ If `one-window-p' returns nil, open PATH using regular
Dired."
path (if (dirvish-curr) (dv-curr-layout (dirvish-curr))
(and (one-window-p) dirvish-default-layout))))
-(transient-define-prefix dirvish-dispatch ()
- "Main menu for Dired/Dirvish."
- [:description
- (lambda () (dirvish--format-menu-heading
- "Dirvish main menu"
- "NOTICE: these commands require relevant Dirvish extensions"))
- "" "Actions & Essential commands"
- ("u" "User interface setup" dirvish-setup-menu)
- ("c" "Dired cheatsheet" dirvish-dired-cheatsheet)
- ("/" "Perform fd search" dirvish-fd)
- ("@" "Find all dirs by fd" dirvish-fd-jump)
- ("R" "Rsync marked files" dirvish-rsync)
- ("n" "Live narrowing" dirvish-narrow)
- "Transient commands"
- ("a" "Quick access" dirvish-quick-access)
- ("h" "Go to history entries" dirvish-history-menu)
- ("s" "Sort current buffer" dirvish-quicksort)
- ("l" "Setup listing switches" dirvish-ls-switches-menu)
- ("f" "Setup fd-find switches" dirvish-fd-switches-menu
- :if (lambda () (dirvish-prop :fd-arglist)))
- ("S" "Setup rsync switches" dirvish-rsync-switches-menu)
- ("m" "Manage marks" dirvish-mark-menu)
- ("e" "Manage emerged groups" dirvish-emerge-menu)
- ("t" "Manage subtrees" dirvish-subtree-menu)
- ("r" "Rename files" dirvish-renaming-menu)
- ("v" "Version control system" dirvish-vc-menu)
- ("y" "Yank marked files" dirvish-yank-menu)
- ("i" "Get file information" dirvish-file-info-menu)])
-
(provide 'dirvish)
;;; dirvish.el ends here
diff --git a/docs/CUSTOMIZING.org b/docs/CUSTOMIZING.org
index 8bd630a7de..e954349558 100644
--- a/docs/CUSTOMIZING.org
+++ b/docs/CUSTOMIZING.org
@@ -282,45 +282,46 @@ you don't have to require them explicitly if you
installed dirvish from MELPA or
=/path/to/dirvish/extensions/= is in your ~load-path~).
#+begin_src emacs-lisp
- (use-package dirvish
- :init
- (dirvish-override-dired-mode)
- :custom
- (dirvish-quick-access-entries ; It's a custom option, `setq' won't work
- '(("h" "~/" "Home")
- ("d" "~/Downloads/" "Downloads")
- ("m" "/mnt/" "Drives")
- ("t" "~/.local/share/Trash/files/" "TrashCan")))
- :config
- ;; (dirvish-peek-mode) ; Preview files in minibuffer
- ;; (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode'
- (setq dirvish-mode-line-format
- '(:left (sort symlink) :right (omit yank index)))
- (setq dirvish-attributes
- '(nerd-icons file-time file-size collapse subtree-state vc-state
git-msg))
- (setq delete-by-moving-to-trash t)
- (setq dired-listing-switches
- "-l --almost-all --human-readable --group-directories-first
--no-group")
- :bind ; Bind `dirvish-fd|dirvish-side|dirvish-dwim' as you see fit
- (("C-c f" . dirvish)
- :map dirvish-mode-map ; Dirvish inherits `dired-mode-map'
- ("a" . dirvish-quick-access)
- ("f" . dirvish-file-info-menu)
- ("y" . dirvish-yank-menu)
- ("N" . dirvish-narrow)
- ("^" . dirvish-history-last)
- ("h" . dirvish-history-jump) ; remapped `describe-mode'
- ("s" . dirvish-quicksort) ; remapped `dired-sort-toggle-or-edit'
- ("v" . dirvish-vc-menu) ; remapped `dired-view-file'
- ("TAB" . dirvish-subtree-toggle)
- ("M-f" . dirvish-history-go-forward)
- ("M-b" . dirvish-history-go-backward)
- ("M-l" . dirvish-ls-switches-menu)
- ("M-m" . dirvish-mark-menu)
- ("M-t" . dirvish-layout-toggle)
- ("M-s" . dirvish-setup-menu)
- ("M-e" . dirvish-emerge-menu)
- ("M-j" . dirvish-fd-jump)))
+(use-package dirvish
+ :init
+ (dirvish-override-dired-mode)
+ :custom
+ (dirvish-quick-access-entries ; It's a custom option, `setq' won't work
+ '(("h" "~/" "Home")
+ ("d" "~/Downloads/" "Downloads")
+ ("m" "/mnt/" "Drives")
+ ("t" "~/.local/share/Trash/files/" "TrashCan")))
+ :config
+ ;; (dirvish-peek-mode) ; Preview files in minibuffer
+ ;; (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode'
+ (setq dirvish-mode-line-format
+ '(:left (sort symlink) :right (omit yank index)))
+ (setq dirvish-attributes
+ '(nerd-icons file-time file-size collapse subtree-state vc-state
git-msg))
+ (setq delete-by-moving-to-trash t)
+ (setq dired-listing-switches
+ "-l --almost-all --human-readable --group-directories-first
--no-group")
+ :bind ; Bind `dirvish-fd|dirvish-side|dirvish-dwim' as you see fit
+ (("C-c f" . dirvish)
+ :map dirvish-mode-map ; Dirvish inherits `dired-mode-map'
+ ("?" . dirvish-dispatch) ; contains most of sub-menus in dirvish
extensions
+ ("a" . dirvish-quick-access)
+ ("f" . dirvish-file-info-menu)
+ ("y" . dirvish-yank-menu)
+ ("N" . dirvish-narrow)
+ ("^" . dirvish-history-last)
+ ("h" . dirvish-history-jump) ; remapped `describe-mode'
+ ("s" . dirvish-quicksort) ; remapped `dired-sort-toggle-or-edit'
+ ("v" . dirvish-vc-menu) ; remapped `dired-view-file'
+ ("TAB" . dirvish-subtree-toggle)
+ ("M-f" . dirvish-history-go-forward)
+ ("M-b" . dirvish-history-go-backward)
+ ("M-l" . dirvish-ls-switches-menu)
+ ("M-m" . dirvish-mark-menu)
+ ("M-t" . dirvish-layout-toggle)
+ ("M-s" . dirvish-setup-menu)
+ ("M-e" . dirvish-emerge-menu)
+ ("M-j" . dirvish-fd-jump)))
#+end_src
** Mouse settings
@@ -401,53 +402,3 @@ These packages are only listed here for discoverability.
** Working with Doom Emacs (WIP)
A [[https://github.com/doomemacs/doomemacs/pull/6760][PR]] to make dirvish as
the default file manager in doom-emacs is under review.
-
-* FAQ
-** =listing directory failed but ‘access-file’ worked= error on macOS
-
-1. Install =gls= (GNU ls) from GNU coreutils
-
-#+begin_src bash
- brew install coreutils
-#+end_src
-
-2. Set ~insert-directory-program~ to =gls=
-
-#+begin_src emacs-lisp
- (setq insert-directory-program "gls")
-#+end_src
-
-** How to hide the parent directory?
-
-#+begin_src emacs-lisp
- (setq dirvish-default-layout '(0 0.4 0.6))
-#+end_src
-
-** How to hide continuation lines?
-
-Do not display continuation lines globally:
-
-#+begin_src emacs-lisp
- (setq-default truncate-lines t)
-#+end_src
-
-Or disable it only in dirvish:
-
-#+begin_src emacs-lisp
- (add-hook 'dirvish-find-entry-hook
- (lambda (&rest _) (setq-local truncate-lines t)))
-#+end_src
-
-Also see https://github.com/alexluigit/dirvish/issues/33
-
-** How to kill all session buffers on quit?
-
-Set ~dirvish-reuse-session~ to nil.
-
-** Dirvish does not respect listing switches?
-
-See [[#Parsing-switches][Parsing switches]] and [[#Sample-config][the sample
config]].
-
-** Why do I have duplicate icon columns?
-
-Disable =all-the-icons-dired= and =treemacs-icons-dired=.
diff --git a/docs/FAQ.org b/docs/FAQ.org
new file mode 100644
index 0000000000..a43a2b3077
--- /dev/null
+++ b/docs/FAQ.org
@@ -0,0 +1,52 @@
+#+AUTHOR: Alex Lu
+#+EMAIL: alexlui...@gmail.com
+#+startup: content
+
+* =listing directory failed but ‘access-file’ worked= error on macOS
+
+1. Install =gls= (GNU ls) from GNU coreutils
+
+#+begin_src bash
+ brew install coreutils
+#+end_src
+
+2. Set ~insert-directory-program~ to =gls=
+
+#+begin_src emacs-lisp
+ (setq insert-directory-program "gls")
+#+end_src
+
+* How to hide the parent directory?
+
+#+begin_src emacs-lisp
+ (setq dirvish-default-layout '(0 0.4 0.6))
+#+end_src
+
+* How to hide continuation lines?
+
+Do not display continuation lines globally:
+
+#+begin_src emacs-lisp
+ (setq-default truncate-lines t)
+#+end_src
+
+Or disable it only in dirvish:
+
+#+begin_src emacs-lisp
+ (add-hook 'dirvish-find-entry-hook
+ (lambda (&rest _) (setq-local truncate-lines t)))
+#+end_src
+
+Also see https://github.com/alexluigit/dirvish/issues/33
+
+* How to kill all session buffers on quit?
+
+Set ~dirvish-reuse-session~ to nil.
+
+* Dirvish does not respect listing switches?
+
+See [[file:CUSTOMIZING.org][Parsing switches]] and
[[file:CUSTOMIZING.org][sample config]].
+
+* Why do I have duplicate icon columns?
+
+Disable =all-the-icons-dired= and =treemacs-icons-dired=.
diff --git a/extensions/dirvish-emerge.el b/extensions/dirvish-emerge.el
index 75800d7a10..4a059b7a68 100644
--- a/extensions/dirvish-emerge.el
+++ b/extensions/dirvish-emerge.el
@@ -17,6 +17,7 @@
(declare-function dirvish-emerge--menu "dirvish-emerge")
(require 'dirvish)
+(require 'transient)
(defun dirvish-emerge-safe-groups-p (groups)
"Return t if GROUPS is a list and has less than 100 items."
diff --git a/extensions/dirvish-fd.el b/extensions/dirvish-fd.el
index 51c707f4ec..27894fab95 100644
--- a/extensions/dirvish-fd.el
+++ b/extensions/dirvish-fd.el
@@ -14,6 +14,7 @@
;;; Code:
(require 'dirvish)
+(require 'transient)
(defcustom dirvish-fd-switches ""
"Fd arguments inserted before user input."
diff --git a/extensions/dirvish-history.el b/extensions/dirvish-history.el
index 69e091cc63..dbaec25db5 100644
--- a/extensions/dirvish-history.el
+++ b/extensions/dirvish-history.el
@@ -14,6 +14,7 @@
;;; Code:
(require 'dirvish)
+(require 'transient)
;;;###autoload
(defun dirvish-history-jump ()
diff --git a/extensions/dirvish-ls.el b/extensions/dirvish-ls.el
index 71da259f26..586ced63e9 100644
--- a/extensions/dirvish-ls.el
+++ b/extensions/dirvish-ls.el
@@ -14,6 +14,7 @@
;;; Code:
(require 'dirvish)
+(require 'transient)
(defun dirvish-ls--clear-switches-choices ()
"Reload the listing switches setup UI."
diff --git a/extensions/dirvish-quick-access.el
b/extensions/dirvish-quick-access.el
index ac69cc19fb..ed51d28fae 100644
--- a/extensions/dirvish-quick-access.el
+++ b/extensions/dirvish-quick-access.el
@@ -21,6 +21,7 @@
;;; Code:
(require 'dirvish)
+(require 'transient)
(defcustom dirvish-quick-access-function 'dirvish-dwim
"Function used to access `dirvish-quick-access-entries'.
diff --git a/extensions/dirvish-subtree.el b/extensions/dirvish-subtree.el
index 4b7f487504..116df758e8 100644
--- a/extensions/dirvish-subtree.el
+++ b/extensions/dirvish-subtree.el
@@ -21,6 +21,7 @@
(declare-function consult-line "consult")
(require 'dirvish)
(require 'dired-x)
+(require 'transient)
(defcustom dirvish-subtree-listing-switches nil
"Listing SWITCHES used in subtrees.
diff --git a/extensions/dirvish-vc.el b/extensions/dirvish-vc.el
index 3b5bc3159e..bdaed22be5 100644
--- a/extensions/dirvish-vc.el
+++ b/extensions/dirvish-vc.el
@@ -15,6 +15,7 @@
;;; Code:
(require 'dirvish)
+(require 'transient)
(define-fringe-bitmap 'dirvish-vc-gutter [250] nil nil '(center repeated))
(defclass dirvish-vc-preview (transient-switches) ()
diff --git a/extensions/dirvish-yank.el b/extensions/dirvish-yank.el
index b108057344..cb14244493 100644
--- a/extensions/dirvish-yank.el
+++ b/extensions/dirvish-yank.el
@@ -27,6 +27,7 @@
(require 'dired-aux)
(require 'dirvish)
+(require 'transient)
(defcustom dirvish-yank-sources 'all
"The way to collect source files.
![https://elpa.nongnu.org/nongnu/dirvish.html][file:https://elpa.nongnu.org/nongnu/dirvish.svg](https://elpa.nongnu.org/nongnu/dirvish.html][file:https://elpa.nongnu.org/nongnu/dirvish.svg){kind=link}
![https://melpa.org/#/dirvish][file:https://melpa.org/packages/dirvish-badge.svg](https://melpa.org/#/dirvish][file:https://melpa.org/packages/dirvish-badge.svg){kind=link}
![https://stable.melpa.org/#/dirvish][file:https://stable.melpa.org/packages/dirvish-badge.svg](https://stable.melpa.org/#/dirvish][file:https://stable.melpa.org/packages/dirvish-badge.svg){kind=link}
![https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml][file:https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml/badge.svg](https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml][file:https://github.com/alexluigit/dirvish/actions/workflows/melpazoid.yml/badge.svg){kind=link}