diff options
Diffstat (limited to 'doc/misc/tramp.texi')
| -rw-r--r-- | doc/misc/tramp.texi | 469 |
1 files changed, 362 insertions, 107 deletions
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 0bed7dbe215..131a23b7423 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -142,6 +142,7 @@ on the remote host. * Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. +* Kubernetes setup:: Kubernetes setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. @@ -162,6 +163,7 @@ Using @value{tramp} How file names, directories and localnames are mangled and managed +* Temporary directory:: Where temporary files are kept. * Localname deconstruction:: Breaking a localname into its components. * External packages:: Integration with external Lisp packages. @@ -291,11 +293,12 @@ file's contents. For external transfers, @value{tramp} sends a command as follows: @example -$ scp user@@host:/path/to/remote/file /tmp/tramp.4711 +$ scp user@@host:/path/to/remote/file <TMP>/tramp.4711 @end example -@value{tramp} reads the local temporary file @file{/tmp/tramp.4711} -into a buffer, and then deletes the temporary file. +@value{tramp} reads the local temporary file @file{<TMP>/tramp.4711} +into a buffer, and then deletes the temporary +file.@footnote{@ref{Temporary directory}} @item Edit, modify, change the buffer contents as normal, and then save the @@ -374,7 +377,7 @@ From behind a proxy: @example @group -$ git config --global http.proxy http://user:pwd@@proxy.server.com:8080 +$ git config --global http.proxy https://user:pwd@@proxy.server.com:8080 $ git clone https://git.savannah.gnu.org/r/tramp.git @end group @end example @@ -485,24 +488,28 @@ an @command{ssh} server: @file{@trampfn{plink,user@@host,/path/to/file}}. -@anchor{Quick Start Guide su, sudo, doas and sg methods} -@section Using @option{su}, @option{sudo}, @option{doas} and @option{sg} +@anchor{Quick Start Guide su, sudo, doas, androidsu and sg methods} +@section Using @option{su}, @option{sudo}, @option{doas}, @option{androidsu} and @option{sg} @cindex method @option{su} @cindex @option{su} method @cindex method @option{sudo} @cindex @option{sudo} method @cindex method @option{doas} @cindex @option{doas} method +@cindex method @option{androidsu} +@cindex @option{androidsu} method @cindex method @option{sg} @cindex @option{sg} method Sometimes, it is necessary to work on your local host under different permissions. For this, you can use the @option{su} or @option{sudo} connection method. On OpenBSD systems, the @option{doas} connection -method offers the same functionality. These methods use @samp{root} -as default user name and the return value of @code{(system-name)} as -default host name. Therefore, it is convenient to open a file as -@file{@trampfn{sudo,,/path/to/file}}. +method offers the same functionality. If your local system is +Android, use the method @option{androidsu} instead of @option{su}. + +These methods use @samp{root} as default user name and the return +value of @code{(system-name)} as default host name. Therefore, it is +convenient to open a file as @file{@trampfn{sudo,,/path/to/file}}. The method @option{sg} stands for ``switch group''; here the user name is used as the group to change to. The default host name is the same. @@ -704,6 +711,7 @@ on the remote host. * Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. +* Kubernetes setup:: Kubernetes setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. @@ -815,6 +823,17 @@ editing as another user. The host can be either @samp{localhost} or the host returned by the function @command{(system-name)}. See @ref{Multi-hops} for an exception to this behavior. +@item @option{androidsu} +@cindex method @option{androidsu} +@cindex @option{androidsu} method +Because the default implementation of the @option{su} method and other +shell-based methods conflict with non-standard @command{su} +implementations popular among Android users and the restricted +command-line utilities distributed with that system, a largely +equivalent @option{androidsu} method is provided for that system with +workarounds for its many idiosyncrasies, with the exception that +multi-hops are unsupported. + @item @option{sudo} @cindex method @option{sudo} @cindex @option{sudo} method @@ -925,9 +944,31 @@ if desired. @cindex method @option{kubernetes} @cindex @option{kubernetes} method -Integration for containers in Kubernetes pods. The host name is a pod -name returned by @samp{kubectl get pods}. The first container in a -pod is used. +Integration for containers in Kubernetes pods. The host name is +@samp{@var{pod}}, or @samp{@var{container}.@var{pod}} if an +explicit container name shall be used. Otherwise, the first container +in a pod is used. + +This method does not support user names. + +@item @option{toolbox} +@cindex method @option{toolbox} +@cindex @option{toolbox} method + +Integration of Toolbox system containers. The host name may be either +a container's name or ID, as returned by @samp{toolbox list -c}. +Without a host name, the default Toolbox container for the host will +be used. + +This method does not support user names. + +@item @option{flatpak} +@cindex method @option{flatpak} +@cindex @option{flatpak} method + +Integration of Flatpak sandboxes. The host name may be either an +application ID, a sandbox instance ID, or a PID, as returned by +@samp{flatpak ps}. This method does not support user names. @@ -1033,6 +1074,20 @@ session. These methods support the @samp{-P} argument. +@item @option{dockercp} +@item @option{podmancp} +@cindex method @option{dockercp} +@cindex @option{dockercp} method +@cindex method @option{podmancp} +@cindex @option{podmancp} method + +These methods are similar to @option{docker} or @option{podman}, but +they use the command @command{docker cp} or @command{podman cp} for +transferring large files. + +These copy commands do not support file globs, and they ignore a user +name. + @item @option{fcp} @cindex method @option{fcp} @cindex @option{fcp} method @@ -1070,11 +1125,11 @@ decode programs. @cindex method @option{sudoedit} @cindex @option{sudoedit} method -The @option{sudoedit} method allows to edit a file as a different user -on the local host. You could regard this as @value{tramp}'s +The @option{sudoedit} method facilitates editing a file as a different +user on the local host. You could regard this as @value{tramp}'s implementation of the @command{sudoedit}. Contrary to the @option{sudo} method, all magic file name functions are implemented by -single @command{sudo @dots{}} commands. The purpose is to make +single @command{sudo @dots{}} commands. The purpose is to make editing such a file as secure as possible; there must be no session running in the Emacs background which could be attacked from inside Emacs. @@ -1359,7 +1414,7 @@ possible, @value{tramp} emulates those operations otherwise. @cindex @option{rclone} method @vindex tramp-rclone-program -The program @command{rclone} allows to access different system +The program @command{rclone} enables accessing different system storages in the cloud, see @uref{https://rclone.org/} for a list of supported systems. If the @command{rclone} program isn't found in your @env{PATH} environment variable, you can tell @value{tramp} its @@ -1378,14 +1433,6 @@ User names are part of the @command{rclone} configuration, and not needed in the remote file name. If a user name is contained in the remote file name, it is ignored. -Internally, @value{tramp} mounts the remote system storage at location -@file{/tmp/tramp.rclone.storage}, with @file{storage} being the name -of the configured system storage. - -The mount point and optional flags to the different @option{rclone} -operations could be passed as connection properties, @xref{Setup of -rclone method}. - Access via @option{rclone} is slow. If you have an alternative method for accessing the system storage, you should use it. @ref{GVFS-based methods} for example, methods @option{gdrive} and @@ -2018,7 +2065,7 @@ machine @var{host} port sudo login @var{user} password secret @var{user} and @var{host} are the strings returned by @code{(user-login-name)} and @code{(system-name)}. If one of these -methods is connected via a multi hop (@pxref{Multi-hops}), the +methods is connected via a multi-hop (@pxref{Multi-hops}), the credentials of the previous hop are used. @vindex auth-source-save-behavior @@ -2199,6 +2246,7 @@ to a remote home directory, like @option{adb}, @option{rclone} and The temporary directory on the remote host. If not specified, the default value is @t{"/data/local/tmp"} for the @option{adb} method, @t{"/C$/Temp"} for the @option{smb} method, and @t{"/tmp"} otherwise. +@ref{Temporary directory}. @item @t{"direct-async-process"} @@ -2226,8 +2274,8 @@ this property has no effect. The directory file name an @acronym{FUSE}-based file system is mounted on. The default value of this property is -@t{"/tmp/tramp.method.user@@host#port"} (not specified in -@code{tramp-methods}). +@t{"<TMP>/tramp.method.user@@host#port"} (not specified in +@code{tramp-methods}). @ref{Temporary directory}. @item @t{"mount-args"}@* @t{"copyto-args"}@* @@ -2349,7 +2397,7 @@ connection information}. If you want, for example, use @end group @end lisp -This works only for connection methods which allow to override the +This works only for connection methods which allow overriding the remote login shell, like @option{sshx} or @option{plink}. See @ref{Inline methods} and @ref{External methods} for connection methods which support this. @@ -2761,32 +2809,32 @@ allows you to set the @option{ControlPath} provided the variable Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as @samp{%%r}, @samp{%%h} and @samp{%%p}. -@vindex tramp-use-ssh-controlmaster-options +@vindex tramp-use-connection-share Using a predefined string in @code{tramp-ssh-controlmaster-options}, or puzzling an own string, happens only when user option -@code{tramp-use-ssh-controlmaster-options} is set to @code{t}. If the +@code{tramp-use-connection-share} is set to @code{t}. If the @file{~/.ssh/config} file is configured appropriately for the above behavior, then any changes to @command{ssh} can be suppressed with this @code{nil} setting: @lisp -(customize-set-variable 'tramp-use-ssh-controlmaster-options nil) +(customize-set-variable 'tramp-use-connection-share nil) @end lisp Sometimes, it is not possible to use OpenSSH's @option{ControlMaster} option for remote processes. This could result in concurrent access to the OpenSSH socket when reading data by different processes, which could block Emacs. In this case, setting -@code{tramp-use-ssh-controlmaster-options} to @code{suppress} disables -shared access. It is not needed to set this user option permanently -to @code{suppress}, binding the user option prior calling +@code{tramp-use-connection-share} to @code{suppress} disables shared +access. It is not needed to set this user option permanently to +@code{suppress}, binding the user option prior calling @code{make-process} is sufficient. @value{tramp} does this for esxample for compilation processes on its own. @vindex ProxyCommand@r{, ssh option} @vindex ProxyJump@r{, ssh option} -@code{tramp-use-ssh-controlmaster-options} should also be set to -@code{nil} or @code{suppress} if you use the @option{ProxyCommand} or +@code{tramp-use-connection-share} should also be set to @code{nil} or +@code{suppress} if you use the @option{ProxyCommand} or @option{ProxyJump} options in your @command{ssh} configuration. In order to use the @option{ControlMaster} option, @value{tramp} must @@ -2809,12 +2857,16 @@ Host * Check the @samp{ssh_config(5)} man page whether these options are supported on your proxy host. -On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to -@code{nil} by default, because the MS Windows and MSYS2 -implementations of @command{OpenSSH} do not support this option properly. +On MS Windows, @code{tramp-use-connection-share} is set to @code{nil} +by default, because the MS Windows and MSYS2 implementations of +@command{OpenSSH} do not support this option properly. -In PuTTY, you can achieve connection sharing in the @option{Connection/SSH} -entry, enabling the @option{Share SSH connections if possible} option. +In PuTTY, you can achieve connection sharing in the +@option{Connection/SSH} entry, enabling the @option{Share SSH +connections if possible} option. @code{tramp-use-connection-share} +must be set to @code{nil}. If @code{tramp-use-connection-share} is +set to @code{t} or @code{suppress}, @command{plink} is called with the +option @option{-share} or @option{-noshare}, respectively. @subsection Configure direct copying between two remote servers @@ -2933,10 +2985,11 @@ The fallback is to start Emacs from a shell. @section @acronym{FUSE} setup hints The @acronym{FUSE} file systems are mounted by default at -@file{/tmp/tramp.method.user@@host#port}. The user name and port -number are optional. If the file system is already mounted, it will -be used as it is. If the mount point does not exist yet, -@value{tramp} creates this directory. +@t{"<TMP>/tramp.method.user@@host#port"}.@footnote{@ref{Temporary +directory}} Method is either @t{"rclone"} or @t{"sshfs"}. The user +name and port number are optional. If the file system is already +mounted, it will be used as it is. If the mount point does not exist +yet, @value{tramp} creates this directory. The mount point can be overwritten by the connection property @t{"mount-point"}, @ref{Predefined connection information}. @@ -3100,6 +3153,29 @@ Open a remote connection with the more concise command @kbd{C-x C-f @end itemize +@node Kubernetes setup +@section Kubernetes setup hints + +With the @option{kubernetes} method, containers in Kubernetes pods can +be accessed. The host name is a pod name returned by @samp{kubectl +get pods}, or @samp{@var{container}.@var{pod}} if an explicit +container name shall be used. Otherwise, the first container in a pod +is used. + +Sometimes, asynchronous processes for a host without a dedicated +container name show a warning like @samp{Defaulted container +"container1" out of: container1, container2}. This can be mitigated +by setting the pod annotation +@samp{kubectl.kubernetes.io/default-container} to a proper value +(@samp{container1} in this example). + +@vindex tramp-kubernetes-context +@vindex tramp-kubernetes-namespace +@value{tramp} uses the default Kubernetes context and namespace. If +another context or namespace shall be used, configure the user options +@code{tramp-kubernetes-context} and @code{tramp-kubernetes-namespace}. + + @node Auto-save File Lock and Backup @section Auto-save, File Lock and Backup configuration @cindex auto-save @@ -3198,6 +3274,11 @@ auto-saved files to the same directory as the original file. Alternatively, set the user option @code{tramp-auto-save-directory} to direct all auto saves to that location. +@c Since Emacs 30. +@vindex remote-file-name-inhibit-auto-save +If you want to suppress auto-saving of remote files at all, set user +option @code{remote-file-name-inhibit-auto-save} to non-@code{nil}. + @c Since Emacs 29. @vindex remote-file-name-inhibit-auto-save-visited An alternative to @code{auto-save-mode} is @@ -3660,6 +3741,47 @@ host name of the previous hop is reused. Therefore, the following file name is equivalent to the previous example: @samp{@trampfn{ssh@value{postfixhop}remotehost|su,,}}. +@defopt tramp-completion-multi-hop-methods +When this list includes the last method in a multi-hop connection, the +remote host will be queried for a list of completion candidates. This +can, for example, provide a list of running docker or podman +containers on the remote host. + +@lisp +(customize-set-variable 'tramp-completion-multi-hop-methods + `(,tramp-docker-method ,tramp-podman-method)) +@end lisp +@end defopt + +A common use case for ad-hoc specifications is to visit a file or a +directory with proper permissions, for example with the @option{sudo} +method. The command @code{tramp-revert-buffer-with-sudo} supports +this. + +@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}). +@end deffn + +@defopt tramp-file-name-with-method +The method @code{tramp-revert-buffer-with-sudo} shows an alternate +buffer. It defaults to @code{sudo}, other valid methods are +@code{su}, @code{doas}, and @code{ksu}. + +@lisp +(customize-set-variable 'tramp-file-name-with-method "doas") +@end lisp +@end defopt + +These methods apply the user @samp{root} as default. If another user +shall be taken, add a proper rule to the user option +@code{tramp-default-user-alist} (@pxref{Default User}): + +@lisp +(add-to-list 'tramp-default-user-alist '("sudo" "remotehost" "admin")) +@end lisp + @node Home directories @section Expanding @file{~} to home directory @@ -3968,12 +4090,12 @@ connection-local variables. @vindex async-shell-command-width @vindex COLUMNS@r{, environment variable} -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}. +@value{tramp} cares about the user option +@code{async-shell-command-width} 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 @@ -4315,17 +4437,14 @@ It does not report the remote terminal name via @code{process-tty-name}. @item It does not set process property @code{remote-pid}. - -@item -It does not use @code{tramp-remote-path}. @end itemize 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 @option{ControlMaster} options, -and use your own settings in @file{~/.ssh/config}, @ref{Using ssh +@code{tramp-use-connection-share} to @code{nil} in order to bypass +@value{tramp}'s handling of the @option{ControlMaster} options, and +use your own settings in @file{~/.ssh/config}, @ref{Using ssh connection sharing}. @@ -4367,7 +4486,6 @@ Flushes the current buffer's remote connection objects, the same as in Flushes all active remote connection objects, the same as in @code{tramp-cleanup-connection}. This command removes also ad-hoc proxy definitions (@pxref{Ad-hoc multi-hops}). - @end deffn @deffn Command tramp-cleanup-all-buffers @@ -4376,6 +4494,20 @@ connections and ad-hoc proxy definition are cleaned up in addition to killing all buffers related to remote connections. @end deffn +@deffn Command tramp-cleanup-some-buffers +Similar to @code{tramp-cleanup-all-buffers}, where all remote +connections and ad-hoc proxy definition are cleaned up. However, +additional buffers are killed only if one of the functions in +@code{tramp-cleanup-some-buffers-hook} returns @code{t}. +@end deffn + +@defopt tramp-cleanup-some-buffers-hook +The functions in this hook determine, whether a remote buffer is +killed when @code{tramp-cleanup-some-buffers} is called. Per default, +remote buffers which are linked to a remote file, remote @code{dired} +buffers, and buffers related to a remote process are cleaned up. +@end defopt + @node Renaming remote files @section Renaming remote files @@ -4865,8 +4997,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on @w{Emacs 26}, @w{Emacs 27}, @w{Emacs -28}, and @w{Emacs 29}. +The package works successfully on @w{Emacs 27}, @w{Emacs 28}, @w{Emacs +29}, and @w{Emacs 30}. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -4925,6 +5057,36 @@ Disable file locks. Set @code{remote-file-name-inhibit-locks} to the same remote file. @item +@vindex remote-file-name-inhibit-auto-save +Keep auto-save files local. This is already the default configuration +in Emacs, don't change it. If you want to disable auto-saving for +remote files at all, set @code{remote-file-name-inhibit-auto-save} to +@code{t}, but think about the consequences! + +If you want to disable auto-saving just for selected connections, for +example due to security considerations, use connection-local variables +in order to set @code{buffer-auto-save-file-name}. If you, for +example, want to disable auto-saving for all @option{sudo} +connections, apply the following code. +@ifinfo +@xref{Connection Variables, , , emacs}. +@end ifinfo + +@lisp +@group +(connection-local-set-profile-variables + 'my-auto-save-profile + '((buffer-auto-save-file-name . nil))) +@end group + +@group +(connection-local-set-profiles + '(:application tramp :protocol "sudo") + 'my-auto-save-profile) +@end group +@end lisp + +@item Disable excessive traces. Set @code{tramp-verbose} to 3 or lower, default being 3. Increase trace levels temporarily when hunting for bugs. @@ -5065,6 +5227,41 @@ In order to disable those optimizations, set user option @item +@value{tramp} blocks Emacs at startup + +@vindex remote-file-name-access-timeout +Some packages, like @file{desktop.el} or @file{recentf.el}, access +remote files when loaded. If the requested file is not accessible, +@value{tramp} could block. In order to check whether this could +happen, add a test via @code{access-file} with a proper timeout prior +to loading these packages: + +@lisp +@group +(let ((remote-file-name-access-timeout 10)) + (access-file "@file{@trampfn{method,user@@host,/path/to/file}}" "error")) +@result{} nil +@end group +@end lisp + +The result @code{nil} means success. If the file is not accessible, +or if the underlying operations last too long, @code{access-file} +returns with an error. + +The value of the timeout (10 seconds in the example) depends on your +preference and on the quality of the connection to the remote host. +If the connection to the remote host isn't established yet, and if +this requires an interactive password, the timeout check doesn't work +properly. + +@c Since Emacs 30. +@strong{Note}: In recent versions of Emacs, both packages already +apply this check. You just need to customize +@code{remote-file-name-access-timeout} to the desired timeout (in +seconds). + + +@item Does @value{tramp} support @acronym{SSH} security keys? Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware @@ -5158,17 +5355,39 @@ customization is explained in user option @item Remote host does not understand default options for directory listing -Emacs computes the @command{dired} options based on the local host but -if the remote host cannot understand the same @command{ls} command, -then set them with a hook as follows: +@vindex dired-listing-switches +Emacs computes the @command{dired} options based on the local host. +Since @w{Emacs 30}, these options can be set connection-local. +@ifinfo +@xref{Connection Variables, , , emacs}. +@end ifinfo + +@lisp +@group +(connection-local-set-profile-variables + 'my-dired-profile + '((dired-listing-switches . "-ahl"))) +@end group + +@group +(connection-local-set-profiles + '(:application tramp :machine "remotehost") + 'my-dired-profile) +@end group +@end lisp + +@vindex dired-actual-switches +In older Emacsen, you can set the @command{dired} options with a hook +as follows: @lisp @group (add-hook 'dired-before-readin-hook (lambda () - (when (file-remote-p default-directory) - (setq dired-actual-switches "-al")))) + (when (string-equal + (file-remote-p default-directory 'host) "remotehost") + (setq dired-actual-switches "-ahl")))) @end group @end lisp @@ -5224,6 +5443,7 @@ HISTFILE=/dev/null @item Where are remote files trashed to? +@vindex remote-file-name-inhibit-delete-by-moving-to-trash Emacs can trash file instead of deleting @ifinfo them, @ref{Misc File Ops, Trashing , , emacs}. @@ -5231,9 +5451,10 @@ them, @ref{Misc File Ops, Trashing , , emacs}. @ifnotinfo them. @end ifnotinfo -Remote files are always trashed to the local trash, except remote -encrypted files (@pxref{Keeping files encrypted}), which are deleted -anyway. +Remote files are always trashed to the local trash, except the user +option @code{remote-file-name-inhibit-delete-by-moving-to-trash} is +non-@code{nil}, or it is a remote encrypted file (@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, @@ -5243,26 +5464,6 @@ be restored by moving them manually from @item -How to identify temporary files produced by @value{tramp}? - -@vindex tramp-temp-name-prefix -Temporary files are kept in your @code{temporary-file-directory} -directory, which is often @file{/tmp/}. By default, they have the -file name prefix @t{"tramp."}. If you want to change this prefix, for -example because you want to identify temporary files produced by -@code{file-local-copy} in your package, you can bind the variable -@code{tramp-temp-name-prefix} temporarily: - -@example -@group -(let ((tramp-temp-name-prefix "my-prefix.")) - (file-local-copy "@trampfn{ssh,,.emacs}")) -@result{} "/tmp/my-prefix.HDfgDZ" -@end group -@end example - - -@item How to shorten long file names when typing in @value{tramp}? Adapt several of these approaches to reduce typing. If the full name @@ -5735,16 +5936,6 @@ If you want to enable Ange FTP's syntax, add the following form: @end lisp @item -@vindex tramp-mode -To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to -@code{nil} in @file{.emacs}. @strong{Note}, that we don't use -@code{customize-set-variable}, in order to avoid loading @value{tramp}. - -@lisp -(setq tramp-mode nil) -@end lisp - -@item @vindex tramp-ignored-file-name-regexp To deactivate @value{tramp} for some look-alike remote file names, set @code{tramp-ignored-file-name-regexp} to a proper regexp in @@ -5760,6 +5951,29 @@ This is needed, if you mount for example a virtual file system on your local host's root directory as @file{/ssh:example.com:}. @item +@findex inhibit-remote-files +To disable both @value{tramp} (and Ange FTP), type @kbd{M-x +inhibit-remote-files @key{RET}}. You can also add this to your +@file{.emacs}. + +@lisp +(inhibit-remote-files) +@end lisp + +@item +@findex without-remote-files +If you write code, which is intended to run only for local files, you +can use the @code{without-remote-files} macro. + +@lisp +(without-remote-files @dots{}) +@end lisp + +This improves performance, because many primitive file name operations +don't check any longer for Tramp file name regexps then. + +@item +@findex tramp-unload-tramp To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @@ -5780,11 +5994,45 @@ programs. @chapter How file names, directories and localnames are mangled and managed @menu +* Temporary directory:: Where temporary files are kept. * Localname deconstruction:: Splitting a localname into its component parts. * External packages:: Integrating with external Lisp packages. @end menu +@node Temporary directory +@section Where temporary files are kept + +@vindex temporary-file-directory +Internally, @value{tramp} uses @t{"~/.cache/emacs"} +as local temporary directory if it exists. Otherwise, the value of +@code{temporary-file-directory} is used, which is often @t{"/tmp"}. + +@vindex tramp-compat-temporary-file-directory +@vindex <TMP> +This local temporary directory is kept in the constant +@code{tramp-compat-temporary-file-directory}. In this manual, we use +@t{"<TMP>"} for its value. + +The temporary directory on a remote host is @t{"/data/local/tmp"} for +the @option{adb} method, @t{"/C$/Temp"} for the @option{smb} method, +and @t{"/tmp"} otherwise. For some methods, this can be customized. + +@vindex tramp-temp-name-prefix +Temporary files have the file name prefix @t{"tramp."}. If you want +to change this prefix, for example because you want to identify +temporary files produced by @code{file-local-copy} in your package, +you can bind the variable @code{tramp-temp-name-prefix} temporarily: + +@example +@group +(let ((tramp-temp-name-prefix "my-prefix.")) + (file-local-copy "@trampfn{ssh,,.emacs}")) +@result{} "/tmp/my-prefix.HDfgDZ" +@end group +@end example + + @node Localname deconstruction @section Splitting a localname into its component parts @@ -5890,6 +6138,7 @@ wrapping the timer function body as follows: @chapter How to Customize Traces @vindex tramp-verbose @vindex tramp-debug-to-file +@vindex tramp-debug-command-messages @value{tramp} messages are raised with verbosity levels ranging from 0 to 10. @value{tramp} does not display all messages; only those with a @@ -5914,9 +6163,10 @@ The verbosity levels are @end itemize With @code{tramp-verbose} greater than or equal to 4, messages are -also written to a @value{tramp} debug buffer. Such debug buffers are -essential to bug and problem analyzes. For @value{tramp} bug reports, -set the @code{tramp-verbose} level to 6 (@pxref{Bug Reports}). +also written to the @value{tramp} debug buffer @file{*debug +tramp/foo*}. Such debug buffers are essential to bug and problem +analyzes. For @value{tramp} bug reports, set the @code{tramp-verbose} +level to 6 (@pxref{Bug Reports}). The debug buffer is in @ifinfo @@ -5955,13 +6205,18 @@ a file: (customize-set-variable 'tramp-debug-to-file t) @end lisp -The debug buffer is written as a file in your -@code{temporary-file-directory}, which is usually @file{/tmp/}. Use -this option with care, because it could decrease the performance of -@value{tramp} actions. +The debug buffer is written as a file in your @ref{Temporary +directory}. Use this option with care, because it could decrease the +performance of @value{tramp} actions. If @code{tramp-verbose} is greater than or equal to 11, @value{tramp} -function call traces are written to a @value{tramp} trace buffer. +function call traces are written to the buffer @file{*trace tramp/foo*}. + +When @code{tramp-debug-command-messages} is non-@code{nil}, the debug +buffer contains all messages with verbosity level 6 (sent and received +strings), and the entry and exit messages for the function +@code{tramp-file-name-handler}. This is intended for @value{tramp} +maintainers, analyzing the remote commands for performance analysis. @node GNU Free Documentation License |