branch: elpa/dirvish
commit 51ab5fa884fd1c2289befd51d695a6afaf01d400
Author: Alex Lu <hellosimon1...@hotmail.com>
Commit: Alex Lu <hellosimon1...@hotmail.com>
doc: document `dirvish-rsync.el` and adjust `dirvish-dispatch`
---
dirvish.el | 18 ++++++++++--------
docs/COMPARISON.org | 4 +---
docs/EXTENSIONS.org | 43 ++++++++++++++++++++++++++++++++-----------
extensions/dirvish-rsync.el | 14 +++++++-------
4 files changed, 50 insertions(+), 29 deletions(-)
diff --git a/dirvish.el b/dirvish.el
index 121e1397f7..368417d8bd 100644
--- a/dirvish.el
+++ b/dirvish.el
@@ -1353,7 +1353,14 @@ If `one-window-p' returns nil, open PATH using regular
Dired."
[:description
(lambda () (dirvish--format-menu-heading
"Dirvish main menu"
- "Press ? to see more info for the current 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)
@@ -1361,19 +1368,14 @@ If `one-window-p' returns nil, open PATH using regular
Dired."
("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)
- "" "Actions | Essential commands"
- ("/" "Perform fd search" dirvish-fd)
- ("@" "Find all dirs by fd" dirvish-fd-jump)
- ("n" "Live narrowing" dirvish-narrow)
- ("u" "User interface setup" dirvish-setup-menu)
- ("c" "Dired cheatsheet" dirvish-dired-cheatsheet)])
+ ("i" "Get file information" dirvish-file-info-menu)])
(provide 'dirvish)
;;; dirvish.el ends here
diff --git a/docs/COMPARISON.org b/docs/COMPARISON.org
index adb68f64b1..850bacf9a3 100644
--- a/docs/COMPARISON.org
+++ b/docs/COMPARISON.org
@@ -139,6 +139,4 @@ mesh well with =dirvish-subtree= nor =dired-subtree=.
* dired-rsync
-~dirvish-rsync~ command has feature parity of ~dired-rsync~. A exclusive
feature in
-~dirvish-rsync~ is that it can collect all marked files across different Dired
-buffers as the source files.
+See: [[file:EXTENSIONS.org][dirvish-rsync section in Extensions.org]]
diff --git a/docs/EXTENSIONS.org b/docs/EXTENSIONS.org
index 6bcef682cf..0082c0bd42 100644
--- a/docs/EXTENSIONS.org
+++ b/docs/EXTENSIONS.org
@@ -33,25 +33,46 @@ buffers into a single "clipboard", then copy or move all of
them to the target
location.
#+end_quote
-Multi-stage copy/paste, asynchronous I/O, work with TRAMP, =dirvish-yank= has
all
-of them. This package also provides the ~dirvish-rsync~ command, which can be
-seen as a alternative to =dired-rsync= package. =dirvish-yank= and friends
also
-handles file operations on the same remote host, see:
-https://github.com/stsquad/dired-rsync/issues/24.
-
-To copy/move/symlink/hardlink files from A to B, just mark the files in A, go
to
-B, and paste them with ~dirvish-yank/move/symlink/hardlink~.
+In addition to implementing the core logic described above, this extension also
+supports several frequently used commands. To transfer files from source to
+destination, mark the desired files, navigate to the destination, and use one
of
+the =dirvish-yank=, =dirvish-move=, =dirvish-symlink=,
=dirvish-relative-symlink= or
+=dirvish-hardlink= commands to complete the transfer. All of these commands
are
+executed *ASYNCHRONOUSLY* without any extra setups.
See also:
[[https://github.com/alexluigit/dirvish/blob/main/docs/FAQ.org#dired-ranger][comparison
with dired-ranger]]
* Integration with *rsync* command (dirvish-rsync.el)
This extension introduces =dirvish-rsync=, which requires
[[https://github.com/RsyncProject/rsync][rsync]] executable,
-mirroring the functionality of Alex Bennée's =dired-rsync=. Uniquely,
-=dirvish-rsync= gathers marked files from multiple Dired buffers. It also
-provides a transient menu =dirvish-rsync-menu=, for temporary adjustments to
+mirroring the functionality of Alex Bennée's =dired-rsync=. It also provides a
+transient menu =dirvish-rsync-switches-menu=, for temporary adjustments to
=dirvish-rsync-args=.
+** Compare to =dired-rsync=
+
++ =dirvish-rsync= also handles file operations on the same remote host.
+ See: https://github.com/stsquad/dired-rsync/issues/24.
+
++ =dirvish-rsync= takes advantages of the same multi-stage action mechanism in
+ =dirvish-yank=. Meaning that you should mark files first then goto target
+ directory and invoke =dirvish-rsync= there, instead of trying to do it in the
+ way of =dired-do-copy=.
+
++ It gathers marked files from multiple Dired buffers.
+
+** User options
+
+Configure ~dirvish-rsync-program~ and ~dirvish-rsync-args~ to specify the
executable
+path and command line arguments of =rsync=.
+
+~dirvish-rsync-r2r-ssh-port~, ~dirvish-rsync-r2r-ssh-user~ and
+~dirvish-rsync-r2r-use-direct-connection~ are provided to deal with the remote
to
+remote connections (thanks to @dvzubarev).
+
+Use ~dirvish-rsync-shortcut-key-for-yank-menu~ and
~dirvish-rsync-use-yank-menu~ to
+adjust the shortcut key of =dirvish-rsync= in =dirvish-yank-menu=.
+
* Group files with custom filter stack (dirvish-emerge.el)
This extension lets you split the file list into different groups by various
diff --git a/extensions/dirvish-rsync.el b/extensions/dirvish-rsync.el
index 8b54a92060..0f37d4e16e 100644
--- a/extensions/dirvish-rsync.el
+++ b/extensions/dirvish-rsync.el
@@ -12,8 +12,8 @@
;; This extension introduces `dirvish-rsync' command (which requires `rsync'
;; executable), mirroring the functionality of Alex Bennée's `dired-rsync'.
;; Uniquely, `dirvish-rsync' gathers marked files from multiple Dired buffers.
-;; It also provides a transient menu `dirvish-rsync-menu', for temporary
-;; adjustments to `dirvish-rsync-args'.
+;; It also provides a transient menu `dirvish-rsync-switches-menu', for
+;; temporary adjustments to `dirvish-rsync-args'.
;;; Code:
@@ -304,7 +304,7 @@ values."
(completing-read "direct: " '(yes no) nil t)))
(transient-define-prefix dirvish-rsync-transient-configure ()
- "Configure variables for `dirvish-rsync'."
+ "Configure romete-to-remote connections for `dirvish-rsync'."
["Remote to remote"
("rh" "Receiver host" dirvish-rsync--r2r-ssh-host)
("rp" "Receiver port" dirvish-rsync--r2r-ssh-port)
@@ -312,10 +312,10 @@ values."
("rd" "Direct connection" dirvish-rsync--r2r-direct-conn)])
;; inspired by `dired-rsync-transient'
-(define-obsolete-function-alias 'dirvish-rsync-transient #'dirvish-rsync-menu
"Feb 09, 2025")
-;;;###autoload (autoload 'dirvish-rsync-menu "dirvish-rsync" nil t)
-(transient-define-prefix dirvish-rsync-menu ()
- "Transient command for `dirvish-rsync'."
+(define-obsolete-function-alias 'dirvish-rsync-transient
#'dirvish-rsync-switches-menu "Feb 09, 2025")
+;;;###autoload (autoload 'dirvish-rsync-switches-menu "dirvish-rsync" nil t)
+(transient-define-prefix dirvish-rsync-switches-menu ()
+ "Transient menu for `dirvish-rsync'."
:init-value (lambda (o)
(oset o value (dirvish-rsync--transient-init-rsync-switches
o)))
["Common Arguments"
