@kbd{C-x C-f} to initiate find-file, enter part of the @value{tramp}
file name, then hit @kbd{@key{TAB}} for completion. If this is the
-first time connection to that host, here's what happens:
+first time connecting to that host, here's what happens:
@itemize
@item
If @value{tramp} does not receive any messages within a timeout period
(a minute, for example), then @value{tramp} responds with an error
-message about not finding the remote shell prompt. If any messages
-from the remote host, @value{tramp} displays them in the buffer.
+message about not finding the remote shell prompt. If there are any
+messages from the remote host, @value{tramp} displays them in the
+buffer.
For any @samp{login failed} message from the remote host,
-@value{tramp} aborts the login attempt, and repeats the login steps
-again.
+@value{tramp} aborts the login attempt, and repeats the login steps.
@item
-Upon successful login and @value{tramp} recognizes the shell prompt
+Upon successful login, if @value{tramp} recognizes the shell prompt
from the remote host, @value{tramp} prepares the shell environment by
-turning off echoing, setting shell prompt, and other housekeeping
+turning off echoing, setting the shell prompt, and other housekeeping
chores.
@strong{Note} that for the remote shell, @value{tramp} invokes
For inline transfers, @value{tramp} sends a command, such as
@samp{mimencode -b /path/to/remote/file}, waits until the output has
-accumulated in the buffer, decodes that output to produce the file's
-contents.
+accumulated in the buffer, then decodes that output to produce the
+file's contents.
For external transfers, @value{tramp} sends a command as follows:
@example
@end lisp
@value{tramp} is also available as @uref{https://elpa.gnu.org, GNU
-ELPA} package. Besides the standalone releases, further minor version
+ELPA} package. Besides the standalone releases, further minor versions
of @value{tramp} will appear on GNU ELPA, until the next @value{tramp}
release appears. These minor versions have a four-number string, like
``2.4.5.1''.
development version of @value{tramp} is always the version number of
the next release, plus the suffix ``-pre'', like ``2.4.4-pre''.
-One way to obtain @value{tramp} from Git server is to visit the
+One way to obtain @value{tramp} from the Git server is to visit the
Savannah project page at the following URL and then clicking on the
Git link in the navigation bar at the top.
@end example
@noindent
-From behind a firewall:
+From behind a proxy:
@example
@group
@end ifset
@ifclear installchapter
See the file @file{INSTALL} in that directory for further information
-how to install @value{tramp}.
+on how to install @value{tramp}.
@end ifclear
@chapter Short introduction how to use @value{tramp}
@cindex quick start guide
-@value{tramp} extends the Emacs file name syntax by a remote
-component. A remote file name looks always like
+@value{tramp} extends the Emacs file name syntax by adding a remote
+component. A remote file name always looks like
@file{@trampfn{method,user@@host,/path/to/file}}.
You can use remote files exactly like ordinary files, that means you
-could open a file or directory by @kbd{C-x C-f
+can open a file or directory by @kbd{C-x C-f
@trampfn{method,user@@host,/path/to/file} @key{RET}}, edit the file,
and save it. You can also mix local files and remote files in file
operations with two arguments, like @code{copy-file} or
-@code{rename-file}. And finally, you can run even processes on a
+@code{rename-file}. And finally, you can even run processes on a
remote host, when the buffer you call the process from has a remote
@code{default-directory}.
@section File name syntax
@cindex file name syntax
-Remote file names are prepended by the @code{method}, @code{user} and
-@code{host} parts. All of them, and also the local file name part,
-are optional, in case of a missing part a default value is assumed.
-The default value for an empty local file name part is the remote
-user's home directory. The shortest remote file name is
-@file{@trampfn{-,,}}, therefore. The @samp{-} notation for the
-default method is used for syntactical reasons, @ref{Default Method}.
+Remote file names have @code{method}, @code{user} and @code{host}
+parts prepended. All of them, and also the local file name part, are
+optional, in case of a missing part a default value is assumed. The
+default value for an empty local file name part is the remote user's
+home directory. The shortest remote file name is thus
+@file{@trampfn{-,,}}. The @samp{-} notation for the default method is
+used for syntactical reasons, @ref{Default Method}.
The @code{method} part describes the connection method used to reach
the remote host, see below.
The @code{user} part is the user name for accessing the remote host.
For the @option{smb} method, this could also require a domain name, in
-this case it is written as @code{user%domain}.
+which case it is written as @code{user%domain}.
-The @code{host} part must be a host name which could be resolved on
+The @code{host} part must be a host name which can be resolved on
your local host. It could be a short host name, a fully qualified
domain name, an IPv4 or IPv6 address, @ref{File name syntax}. Some
-connection methods support also a notation of the port to be used, in
-this case it is written as @code{host#port}.
+connection methods also support a notation for the port to be used, in
+which case it is written as @code{host#port}.
@anchor{Quick Start Guide: @option{ssh} and @option{plink} methods}
server, the simplest remote file name is
@file{@trampfn{ssh,user@@host,/path/to/file}}. The remote file name
@file{@trampfn{ssh,,}} opens a remote connection to yourself on the
-local host, and is taken often for testing @value{tramp}.
+local host, and is often used for testing @value{tramp}.
-On MS Windows, PuTTY is often used as SSH client. Its @command{plink}
+On MS Windows, PuTTY is often used as the SSH client. Its @command{plink}
method can be used there to open a connection to a remote host running
an @command{ssh} server:
@file{@trampfn{plink,user@@host,/path/to/file}}.
@cindex @option{sg} method
Sometimes, it is necessary to work on your local host under different
-permissions. For this, you could use the @option{su} or @option{sudo}
+permissions. For this, you can use the @option{su} or @option{sudo}
connection method. Both 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''; the changed group
-must be used here as user name. The default host name is the same.
+The method @option{sg} stands for ``switch group''; here the username
+is used as the group to change to. The default host name is the same.
@anchor{Quick Start Guide: @option{ssh}, @option{plink}, @option{su}, @option{sudo} and @option{sg} methods}
@cindex method @option{sudo}
@cindex @option{sudo} method
-If the @option{su} or @option{sudo} option shall be performed on
-another host, it could be comnbined with a leading @option{ssh} or
-@option{plink} option. That means, @value{tramp} connects first to
+If the @option{su} or @option{sudo} option should be performed on
+another host, it can be comnbined with a leading @option{ssh} or
+@option{plink} option. That means that @value{tramp} connects first to
the other host with non-administrative credentials, and changes to
administrative credentials on that host afterwards. In a simple case,
the syntax looks like
The @option{sudoedit} method is similar to the @option{sudo} method.
However, it is a different implementation: it does not keep an open
session running in the background. This is for security reasons; on
-the backside this method is less performant than the @option{sudo}
-method, it is restricted to the @samp{localhost} only, and it does not
+the backside this method has worse performance than the @option{sudo}
+method, it is restricted to @samp{localhost} only, and it does not
support external processes.
@cindex method @option{mtp}
@cindex @option{mtp} method
-On systems, which have installed @acronym{GVFS, the GNOME Virtual File
-System}, its offered methods could be used by @value{tramp}. Examples
-are @file{@trampfn{sftp,user@@host,/path/to/file}},
+On systems which have @acronym{GVFS, the GNOME Virtual File System}
+installed , its offered methods can be used by @value{tramp}.
+Examples are @file{@trampfn{sftp,user@@host,/path/to/file}},
@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
file system), @file{@trampfn{dav,user@@host,/path/to/file}},
@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares) and
@cindex @option{nextcloud} method
@cindex nextcloud
-@acronym{GVFS}-based methods include also @acronym{GNOME} Online
+@acronym{GVFS}-based methods also include @acronym{GNOME} Online
Accounts, which support the @option{Files} service. These are the
Google Drive file system, and the OwnCloud/NextCloud file system. The
-file name syntax is here always
+file name syntax here is always
@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}
(@samp{john.doe@@gmail.com} stands here for your Google Drive
account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}}
A convenient way to access system storages is the @command{rclone}
program. If you have configured a storage in @command{rclone} under a
-name @samp{storage} (for example), you could access it via the remote
+name @samp{storage} (for example), you can access it via the remote
file name syntax @file{@trampfn{rclone,storage,/path/to/file}}. User
names are not needed.
defaults to one of several other options, @xref{Connection types}.
@strong{Note} that some user options described in these examples are
-not auto loaded by Emacs. All examples require @value{tramp} is
+not auto loaded by Emacs. All examples require @value{tramp} to be
installed and loaded:
@lisp
@end lisp
For functions used to configure @value{tramp}, the following clause
-might be used in your init file:
+may be used in your init file:
@lisp
(with-eval-after-load 'tramp (tramp-change-syntax 'simplified))
transferring files, the overhead of the cryptographic negotiation at
startup may drown out the improvement in file transfer times.
-External methods should be configured such a way that they don't
-require a password (with @command{ssh-agent}, or such alike). Modern
+External methods should be configured in such a way that they don't
+require a password (with @command{ssh-agent}, or similar). Modern
@command{scp} implementations offer options to reuse existing
-@command{ssh} connections, which will be enabled by default if
-available. If it isn't possible, you should consider @ref{Password
-handling}, otherwise you will be prompted for a password every copy
-action.
+@command{ssh} connections, which @value{tramp} enables by default if
+available. If that is not possible, you should consider @ref{Password
+handling}, otherwise you will be prompted for a password for every
+copy action.
@node Inline methods
reliable command it finds. @value{tramp}'s search path can be
customized, see @ref{Remote programs}.
-In case none of the commands are unavailable, @value{tramp} first
-transfers a small Perl program to the remote host, and then tries that
-program for encoding and decoding.
+In case none of the commands are available, @value{tramp} first
+transfers a small Perl program to the remote host, and then tries to
+use that program for encoding and decoding.
@vindex tramp-inline-compress-start-size
@vindex tramp-inline-compress-commands
-To increase transfer speeds for large text files, use compression
-before encoding. The user option
-@code{tramp-inline-compress-start-size} specifies the file size for
-such optimization. This feature depends on the availability and
-usability of one of the commands defined in
+To increase transfer speeds for large text files, @value{tramp} can
+use compression before encoding. The user option
+@code{tramp-inline-compress-start-size} specifies the file size above
+which to use this optimization. This feature depends on the
+availability and usability of one of the commands defined in
@code{tramp-inline-compress-commands}.
@table @asis
@command{rsh} is an option for connecting to hosts within local
networks since @command{rsh} is not as secure as other methods.
+There should be no reason to use it, as @command{ssh} is a both a
+complete replacement and ubiquitous.
@item @option{ssh}
@cindex method @option{ssh}
@command{sudo} must have sufficient rights to start a shell.
For security reasons, a @option{sudo} connection is disabled after a
-predefined timeout (5 minutes per default). This can be changed, see
+predefined timeout (5 minutes by default). This can be changed, see
@ref{Predefined connection information}.
@item @option{doas}
@t{"copyto-args"} and @t{"moveto-args"}.
Access via @option{rclone} is slow. If you have an alternative method
-for accessing the system storage, you shall prefer this.
+for accessing the system storage, you should use it.
@ref{GVFS-based methods} for example, methods @option{gdrive} and
@option{nextcloud}.
@end example
@vindex auth-source-save-behavior
-If there doesn't exist a proper entry, the password is read
+If no proper entry exists, the password is read
interactively. After successful login (verification of the password),
-it is offered to save a corresponding entry for further use by
-@code{auth-source} backends which support this. This could be changed
+Emacs offers to save a corresponding entry for further use by
+@code{auth-source} backends which support this. This can be changed
by setting the user option @code{auth-source-save-behavior} to @code{nil}.
@vindex auth-source-debug
@itemize
@item @t{"login-program"}
-The property @t{"login-program"} keeps the program to be called in
-order to connect the remote host. Sometimes, the program might have
-another name on your host, or it is located on another path. In this
-case, you can overwrite the default value, which is special for every
+The property @t{"login-program"} stores the program to be used to
+connect to the remote host. Sometimes, the program might have another
+name on your host, or it might be located in another path. In this case,
+you can overwrite the default value, which is special for every
connection method. It is used in all connection methods of
@file{tramp-sh.el}.
host supports posix commands. If the remote host runs Samba, it
confirms this capability. However, some very old Samba versions have
errors in their implementation. In order to suppress the posix
-commands for those hosts, the property @t{"posix"} shall be set to
+commands for those hosts, the property @t{"posix"} should be set to
@code{nil}.
The default value of this property is @code{t} (not specified in
@code{tramp-methods}). If the remote host runs native MS Windows,
-there is no effect of this property.
+this propery has no effect.
@item @t{"mount-args"}@*
@t{"copyto-args"}@*
@subsection Changing the default remote or local shell
@cindex zsh setup
-Per default, @value{tramp} uses the command @command{/bin/sh} for
+By default, @value{tramp} uses the command @command{/bin/sh} for
starting a shell on the remote host. This can be changed by setting
the connection property @t{"remote-shell"}; see @pxref{Predefined
connection information}. If you want, for example, use
trouble with the shell prompt due to set zle options will be avoided.
Similar problems can happen with the local shell Tramp uses to create
-a process. Per default, it uses the command @command{/bin/sh} for
+a process. By default, it uses the command @command{/bin/sh} for
this, which could also be a link to another shell. In order to
overwrite this, you might apply
@value{tramp} uses the user option @code{tramp-terminal-type} to set
the remote environment variable @env{TERM} for the shells it runs.
-Per default, it is @t{"dumb"}, but this could be changed. A dumb
+By default, it is @t{"dumb"}, but this could be changed. A dumb
terminal is best suited to run the background sessions of
@value{tramp}. However, running interactive remote shells might
require a different setting. This could be achieved by tweaking the
@end lisp
@vindex process-file-return-signal-string
-@code{process-file} shall return either the exit code of the process,
-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
+For a local process, @code{process-file} returns either the exit code
+of the process, or a string describing a signal, when the process has
+been interrupted. Since it cannot be determined reliably whether a
+remote process has been interrupted, @code{process-file} will always
+returns the exit code for it. When the user option
@code{process-file-return-signal-string} is non-@code{nil},
-@code{process-file} regards all exit codes greater than 128 as an
+@code{process-file} treats all exit codes greater than 128 as an
indication that the process has been interrupted, and returns a
-respective string.
+corresponding string.
-Remote processes do not apply to @acronym{GVFS} (see @ref{GVFS-based
-methods}) because the remote file system is mounted on the local host
-and @value{tramp} just accesses by changing the
+This remote process handling does not apply to @acronym{GVFS} (see
+@ref{GVFS-based methods}) because the remote file system is mounted on
+the local host and @value{tramp} accesses it by changing the
@code{default-directory}.
@value{tramp} starts a remote process when a command is executed in a
@vindex INSIDE_EMACS@r{, environment variable}
@value{tramp} always modifies the @env{INSIDE_EMACS} environment
-variable for remote processes. Per default, this environment variable
+variable for remote processes. By default, this environment variable
shows the Emacs version. @value{tramp} adds its own version string,
so it looks like @samp{27.2,tramp:2.4.5.1}. However, other packages
might also add their name to this environment variable, like
@vindex ENV@r{, environment variable}
Setting the @env{ENV} environment variable instructs some shells to
-read an initialization file. Per default, @value{tramp} has disabled
-this. You could overwrite this behavior by evaluating
+read an initialization file. By default, @value{tramp} disables
+this. You can override this behavior by evaluating
@lisp
@group
@vindex ProxyCommand@r{, ssh option}
@vindex ProxyJump@r{, ssh option}
-This shall also be set to @code{nil} if you use the
+This should also be set to @code{nil} if you use the
@option{ProxyCommand} or @option{ProxyJump} options in your
@command{ssh} configuration.
Timers, process filters and sentinels, and other event based functions
can run at any time, when a remote file operation is still running.
This can cause @value{tramp} to block. When such a situation is
-detected, this error is triggered. It shall be fixed in the
-respective function (an error report will help), but for the time
-being you can suppress this error by the following code in your
+detected, this error is triggered. It should be fixed in the
+respective function (sending an error report will help), but for the
+time being you can suppress this error by the following code in your
@file{~/.emacs}:
@lisp
can run any remote file operation, which would conflict with the
already running remote file operation, if the same connection is
affected. @value{tramp} detects this situation, and raises the
-@code{remote-file-error} error. A timer function shall avoid this
-situation. At least, it shall protect itself against this error, by
-wrapping the timer function body with
+@code{remote-file-error} error. A timer function should avoid this
+situation. As a minimum, it should protect itself against this error, by
+wrapping the timer function body as follows:
@lisp
@group
@ref{Outline Visibility, , , emacs}.
@end ifinfo
-@value{tramp} handles errors internally. But to get a Lisp backtrace,
-both the error and the signal have to be set as follows:
+@value{tramp} handles errors internally. Hence, to get a Lisp backtrace,
+the following settings are required:
@lisp
@group
errors.
In very rare cases it could happen, that @value{tramp} blocks Emacs.
-Killing Emacs does not allow to inspect the debug buffer. In that
-case, you might instruct @value{tramp} to mirror the debug buffer to
-file:
+Killing Emacs does not allow inspecting the debug buffer. In that
+case, you can instruct @value{tramp} to mirror the debug buffer to
+a file:
@lisp
(customize-set-variable 'tramp-debug-to-file t)
@end lisp
-The debug buffer is written as file in your
+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.
projects / emacs.git / commitdiff