From 3965f269d2d3549315a5647c6942ea0c0b97a1dc Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Sun, 23 Feb 2025 10:47:58 +0100 Subject: [PATCH] Tramp: Improve doc of ad-hoc multi-hop file names * doc/misc/tramp.texi (Ad-hoc multi-hops, Frequently Asked Questions): Improve description how ad-hoc multi-hop file names can be made persistent. (Bug#65039, Bug#76457) (cherry picked from commit 949739571ba48bcece296d805668de71b2481e82) --- doc/misc/tramp.texi | 74 +++++++++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 23 deletions(-) diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 0d4dc954674..247bbdf1262 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -3361,8 +3361,8 @@ Another option is to create better backup file naming with user and host names prefixed to the file name. For example, transforming @file{/etc/secretfile} to @file{~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile}, set the -@value{tramp} user option @code{tramp-backup-directory-alist} from -the existing user option @code{backup-directory-alist}. +@value{tramp} user option @code{tramp-backup-directory-alist} from the +existing user option @code{backup-directory-alist}. Then @value{tramp} backs up to a file name that is transformed with a prefix consisting of the DIRECTORY name. This file name prefixing @@ -3384,10 +3384,12 @@ Example: The backup file name of @file{@trampfn{su,root@@localhost,/etc/secretfile}} would be @ifset unified -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}. +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/@c +!su:root@@localhost:!etc!secretfile~}}. @end ifset @ifset separate -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}. +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/@c +![su!root@@localhost]!etc!secretfile~}}. @end ifset @vindex auto-save-file-name-transforms @@ -3837,15 +3839,21 @@ ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} Each involved method must be an inline method (@pxref{Inline methods}). -@value{tramp} adds the ad-hoc definitions on the fly to -@code{tramp-default-proxies-alist} and is available for reuse during -that Emacs session. Subsequent @value{tramp} connections to the same -remote host can then use the shortcut form: -@samp{@trampfn{ssh,you@@remotehost,/path}}. +@value{tramp} adds the ad-hoc definitions as an ephemeral record to +@code{tramp-default-proxies-alist}, which are available for reuse +during that Emacs session. Subsequent @value{tramp} connections to +the same remote host can then use the abbreviated form +@file{@trampfn{ssh,you@@remotehost,/path}}. +@anchor{tramp-show-ad-hoc-proxies} @defopt tramp-show-ad-hoc-proxies If this user option is non-@code{nil}, ad-hoc definitions are kept in -remote file names instead of showing the shortcuts. +remote file names instead of showing the abbreviations. This is +useful if the ad-hoc proxy definition shall be used in further Emacs +sessions, kept in configuration files of recentf and other packages. + +A non-@code{nil} setting of this option has effect only if set before +the connection is established. @lisp (customize-set-variable 'tramp-show-ad-hoc-proxies t) @@ -3856,10 +3864,18 @@ Ad-hoc definitions are removed from @code{tramp-default-proxies-alist} via the command @kbd{M-x tramp-cleanup-all-connections @key{RET}} (@pxref{Cleanup remote connections}). +@anchor{tramp-save-ad-hoc-proxies} @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in @code{tramp-default-proxies-alist} for future Emacs sessions, set -@code{tramp-save-ad-hoc-proxies} to non-@code{nil}. +@code{tramp-save-ad-hoc-proxies} to non-@code{nil}. The resulting +user option @code{tramp-default-proxies-alist} is saved in your +@file{.emacs} file. + +If you use saved configuration files with abbreviated ad-hoc proxy +definitions on another host, for example by distribution of the +@code{recentf-save-file}, you must distribute your @file{.emacs} file +as well. @lisp (customize-set-variable 'tramp-save-ad-hoc-proxies t) @@ -6026,18 +6042,30 @@ Thanks to @value{tramp} users for contributing to these recipes. @item -Why saved multi-hop file names do not work in a new Emacs session? - -When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc -multi-hops}) via bookmarks, recent files, filecache, bbdb, or another -package, use the full ad-hoc file name including all hops, like -@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}@c -news.my.domain,/opt/news/etc}}. - -Alternatively, when saving abbreviated multi-hop file names -@file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the user -option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil} -value. +Why don't saved ad-hoc multi-hop file names work in a new Emacs session? + +By default, ad-hoc multi-hop file names are abbreviated after +completing the initial connection. These abbreviated forms retain +only the final hop, and so only the Emacs session that generated the +abbreviated form can understand it. @xref{Ad-hoc multi-hops}. + +For example, after connecting to @file{@trampfn{ssh,bird@@bastion|@c +ssh@value{postfixhop}news@@news.my.domain,/opt/news/etc}}, the file +name becomes @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}. +If the abbreviated form is saved in a bookmark, the recent files list, +bbdb, or similar, a new Emacs session has no way to know that the +connection must go through @samp{bird@@bastion} first. + +There are two mechanisms to deal with this. The first is to customize +@code{tramp-show-ad-hoc-proxies} to a non-@code{nil} value, which +disables abbreviation. Then the fully-qualified ad-hoc multi-hop file +name is the one that will be both displayed and saved. +@xref{tramp-show-ad-hoc-proxies}. + +Alternatively, you can customize @code{tramp-save-ad-hoc-proxies} to a +non-@code{nil} value which means to save the information how an +abbreviated multi-hop file name can be expanded. +@xref{tramp-save-ad-hoc-proxies}. @item -- 2.39.5