diff options
Diffstat (limited to 'doc/misc/tramp.texi')
| -rw-r--r-- | doc/misc/tramp.texi | 133 |
1 files changed, 77 insertions, 56 deletions
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index bdf3b403d80..6738ed5123d 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -384,7 +384,7 @@ After one of the above commands, @file{~/emacs/tramp} will containing the latest version of @value{tramp}. @noindent -To fetch updates from the repository, use git pull: +To fetch updates from the repository, use @code{git pull}: @example @group @@ -1622,7 +1622,7 @@ support this command. @subsection Tunneling with ssh -With ssh, you could use the @code{ProxyCommand} entry in +With @command{ssh}, you could use the @option{ProxyCommand} entry in @file{~/.ssh/config}: @example @@ -1709,9 +1709,9 @@ Integration for LXD containers. A container is accessed via @item magit-tramp @cindex method @option{git} @cindex @option{git} method -Browsing git repositories with @code{magit}. A versioned file is +Browsing Git repositories with @code{magit}. A versioned file is accessed via @file{@trampfn{git,rev@@root-dir,/path/to/file}}. -@samp{rev} is a git revision, and @samp{root-dir} is a virtual host +@samp{rev} is a Git revision, and @samp{root-dir} is a virtual host name for the root directory, specified in @code{magit-tramp-hosts-alist}. @@ -1802,8 +1802,8 @@ in such files, it can return host names only. @item @code{tramp-parse-sconfig} @findex tramp-parse-sconfig -This function returns the host nicknames defined by @code{Host} entries -in @file{~/.ssh/config} style files. +This function returns the host nicknames defined by @option{Host} +entries in @file{~/.ssh/config} style files. @item @code{tramp-parse-shostkeys} @findex tramp-parse-shostkeys @@ -2280,6 +2280,12 @@ example below: @end group @end lisp +@vindex password-word-equivalents +This user option is, by default, initialised from +@code{password-word-equivalents} when @value{tramp} is loaded, and it +is usually more convenient to add new passphrases to that user option +instead of altering this user option. + Similar localization may be necessary for handling wrong password prompts, for which @value{tramp} uses @code{tramp-wrong-passwd-regexp}. @@ -2719,7 +2725,7 @@ corresponding password; otherwise there is no way to decrypt your encrypted files. @defopt tramp-crypt-save-encfs-config-remote -If this user option is non-nil (the default), the @option{encfs} +If this user option is non-@code{nil} (the default), the @option{encfs} configuration file @file{.encfs6.xml} is also kept in the encrypted remote directory. It depends on you, whether you regard the password protection of this file as sufficient. The advantage would be, that @@ -3083,19 +3089,6 @@ Example: @end group @end example -During file name completion, remote directory contents are re-read -regularly to account for any changes in the file system that may -affect the completion candidates. Such re-reads can account for -changes to the file system by applications outside Emacs -(@pxref{Connection caching}). - -@defopt tramp-completion-reread-directory-timeout -The timeout is number of seconds since last remote command for -rereading remote directory contents. A value of 0 re-reads -immediately during file name completion, @code{nil} uses cached -directory contents. -@end defopt - @node Ad-hoc multi-hops @section Declaring multiple hops in the file name @@ -3144,7 +3137,7 @@ to user @code{root} on host @code{remotehost}, starting with an @option{ssh} session on host @code{remotehost}: @samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. -On the other hand, if a trailing hop does not specifiy a host name, +On the other hand, if a trailing hop does not specify a host name, the host name of the previous hop is reused. Therefore, the following file name is equivalent to the previous example: @samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. @@ -3180,7 +3173,7 @@ or a string describing the signal, when the process has been interrupted. Since it cannot be determined reliably whether a remote process has been interrupted, @code{process-file} returns always the exit code. When the user option -@code{process-file-return-signal-string} is non-nil, +@code{process-file-return-signal-string} is non-@code{nil}, @code{process-file} regards all exit codes greater than 128 as an indication that the process has been interrupted, and returns a respective string. @@ -3311,8 +3304,8 @@ whatever reason, then replace @code{(getenv "DISPLAY")} with a hard-coded, fixed name. Note that using @code{:0} for X11 display name here will not work as expected. -An alternate approach is specify @code{ForwardX11 yes} or -@code{ForwardX11Trusted yes} in @file{~/.ssh/config} on the local +An alternate approach is specify @option{ForwardX11 yes} or +@option{ForwardX11Trusted yes} in @file{~/.ssh/config} on the local host. @@ -3386,22 +3379,22 @@ continuous output. @vindex shell-file-name @vindex shell-command-switch -@code{shell-command} uses the variables @code{shell-file-name} and -@code{shell-command-switch} in order to determine which shell to run. -For remote hosts, their default values are @file{/bin/sh} and -@option{-c}, respectively (except for the @option{adb} method, which -uses @file{/system/bin/sh}). Like the variables in the previous -section, these variables can be changed via connection-local -variables. +@code{shell-command} uses the user option @code{shell-file-name} and +the variable @code{shell-command-switch} in order to determine which +shell to run. For remote hosts, their default values are +@file{/bin/sh} and @option{-c}, respectively (except for the +@option{adb} method, which uses @file{/system/bin/sh}). Like the +variables in the previous section, these variables can be changed via +connection-local variables. @vindex async-shell-command-width @vindex COLUMNS@r{, environment variable} -If Emacs supports the variable @code{async-shell-command-width} (since -@w{Emacs 27}), @value{tramp} cares about its value for asynchronous -shell commands. It specifies the number of display columns for -command output. For synchronous shell commands, a similar effect can -be achieved by adding the environment variable @env{COLUMNS} to -@code{tramp-remote-process-environment}. +If Emacs supports the user option @code{async-shell-command-width} +(since @w{Emacs 27}), @value{tramp} cares about its value for +asynchronous shell commands. It specifies the number of display +columns for command output. For synchronous shell commands, a similar +effect can be achieved by adding the environment variable +@env{COLUMNS} to @code{tramp-remote-process-environment}. @subsection Running @code{eshell} on a remote host @@ -3577,7 +3570,7 @@ It works only for connection methods defined in @file{tramp-sh.el} and It does not support interactive user authentication. With @option{ssh}-based methods, this can be avoided by using a password agent like @command{ssh-agent}, using public key authentication, or -using @code{ControlMaster} options. +using @option{ControlMaster} options. @item It cannot be killed via @code{interrupt-process}. @@ -3600,7 +3593,7 @@ In order to gain even more performance, it is recommended to bind @code{tramp-verbose} to 0 when running @code{make-process} or @code{start-file-process}. Furthermore, you might set @code{tramp-use-ssh-controlmaster-options} to @code{nil} in order to -bypass @value{tramp}'s handling of the @code{ControlMaster} options, +bypass @value{tramp}'s handling of the @option{ControlMaster} options, and use your own settings in @file{~/.ssh/config}. @@ -3675,8 +3668,8 @@ On all buffers, which have a @code{buffer-file-name} matching prompted for modification in the minibuffer. The buffers are marked modified, and must be saved explicitly. -If user option @code{tramp-confirm-rename-file-names} is nil, changing -the file name happens without confirmation. This requires a +If user option @code{tramp-confirm-rename-file-names} is @code{nil}, +changing the file name happens without confirmation. This requires a matching entry in @code{tramp-default-rename-alist}. Remote buffers related to the remote connection identified by @@ -3715,8 +3708,8 @@ Tramp infers by default, such as @samp{@trampfn{method,user@@host,}}). name of @code{source} when calling @code{tramp-rename-files}. @code{source} could also be a Lisp form, which will be evaluated. The -result must be a string or nil, which is interpreted as a regular -expression which always matches. +result must be a string or @code{nil}, which is interpreted as a +regular expression which always matches. Example entries: @@ -4120,9 +4113,6 @@ files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or files are updated independent of @value{tramp}. -Set @code{tramp-completion-reread-directory-timeout} to @code{nil} to -speed up completions, @ref{File name completion}. - Disable version control to avoid delays: @lisp @@ -4274,8 +4264,8 @@ first saving to a temporary file. @vindex tramp-local-host-regexp When connecting to a local host, @value{tramp} uses some internal -optimizations. They fail, when there is a chrooted environment. In -order to disable those optimizations, set user option +optimizations. They fail when Emacs runs in a chrooted environment. +In order to disable those optimizations, set user option @code{tramp-local-host-regexp} to @code{nil}. @@ -4296,17 +4286,17 @@ Host * @item -@value{tramp} does not use default @command{ssh} @code{ControlPath} +@value{tramp} does not use default @command{ssh} @option{ControlPath} -@value{tramp} overwrites @code{ControlPath} settings when initiating +@value{tramp} overwrites @option{ControlPath} settings when initiating @command{ssh} sessions. @value{tramp} does this to fend off a stall if a master session opened outside the Emacs session is no longer open. That is why @value{tramp} prompts for the password again even if there is an @command{ssh} already open. @vindex tramp-ssh-controlmaster-options -Some @command{ssh} versions support a @code{ControlPersist} option, -which allows you to set the @code{ControlPath} provided the variable +Some @command{ssh} versions support a @option{ControlPersist} option, +which allows you to set the @option{ControlPath} provided the variable @code{tramp-ssh-controlmaster-options} is customized as follows: @lisp @@ -4331,12 +4321,16 @@ this @code{nil} setting: (customize-set-variable 'tramp-use-ssh-controlmaster-options nil) @end lisp +This shall also be set to @code{nil} if you use the +@option{ProxyCommand} or @option{ProxyJump} options in your +@command{ssh} configuration. + @item On multi-hop connections, @value{tramp} does not use @command{ssh} -@code{ControlMaster} +@option{ControlMaster} -In order to use the @code{ControlMaster} option, @value{tramp} must +In order to use the @option{ControlMaster} option, @value{tramp} must check whether the @command{ssh} client supports this option. This is only possible on the local host, for the first hop. @value{tramp} does not use this option on proxy hosts. @@ -4359,7 +4353,7 @@ supported on your proxy host. @item @value{tramp} does not connect to Samba or MS Windows hosts running -SMB1 connection protocol. +SMB1 connection protocol @vindex tramp-smb-options Recent versions of @command{smbclient} do not support old connection @@ -4518,6 +4512,21 @@ HISTFILE=/dev/null @item +Where are remote files trashed to? + +Emacs can trash file instead of deleting them, @ref{Misc File Ops, +Trashing , , emacs}. Remote files are always trashed to the local +trash, except remote encrypted files (@pxref{Keeping files +encrypted}), which are deleted anyway. + +If Emacs is configured to use the XDG conventions for the trash +directory, remote files cannot be restored with the respective tools, +because those conventions don't specify remote paths. Such files must +be restored by moving them manually from +@file{$@{XDG_DATA_HOME@}/Trash/files/}, if needed. + + +@item How to shorten long file names when typing in @value{tramp}? Adapt several of these approaches to reduce typing. If the full name @@ -4586,7 +4595,7 @@ completion can further reduce key strokes: @kbd{C-x C-f @value{prefix}ssh@value{postfixhop}x @key{TAB}}. @item -Use environment variables to expand long strings +Use environment variables to expand long strings: For long file names, set up environment variables that are expanded in the minibuffer. Environment variables are set either outside Emacs or @@ -4857,6 +4866,18 @@ remote files}. @item +I get a warning @samp{Tramp has been compiled with Emacs a.b, this is Emacs c.d} + +@value{tramp} comes with compatibility code for different Emacs +versions. When you see this warning, you don't use the Emacs built-in +version of @value{tramp}. In case you have installed @value{tramp} +from GNU ELPA, you must delete and reinstall it. +@ifset installchapter +In case you have installed it from its Git repository, @ref{Recompilation}. +@end ifset + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever |