From 4b85a321acf02bbf07bf8d0a4f5a83dd81aaa7b6 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 15 Mar 2025 19:32:35 +0800 Subject: [PATCH] ; Touch up tramp-*-with-sudo documentation, add FIXMEs * doc/emacs/dired.texi (Dired Visiting): * doc/emacs/files.texi (Reverting): * doc/misc/tramp.texi (Ad-hoc multi-hops): * etc/NEWS: * lisp/net/tramp-cmds.el (tramp-revert-buffer-with-sudo) (tramp-dired-find-file-with-sudo): Touch up documentation of these features. Add FIXMEs about renaming the two commands. (cherry picked from commit a57e9f45db6007bdb4af21a444f0ed62d1b2010e) --- doc/emacs/dired.texi | 9 +++++---- doc/emacs/files.texi | 12 +++++++----- doc/misc/tramp.texi | 5 ++--- lisp/net/tramp-cmds.el | 25 +++++++++++++++++++++---- 4 files changed, 35 insertions(+), 16 deletions(-) diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 0d7d7c4cf26..602c8e5bfb2 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -463,10 +463,11 @@ navigate the buffer but forbids changing it; @xref{View Mode}. @item @@ @kindex @@ @r{(Dired)} @findex tramp-dired-find-file-with-sudo -Open the file described on the current line, with root permissions -(@code{tramp-dired-find-file-with-sudo}). Calling it with the @kbd{C-u} -prefix argument asks for another Tramp method interactively but -@option{sudo}. @xref{Ad-hoc multi-hops, Tramp,, tramp, The Tramp Manual}. +Open the file described on the current line, with superuser, or root, +permissions (@code{tramp-dired-find-file-with-sudo}). If called with a +@kbd{C-u} prefix argument, it prompts for another Tramp method to use +other than the default, @option{sudo}. @xref{Ad-hoc multi-hops, Tramp,, +tramp, The Tramp Manual}. @item ^ @kindex ^ @r{(Dired)} diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index e7c5130c6b5..7f62603ae41 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1172,14 +1172,16 @@ the major mode actually turned on as result of reverting a buffer depends on mode remapping, and could be different from the original mode if you customized @code{major-mode-remap-alist} in-between. +@cindex reverting with superuser permissions @cindex reverting with root permissions @findex tramp-revert-buffer-with-sudo @kindex C-x x @@ -A variant of reverting a buffer is visiting it by the -@code{tramp-revert-buffer-with-sudo} (@kbd{C-x x @@}) command. It -reopens the file or Dired buffer with root permissions. With a prefix -argument of @kbd{C-u}, you could change the default Tramp method -(@option{sudo}). @xref{Ad-hoc multi-hops, Tramp,, tramp, The Tramp Manual}. +The @kbd{C-x x @@} keystroke is bound to the +@code{tramp-revert-buffer-with-sudo} command. This visits the file +again, but with superuser, or root, permissions. If called with a +@kbd{C-u} prefix argument, it prompts for another Tramp method to use +other than the default, @option{sudo}. @xref{Ad-hoc multi-hops, Tramp,, +tramp, The Tramp Manual}. @node Auto Revert @section Auto Revert: Keeping buffers automatically up-to-date diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 26143da9501..04811355b9a 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -3924,9 +3924,8 @@ method. The commands @code{tramp-revert-buffer-with-sudo} (@kbd{C-x x @kindex C-x x @@ @deffn Command tramp-revert-buffer-with-sudo -This command shows the current buffer with @option{sudo} permissions. -The buffer must either visit a file, or a directory -(@code{dired-mode}). +This command visits the current buffer with @option{sudo} permissions. +The buffer must either visit a file, or a directory in @code{dired-mode}. @end deffn @kindex @@ @r{(in dired}) diff --git a/lisp/net/tramp-cmds.el b/lisp/net/tramp-cmds.el index 2789d00380c..6db1e9bfd12 100644 --- a/lisp/net/tramp-cmds.el +++ b/lisp/net/tramp-cmds.el @@ -681,10 +681,21 @@ An alternative method could be chosen with `tramp-file-name-with-method'." (make-tramp-file-name :method tramp-file-name-with-method :localname filename)))) +;; FIXME: We would like to rename this for Emacs 31.1 to a name that +;; does not encode the default method. It is intended as a generic +;; privilege-elevation command. Some ideas from bug#76974: +;; `tramp-revert-buffer-obtain-root', +;; `tramp-revert-buffer-as-superuser'. + ;;;###autoload (defun tramp-revert-buffer-with-sudo () - "Revert current buffer to visit with \"sudo\" permissions. -An alternative method could be chosen with `tramp-file-name-with-method'. + "Visit the current file again with superuser, or root, permissions. + +By default this is done using the \"sudo\" Tramp method. +You can customize `tramp-file-name-with-method' to change this. + +Interactively, with a prefix argument, prompt for a different method. + If the buffer visits a file, the file is replaced. If the buffer runs `dired', the buffer is reverted." (interactive) @@ -706,10 +717,16 @@ If the buffer runs `dired', the buffer is reverted." (dired-advertise) (revert-buffer))))) +;; FIXME: See FIXME above about renaming this before Emacs 31.1. + ;;;###autoload (defun tramp-dired-find-file-with-sudo () - "In Dired, visit the file or directory named on this line. -This is performed with \"sudo\" permissions." + "Visit the file or directory named on this line as the superuser. + +By default this is done using the \"sudo\" Tramp method. +YOu can customize `tramp-file-name-with-method' to change this. + +Interactively, with a prefix argument, prompt for a different method." (interactive) (with-tramp-file-name-with-method (find-file (tramp-file-name-with-sudo (dired-get-file-for-visit))))) -- 2.39.5