@setfilename ../../info/tramp
@c %**start of header
@settitle TRAMP User Manual
-@setchapternewpage odd
@c %**end of header
@c This is *so* much nicer :)
@include trampver.texi
-@c Macro for formatting a filename according to the repective syntax.
+@c Macro for formatting a filename according to the respective syntax.
@c xxx and yyy are auxiliary macros in order to omit leading and
@c trailing whitespace. Not very elegant, but I don't know it better.
@end macro
@copying
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
- 2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
@end copying
@c Entries for @command{install-info} to use
-@dircategory @value{emacsname}
+@dircategory @value{emacsname} network features
@direntry
-* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
- @value{emacsname} remote file access via rsh and rcp.
+* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
+ @value{emacsname} remote file access via rsh and rcp.
@end direntry
-@tex
-
@titlepage
@title @value{tramp} version @value{trampver} User Manual
-
@author by Daniel Pittman
@author based on documentation by Kai Gro@ss{}johann
-
@page
@insertcopying
-
@end titlepage
-@page
-@end tex
+@contents
@ifnottex
@node Top, Overview, (dir), (dir)
@end ifset
@ifhtml
-@ifset jamanual
-This manual is also available as a @uref{@value{japanesemanual},
-Japanese translation}.
-@end ifset
-
The latest release of @value{tramp} is available for
@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
@ref{Obtaining Tramp} for more details, including the CVS server
For the developer:
-* Version Control:: The inner workings of remote version control.
* Files directories and localnames:: How file names, directories and localnames are mangled and managed.
* Traces and Profiles:: How to Customize Traces.
* Issues:: Debatable Issues and What Was Decided.
* Installation parameters:: Parameters in order to control installation.
* Load paths:: How to plug-in @value{tramp} into your environment.
-* Japanese manual:: Japanese manual.
@end ifset
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
-* External transfer methods:: External transfer methods.
+* External methods:: External methods.
+@ifset emacsgvfs
+* GVFS based methods:: GVFS based external methods.
+@end ifset
@ifset emacsgw
* Gateway methods:: Gateway methods.
@end ifset
* Remote processes:: Integration with other @value{emacsname} packages.
* Cleanup remote connections:: Cleanup remote connections.
-The inner workings of remote version control
-
-* Version Controlled Files:: Determining if a file is under version control.
-* Remote Commands:: Executing the version control commands on the remote machine.
-* Changed workfiles:: Detecting if the working file has changed.
-* Checking out files:: Bringing the workfile out of the repository.
-* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
-
-Things related to Version Control that don't fit elsewhere
-
-* Remote File Ownership:: How VC determines who owns a workfile.
-* Back-end Versions:: How VC determines what release your RCS is.
-
How file names, directories and localnames are mangled and managed
* Localname deconstruction:: Breaking a localname into its components.
buffer that's used for communication, then decodes that output to
produce the file contents.
-For out-of-band transfers, @value{tramp} issues a command like the following:
+For external transfers, @value{tramp} issues a command like the
+following:
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
you are finished, you type @kbd{C-x C-s} to save the buffer.
@item
-Again, @value{tramp} transfers the file contents to the remote host either
-inline or out-of-band. This is the reverse of what happens when reading
-the file.
+Again, @value{tramp} transfers the file contents to the remote host
+either inline or external. This is the reverse of what happens when
+reading the file.
@end itemize
I hope this has provided you with a basic overview of what happens
@cindex obtaining Tramp
@value{tramp} is freely available on the Internet and the latest
-release may be downloaded from
-@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
-documentation and code for @value{tramp}, suitable for installation.
-But GNU Emacs (22 or later) includes @value{tramp} already, and there
-is a @value{tramp} package for XEmacs, as well. So maybe it is easier
-to just use those. But if you want the bleeding edge, read
-on@dots{...}
+release may be downloaded from @uref{ftp://ftp.gnu.org/gnu/tramp/}.
+This release includes the full documentation and code for
+@value{tramp}, suitable for installation. But Emacs (22 or later)
+includes @value{tramp} already, and there is a @value{tramp} package
+for XEmacs, as well. So maybe it is easier to just use those. But if
+you want the bleeding edge, read on@dots{...}
For the especially brave, @value{tramp} is available from CVS. The CVS
version is the latest version of the code and may contain incomplete
@example
] @strong{cd ~/@value{emacsdir}}
] @strong{export CVS_RSH="ssh"}
-] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
+] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp}
@end example
@noindent
] @strong{autoconf}
@end example
-People who have no direct CVS access (maybe because sitting behind a
-blocking firewall), can try the
-@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
-CVS Tree Tarball} instead of.
-
@node History
@chapter History of @value{tramp}
many more methods for getting a remote shell and for transferring the
file contents were added. Support for VC was added.
-The most recent addition of major features were the multi-hop methods
-added in April 2000 and the unification of @value{tramp} and Ange-FTP
-filenames in July 2002. In July 2004, multi-hop methods have been
-replaced by proxy hosts. Running commands on remote hosts was
-introduced in December 2005.
+After that, there were added the multi-hop methods in April 2000 and
+the unification of @value{tramp} and Ange-FTP filenames in July 2002.
+In July 2004, multi-hop methods have been replaced by proxy hosts.
+Running commands on remote hosts was introduced in December 2005.
@ifset emacsgw
Support of gateways exists since April 2007.
@end ifset
+@ifset emacsgvfs
+GVFS integration started in February 2009.
+@end ifset
In December 2001, @value{tramp} has been added to the XEmacs package
-repository. Being part of the GNU Emacs repository happened in June
-2002, the first release including @value{tramp} was GNU Emacs 22.1.
+repository. Being part of the Emacs repository happened in June 2002,
+the first release including @value{tramp} was Emacs 22.1.
-@value{tramp} is also a GNU/Linux Debian package since February 2001.
+@value{tramp} is also a Debian GNU/Linux package since February 2001.
@c Installation chapter is necessary only in case of standalone
@menu
* Connection types:: Types of connections made to remote machines.
* Inline methods:: Inline methods.
-* External transfer methods:: External transfer methods.
+* External methods:: External methods.
+@ifset emacsgvfs
+* GVFS based methods:: GVFS based external methods.
+@end ifset
@ifset emacsgw
* Gateway methods:: Gateway methods.
@end ifset
differ.
@cindex inline methods
-@cindex external transfer methods
@cindex external methods
-@cindex out-of-band methods
@cindex methods, inline
-@cindex methods, external transfer
-@cindex methods, out-of-band
+@cindex methods, external
Loading or saving a remote file requires that the content of the file
-be transfered between the two machines. The content of the file can be
-transfered over the same connection used to log in to the remote
-machine or the file can be transfered through another connection using
-a remote copy program such as @command{rcp}, @command{scp} or
-@command{rsync}. The former are called @dfn{inline methods}, the
-latter are called @dfn{out-of-band methods} or @dfn{external transfer
-methods} (@dfn{external methods} for short).
-
-The performance of the external transfer methods is generally better
-than that of the inline methods, at least for large files. This is
-caused by the need to encode and decode the data when transferring
-inline.
+be transferred between the two machines. The content of the file can
+be transferred using one of two methods: the @dfn{inline method} over
+the same connection used to log in to the remote machine, or the
+@dfn{external method} through another connection using a remote copy
+program such as @command{rcp}, @command{scp} or @command{rsync}.
+
+The performance of the external methods is generally better than that
+of the inline methods, at least for large files. This is caused by
+the need to encode and decode the data when transferring inline.
The one exception to this rule are the @command{scp} based transfer
methods. While these methods do see better performance when actually
transferring files, the overhead of the cryptographic negotiation at
startup may drown out the improvement in file transfer times.
-External transfer methods should be configured such a way that they
-don't require a password (with @command{ssh-agent}, or such alike).
-Modern @command{scp} implementations offer options to reuse existing
+External methods should be configured such a way that they don't
+require a password (with @command{ssh-agent}, or such alike). Modern
+@command{scp} implementations offer options to reuse existing
@command{ssh} connections, see method @command{scpc}. If it isn't
possible, you should consider @ref{Password handling}, otherwise you
will be prompted for a password every copy action.
transfers a small piece of Perl code to the remote host, and tries to
apply it for encoding and decoding.
+The variable @var{tramp-inline-compress-start-size} controls, whether
+a file shall be compressed before encoding. This could increase
+transfer speed for large text files.
+
@table @asis
@item @option{rsh}
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{ssh} method.)
-Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
-All the methods based on @command{ssh} have an additional kludgy
-feature: you can specify a host name which looks like @file{host#42}
-(the real host name, then a hash sign, then a port number). This
-means to connect to the given host but to also pass @code{-p 42} as
-arguments to the @command{ssh} command.
+All the methods based on @command{ssh} have an additional feature: you
+can specify a host name which looks like @file{host#42} (the real host
+name, then a hash sign, then a port number). This means to connect to
+the given host but to also pass @code{-p 42} as arguments to the
+@command{ssh} command.
@item @option{telnet}
invoked from an @value{emacsname} buffer, tells them that it is not
allocating a pseudo tty. When this happens, the login shell is wont
to not print any shell prompt, which confuses @value{tramp} mightily.
-For reasons unknown, some Windows ports for @command{ssh} require the
-doubled @samp{-t} option.
-This supports the @samp{-p} kludge.
+This supports the @samp{-p} argument.
@item @option{krlogin}
@command{krlogin -x} command to log in to the remote host.
+@item @option{ksu}
+@cindex method ksu
+@cindex ksu method
+@cindex Kerberos (with ksu method)
+
+This is another method from the Kerberos suite. It behaves like @option{su}.
+
+
@item @option{plink}
@cindex method plink
@cindex plink method
implementation of SSH. It uses @samp{plink -ssh} to log in to the
remote host.
-This supports the @samp{-P} kludge.
+This supports the @samp{-P} argument.
Additionally, the methods @option{plink1} and @option{plink2} are
provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
hasn't defined a user name. Different port numbers must be defined in
the session.
-
-@item @option{fish}
-@cindex method fish
-@cindex fish method
-
-This is an experimental implementation of the fish protocol, known from
-the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
-the fish server implementation from the KDE kioslave. That means, the
-file @file{~/.fishsrv.pl} is expected to reside on the remote host.
-
-The implementation lacks good performance. The code is offered anyway,
-maybe somebody can improve the performance.
-
@end table
-@node External transfer methods
-@section External transfer methods
-@cindex methods, external transfer
-@cindex methods, out-of-band
-@cindex external transfer methods
-@cindex out-of-band methods
+@node External methods
+@section External methods
+@cindex methods, external
+@cindex external methods
-The external transfer methods operate through multiple channels, using
-the remote shell connection for many actions while delegating file
+The external methods operate through multiple channels, using the
+remote shell connection for many actions while delegating file
transfers to an external transfer utility.
This saves the overhead of encoding and decoding that multiplexing the
transfer through the one connection has with the inline methods.
-Since external transfer methods need their own overhead opening a new
-channel, all files which are smaller than @var{tramp-copy-size-limit}
-are still transferred with the corresponding inline method. It should
-provide a fair trade-off between both approaches.
+Since external methods need their own overhead opening a new channel,
+all files which are smaller than @var{tramp-copy-size-limit} are still
+transferred with the corresponding inline method. It should provide a
+fair trade-off between both approaches.
@table @asis
@item @option{rcp} --- @command{rsh} and @command{rcp}
@file{~/.ssh/config}, the SSH configuration file, which protocol
should be used, and use the regular @option{scp} method.)
-Two other variants, @option{scp1_old} and @option{scp2_old}, use the
-@command{ssh1} and @command{ssh2} commands explicitly. If you don't
-know what these are, you do not need these options.
-
-All the @command{ssh} based methods support the kludgy @samp{-p}
-feature where you can specify a port number to connect to in the host
-name. For example, the host name @file{host#42} tells @value{tramp} to
+All the @command{ssh} based methods support the @samp{-p} feature
+where you can specify a port number to connect to in the host name.
+For example, the host name @file{host#42} tells @value{tramp} to
specify @samp{-p 42} in the argument list for @command{ssh}, and to
specify @samp{-P 42} in the argument list for @command{scp}.
@command{ftp} is called interactively, and all commands are send from
within this session. Instead of, @command{ssh} is used for login.
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{rsync} --- @command{ssh} and @command{rsync}
While @command{rsync} performs much better than @command{scp} when
transferring files that exist on both hosts, this advantage is lost if
-the file exists only on one side of the connection.
+the file exists only on one side of the connection. A file can exists
+on both the remote and local host, when you copy a file from/to a
+remote host. When you just open a file from the remote host (or write
+a file there), a temporary file on the local side is kept as long as
+the corresponding buffer, visiting this file, is alive.
-The @command{rsync} based method may be considerably faster than the
-@command{rcp} based methods when writing to the remote system. Reading
-files to the local machine is no faster than with a direct copy.
-
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{scpx} --- @command{ssh} and @command{scp}
allocating a pseudo tty. When this happens, the login shell is wont
to not print any shell prompt, which confuses @value{tramp} mightily.
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
@item @option{scpc} --- @command{ssh} and @command{scp}
-@cindex method scpx
-@cindex scpx method
-@cindex scp (with scpx method)
-@cindex ssh (with scpx method)
+@cindex method scpc
+@cindex scpc method
+@cindex scp (with scpc method)
+@cindex ssh (with scpc method)
Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
@option{ControlMaster}. This allows @option{scp} to reuse an existing
ssh localhost -o ControlMaster=yes
@end example
-This method supports the @samp{-p} hack.
+This method supports the @samp{-p} argument.
+
+
+@item @option{rsyncc} --- @command{ssh} and @command{rsync}
+@cindex method rsyncc
+@cindex rsyncc method
+@cindex rsync (with rsyncc method)
+@cindex ssh (with rsyncc method)
+
+Like the @option{scpc} method, @option{rsyncc} improves the underlying
+@command{ssh} connection by the option @option{ControlMaster}. This
+allows @command{rsync} to reuse an existing @command{ssh} channel,
+which increases performance.
+
+This method supports the @samp{-p} argument.
@item @option{pscp} --- @command{plink} and @command{pscp}
@command{pscp} for transferring the files. These programs are part
of PuTTY, an SSH implementation for Windows.
-This method supports the @samp{-P} hack.
+This method supports the @samp{-P} argument.
@item @option{psftp} --- @command{plink} and @command{psftp}
uses @command{psftp} for transferring the files. These programs are
part of PuTTY, an SSH implementation for Windows.
-This method supports the @samp{-P} hack.
+This method supports the @samp{-P} argument.
@item @option{fcp} --- @command{fsh} and @command{fcp}
@cindex method ftp
@cindex ftp method
-This is not a native @value{tramp} method. Instead of, it forwards all
+This is not a native @value{tramp} method. Instead, it forwards all
requests to @value{ftppackagename}.
@ifset xemacs
This works only for unified filenames, see @ref{Issues}.
@command{smbclient} command on different Unices in order to connect to
an SMB server. An SMB server might be a Samba (or CIFS) server on
another UNIX host or, more interesting, a host running MS Windows. So
-far, it is tested towards MS Windows NT, MS Windows 2000, and MS
+far, it is tested against MS Windows NT, MS Windows 2000, and MS
Windows XP.
The first directory in the localname must be a share name on the remote
-host. Remember, that the @code{$} character in which default shares
+host. Remember that the @code{$} character, in which default shares
usually end, must be written @code{$$} due to environment variable
substitution in file names. If no share name is given (i.e. remote
directory @code{/}), all available shares are listed.
-Since authorization is done on share level, you will be prompted
-always for a password if you access another share on the same host.
+Since authorization is done on share level, you will always be
+prompted for a password if you access another share on the same host.
This can be suppressed by @ref{Password handling}.
-MS Windows uses for authorization both a user name and a domain name.
+For authorization, MS Windows uses both a user name and a domain name.
Because of this, the @value{tramp} syntax has been extended: you can
specify a user name which looks like @code{user%domain} (the real user
name, then a percent sign, then the domain name). So, to connect to
prompting) is assumed. This is different from all other @value{tramp}
methods, where in such a case the local user name is taken.
-The @option{smb} method supports the @samp{-p} hack.
+The @option{smb} method supports the @samp{-p} argument.
@strong{Please note:} If @value{emacsname} runs locally under MS
-Windows, this method isn't available. Instead of, you can use UNC
+Windows, this method isn't available. Instead, you can use UNC
file names like @file{//melancholia/daniel$$/.emacs}. The only
disadvantage is that there's no possibility to specify another user
name.
+@end table
+
+
+@ifset emacsgvfs
+@node GVFS based methods
+@section GVFS based external methods
+@cindex methods, gvfs
+@cindex gvfs based methods
+@cindex dbus
+
+The connection methods described in this section are based on GVFS
+@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote
+filesystem is mounted locally through FUSE. @value{tramp} uses
+this local mounted directory internally.
+
+The communication with GVFS is implemented via D-Bus messages.
+Therefore, your @value{emacsname} must have D-Bus integration,
+@pxref{Top, , D-Bus, dbus}.
+
+@table @asis
+@item @option{dav}
+@cindex method dav
+@cindex method davs
+@cindex dav method
+@cindex davs method
+
+This method provides access to WebDAV files and directories. There
+exists also the external method @option{davs}, which uses SSL
+encryption for the access.
+
+Both methods support the port number specification as discussed above.
+
+
+@item @option{obex}
+@cindex method obex
+@cindex obex method
+OBEX is an FTP-like access protocol for simple devices, like cell
+phones. For the time being, @value{tramp} only supports OBEX over Bluetooth.
+
+
+@item @option{synce}
+@cindex method synce
+@cindex synce method
+
+The @option{synce} method allows communication with Windows Mobile
+devices. Beside GVFS for mounting remote files and directories via
+FUSE, it also needs the SYNCE-GVFS plugin.
@end table
+@defopt tramp-gvfs-methods
+This customer option, a list, defines the external methods which
+shall be used with GVFS. Per default, these are @option{dav},
+@option{davs}, @option{obex} and @option{synce}. Other possible
+values are @option{ftp}, @option{sftp} and @option{smb}.
+@end defopt
+@end ifset
+
@ifset emacsgw
@node Gateway methods
Therefore, they can be used for proxy host declarations
(@pxref{Multi-hops}) only.
-A gateway method must come always along with a method who supports
-port setting (referred to as @samp{-p} kludge). This is because
-@value{tramp} targets the accompanied method to
-@file{localhost#random_port}, from where the firewall or proxy server
-is accessed to.
+A gateway method must always come along with a method which supports
+port setting. This is because @value{tramp} targets the accompanied
+method to @file{localhost#random_port}, from where the firewall or
+proxy server is accessed.
Gateway methods support user name and password declarations. These
are used to authenticate towards the corresponding firewall or proxy
See the documentation for the variable
@code{tramp-default-method-alist} for more details.
-External transfer methods are normally preferable to inline transfer
-methods, giving better performance.
+External methods are normally preferable to inline methods, giving
+better performance.
@xref{Inline methods}.
-@xref{External transfer methods}.
+@xref{External methods}.
Another consideration with the selection of transfer methods is the
environment you will use them in and, especially when used over the
like to have some guidance, so here I'll try to give you this guidance
without bossing you around. You tell me whether it works @dots{}
-My suggestion is to use an inline method. For large files, out-of-band
-methods might be more efficient, but I guess that most people will want
-to edit mostly small files.
+My suggestion is to use an inline method. For large files, external
+methods might be more efficient, but I guess that most people will
+want to edit mostly small files. And if you access large text files,
+compression (driven by @var{tramp-inline-compress-start-size}) shall
+still result in good performance.
I guess that these days, most people can access a remote machine by
using @command{ssh}. So I suggest that you use the @option{ssh}
People who edit large files may want to consider @option{scpc} instead
of @option{ssh}, or @option{pscp} instead of @option{plink}. These
-out-of-band methods are faster than inline methods for large files.
-Note, however, that out-of-band methods suffer from some limitations.
+external methods are faster than inline methods for large files.
+Note, however, that external methods suffer from some limitations.
Please try first whether you really get a noticeable speed advantage
-from using an out-of-band method! Maybe even for large files, inline
+from using an external method! Maybe even for large files, inline
methods are fast enough.
has been reached so far. @code{sudo -u root}, applied on your local
host, wouldn't be useful here.
+@var{host}, @var{user} and @var{proxy} can also be Lisp forms. These
+forms are evaluated, and must return a string, or @code{nil}. The
+previous example could be generalized then: For all hosts except my
+local one connect via @code{ssh} first, and apply @code{sudo -u root}
+afterwards:
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
+(add-to-list 'tramp-default-proxies-alist
+ '((regexp-quote (system-name)) nil nil))
+@end lisp
+
This is the recommended configuration to work as @samp{root} on remote
Ubuntu hosts.
@item @code{tramp-parse-netrc}
@findex tramp-parse-netrc
-Finally, a function which parses @file{~/.netrc} like files.
+Finally, a function which parses @file{~/.netrc} like files. This
+includes also @file{~/.authinfo}-style files.
@end table
If you want to keep your own data in a file, with your own structure,
methods, or @command{pageant} for @option{plink}-like methods.
However, if you cannot apply such native password handling,
-@value{tramp} offers altenatives.
+@value{tramp} offers alternatives.
-@anchor{auth-sources}
+@anchor{Using an authentication file}
@subsection Using an authentication file
@vindex auth-sources
@end example
The port can be any @value{tramp} method (@pxref{Inline methods},
-@pxref{External transfer methods}), to match only this method. When
-you omit the port, you match all @value{tramp} methods.
+@pxref{External methods}), to match only this method. When you omit
+the port, you match all @value{tramp} methods.
+In case of problems, setting @code{auth-source-debug} to @code{t}
+gives useful debug messages.
-@anchor{password-cache}
+
+@anchor{Caching passwords}
@subsection Caching passwords
If there is no authentication file, @value{tramp} caches the passwords
When @value{tramp} detects a changed operating system version on a
remote host (via the command @command{uname -sr}), it flushes all
connection related information for this host, and opens the
-connection, again.
+connection again.
@node Remote Programs
In addition to these required tools, there are various tools that may be
required based on the connection method. See @ref{Inline methods} and
-@ref{External transfer methods} for details on these.
+@ref{External methods} for details on these.
Certain other tools, such as @command{perl} (or @command{perl5}) and
@command{grep} will be used if they can be found. When they are
remote file access.
@vindex tramp-remote-path
+@vindex tramp-default-remote-path
+@vindex tramp-own-remote-path
+@defopt tramp-remote-path
When @value{tramp} connects to the remote machine, it searches for the
programs that it can use. The variable @code{tramp-remote-path}
controls the directories searched on the remote machine.
machines. The symbol @code{tramp-default-remote-path} is a place
holder, it is replaced by the list of directories received via the
command @command{getconf PATH} on your remote machine. For example,
-on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
-@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
-recommended to apply this symbol on top of @code{tramp-remote-path}.
+on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris
+this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}.
+It is recommended to apply this symbol on top of
+@code{tramp-remote-path}.
It is possible, however, that your local (or remote ;) system
administrator has put the tools you want in some obscure local
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end lisp
+Another possibility is to reuse the path settings of your remote
+account when you log in. Usually, these settings are overwritten,
+because they might not be useful for @value{tramp}. The place holder
+@code{tramp-own-remote-path} preserves these settings. You can
+activate it via
+
+@lisp
+(add-to-list 'tramp-remote-path 'tramp-own-remote-path)
+@end lisp
+@end defopt
+
@value{tramp} caches several information, like the Perl binary
location. The changed remote search path wouldn't affect these
settings. In order to force @value{tramp} to recompute these values,
this line.
Another example is the tilde (@code{~}) character, say when adding
-@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
+@file{~/bin} to @code{PATH}. Many Bourne shells will not expand this
character, and since there is usually no directory whose name consists
of the single character tilde, strange things will happen.
@command{exec /bin/sh} step. But how to find out if the shell is
Bourne-ish?
+
+@item Interactive shell prompt
+
+@value{tramp} redefines the shell prompt in order to parse the shell's
+output robustly. When calling an interactive shell by @kbd{M-x
+shell}, this doesn't look nice.
+
+You can redefine the shell prompt by checking the environment variable
+@code{INSIDE_EMACS}, which is set by @value{tramp}, in your startup
+script @file{~/.emacs_SHELLNAME}. @code{SHELLNAME} might be the string
+@code{bash} or similar, in case of doubt you could set it the
+environment variable @code{ESHELL} in your @file{.emacs}:
+
+@lisp
+(setenv "ESHELL" "bash")
+@end lisp
+
+Your file @file{~/.emacs_SHELLNAME} could contain code like
+
+@example
+# Reset the prompt for remote Tramp shells.
+if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then
+ PS1="[\u@@\h \w]$ "
+fi
+@end example
+
+@ifinfo
+@ifset emacs
+@xref{Interactive Shell, , , @value{emacsdir}}.
+@end ifset
+@end ifinfo
+
@end table
@end lisp
@end ifset
+@ifset emacs
+It is also possible to disable backups depending on the used method.
+The following code disables backups for the @option{su} and
+@option{sudo} methods:
+
+@lisp
+(setq backup-enable-predicate
+ (lambda (name)
+ (and (normal-backup-enable-predicate name)
+ (not
+ (let ((method (file-remote-p name 'method)))
+ (when (stringp method)
+ (member method '("su" "sudo"))))))))
+@end lisp
+@end ifset
+
+
Another possibility is to use the @value{tramp} variable
@ifset emacs
@code{tramp-backup-directory-alist}.
The same problem can happen with auto-saving files.
@ifset emacs
-Since @value{emacsname} 21, the variable
-@code{auto-save-file-name-transforms} keeps information, on which
-directory an auto-saved file should go. By default, it is initialized
-for @value{tramp} files to the local temporary directory.
+The variable @code{auto-save-file-name-transforms} keeps information,
+on which directory an auto-saved file should go. By default, it is
+initialized for @value{tramp} files to the local temporary directory.
On some versions of @value{emacsname}, namely the version built for
Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
@end table
+@var{machine} can also be an IPv4 or IPv6 address, like in
+@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, ,
+@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}.
+@ifset emacs
+For syntactical reasons, IPv6 addresses must be embedded in square
+brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
+@end ifset
+
Unless you specify a different name to use, @value{tramp} will use the
current local user name as the remote user name to log in with. If you
need to log in as a different user, you can specify the user name as
@file{@trampfn{, daniel, melancholia, .emacs}}.
It is also possible to specify other file transfer methods
-(@pxref{Inline methods}, @pxref{External transfer methods}) as part of
-the filename.
+(@pxref{Inline methods}, @pxref{External methods}) as part of the
+filename.
@ifset emacs
This is done by putting the method before the user and host name, as
in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
@file{.emacs} in my home directory I would specify the filename
@file{@trampfn{ssh, daniel, melancholia, .emacs}}.
+Finally, for some methods it is possible to specify a different port
+number than the default one, given by the method. This is specified
+by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh,
+daniel, melancholia#42, .emacs}}.
+
@node Alternative Syntax
@section URL-like filename syntax
names, of user names and of machine names as well as for completion of
file names on remote machines.
@ifset emacs
-In order to enable this, Partial Completion mode must be set on.
+In order to enable this, partial completion must be activated in your
+@file{.emacs}.
@ifinfo
@xref{Completion Options, , , @value{emacsdir}}.
@end ifinfo
@key{TAB}}, @value{tramp} might give you as result the choice for
@example
+@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
@ifset emacs
-@value{prefixhop}telnet@value{postfixhop} tmp/
-@value{prefixhop}toto@value{postfix}
+@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
+@item @value{prefixhop}toto@value{postfix} @tab
@end ifset
@ifset xemacs
-@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
+@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix}
@end ifset
+@end multitable
@end example
@samp{@value{prefixhop}telnet@value{postfixhop}}
your @file{/etc/hosts} file, let's say
@example
-@trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
-@trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
-@trampfn{telnet, , melancholia,}
+@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
+@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,}
+@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,}
+@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,}
+@end multitable
@end example
Now you can choose the desired machine, and you can continue to
@value{tramp} uses for analysis of completion, offer user names, those user
names will be taken into account as well.
-Remote machines, which have been visited in the past and kept
-persistently (@pxref{Connection caching}), will be offered too.
+Remote machines which have been visited in the past and kept
+persistently (@pxref{Connection caching}) will be offered too.
Once the remote machine identification is completed, it comes to
filename completion on the remote host. This works pretty much like
A remote directory might have changed its contents out of
@value{emacsname} control, for example by creation or deletion of
-files by other processes. Therefore, during filename completion the
-remote directory contents is reread regularly in order to detect such
+files by other processes. Therefore, during filename completion, the
+remote directory contents are reread regularly in order to detect such
changes, which would be invisible otherwise (@pxref{Connection caching}).
@defopt tramp-completion-reread-directory-timeout
@value{tramp} supports running processes on a remote host. This
allows to exploit @value{emacsname} packages without modification for
remote file names. It does not work for the @option{ftp} and
-@option{smb} methods.
+@option{smb} methods. Association of a pty, as specified in
+@code{start-file-process}, is not supported.
+
+@code{process-file} and @code{start-file-process} work on the remote
+host when the variable @code{default-directory} is remote:
+
+@lisp
+(let ((default-directory "/ssh:remote.host:"))
+ (start-file-process "grep" (get-buffer-create "*grep*")
+ "/bin/sh" "-c" "grep -e tramp *"))
+@end lisp
+
+@ifset emacsgvfs
+If the remote host is mounted via GVFS (see @ref{GVFS based methods}),
+the remote filesystem is mounted locally. Therefore, there are no
+remote processes; all processes run still locally on your machine with
+an adapted @code{default-directory}. This section does not apply for
+such connection methods.
+@end ifset
Remote processes are started when a corresponding command is executed
from a buffer belonging to a remote file or directory. Up to now, the
Changing or removing an existing entry is not encouraged. The default
values are chosen for proper @value{tramp} work. Nevertheless, if for
example a paranoid system administrator disallows changing the
-@var{$HISTORY} environment variable, you can customize
+@code{HISTORY} environment variable, you can customize
@code{tramp-remote-process-environment}, or you can apply the
following code in your @file{.emacs}:
integrate them as well. @xref{Bug Reports}.
-@subsection Running shell-command on a remote host
+@subsection Running remote programs that create local X11 windows
+
+If you want to run a remote program, which shall connect the X11
+server you are using with your local host, you can set the
+@code{DISPLAY} environment variable on the remote host:
+
+@lisp
+(add-to-list 'tramp-remote-process-environment
+ (format "DISPLAY=%s" (getenv "DISPLAY")))
+@end lisp
+
+@noindent
+@code{(getenv "DISPLAY")} shall return a string containing a host
+name, which can be interpreted on the remote host; otherwise you might
+use a fixed host name. Strings like @code{:0} cannot be used properly
+on the remote host.
+
+Another trick might be that you put @code{ForwardX11 yes} or
+@code{ForwardX11Trusted yes} to your @file{~/.ssh/config} file for
+that host.
+
+
+@subsection Running @code{shell} on a remote host
+@cindex shell
+
+Calling @code{M-x shell} in a buffer related to a remote host runs the
+local shell as defined in @option{shell-file-name}. This might be
+also a valid path name for a shell to be applied on the remote host,
+but it will fail at least when your local and remote hosts belong to
+different system types, like @samp{windows-nt} and @samp{gnu/linux}.
+
+You must set the variable @option{explicit-shell-file-name} to the
+shell path name on the remote host, in order to start that shell on
+the remote host.
+
+@ifset emacs
+Starting with Emacs 24 this won't be necessary, if you call
+@code{shell} interactively. You will be asked for the remote shell
+path, if you are on a remote buffer, and if
+@option{explicit-shell-file-name} is equal to @code{nil}.
+@end ifset
+
+
+@subsection Running @code{shell-command} on a remote host
@cindex shell-command
@code{shell-command} allows to execute commands in a shell, either
@end example
You will see the buffer @file{*Async Shell Command*}, containing the
-continous output of the @command{tail} command.
+continuous output of the @command{tail} command.
-@subsection Running eshell on a remote host
+@subsection Running @code{eshell} on a remote host
@cindex eshell
@value{tramp} is integrated into @file{eshell.el}. That is, you can
open an interactive shell on your remote host, and run commands there.
-After you have started @code{eshell}, you could perform commands like
-this:
+After you have started @code{M-x eshell}, you could perform commands
+like this:
@example
@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
@b{@trampfn{sudo, root, host, /etc} $}
@end example
+@ifset emacs
+Since @value{emacsname} 23.2, @code{eshell} has also an own
+implementation of the @code{su} and @code{sudo} commands. Both
+commands change the default directory of the @file{*eshell*} buffer to
+the value related to the user the command has switched to. This works
+even on remote hosts, adding silently a corresponding entry to the
+variable @code{tramp-default-proxies-alist} (@pxref{Multi-hops}):
+
+@example
+@b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET}
+@b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET}
+File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow}
+@b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET}
+#<buffer shadow>
+
+@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET}
+@b{@trampfn{su, root, remotehost, /root} $} id @key{RET}
+uid=0(root) gid=0(root) groups=0(root)
+@b{@trampfn{su, root, remotehost, /root} $}
+@end example
+@end ifset
+
@anchor{Running a debugger on a remote host}
@subsection Running a debugger on a remote host
connection buffers.
@end deffn
+@deffn Command tramp-cleanup-this-connection
+This command flushes all objects of the current buffer's remote
+connection. The same objects are removed as in
+@code{tramp-cleanup-connection}.
+@end deffn
+
@deffn Command tramp-cleanup-all-connections
This command flushes objects for all active remote connections. The
same objects are removed as in @code{tramp-cleanup-connection}.
@item
Which systems does it work on?
-The package has been used successfully on GNU Emacs 21, GNU Emacs 22
-and XEmacs 21 (starting with 21.4). Gateway methods are supported for
-GNU Emacs 22 only.
+The package has been used successfully on Emacs 22, Emacs 23, Emacs
+24, XEmacs 21 (starting with 21.4), and SXEmacs 22.
The package was intended to work on Unix, and it really expects a
Unix-like system on the remote end (except the @option{smb} method),
but some people seemed to have some success getting it to work on MS
-Windows NT/2000/XP @value{emacsname}.
+Windows XP/Vista/7 @value{emacsname}.
-There is some informations on @value{tramp} on NT at the following URL;
-many thanks to Joe Stoy for providing the information:
-@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
-
-@c The link is broken. I've contacted Tom for clarification. Michael.
-@ignore
-The above mostly contains patches to old ssh versions; Tom Roche has a
-Web page with instructions:
-@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
-@end ignore
@item
How could I speed up @value{tramp}?
In order to speed up @value{tramp}, one could either try to avoid some
of the operations, or one could try to improve their performance.
-Use an external transfer method, like @option{scpc}.
+Use an external method, like @option{scpc}.
Use caching. This is already enabled by default. Information about
the remote host as well as the remote files are cached for reuse. The
information about remote hosts is kept in the file specified in
-@code{tramp-persistency-file-name}. Keep this file.
+@code{tramp-persistency-file-name}. Keep this file. If you are
+confident that files on remote hosts are not changed out of
+@value{emacsname}' control, set @code{remote-file-name-inhibit-cache}
+to @code{nil}.
Disable version control. If you access remote files which are not
under version control, a lot of check operations can be avoided by
disabling VC. This can be achieved by
@lisp
-(setq vc-handled-backends nil)
+(setq vc-ignore-dir-regexp
+ (format "\\(%s\\)\\|\\(%s\\)"
+ vc-ignore-dir-regexp
+ tramp-file-name-regexp))
@end lisp
Disable excessive traces. The default trace level of @value{tramp},
@item
@value{tramp} does not connect to the remote host
-When @value{tramp} does not connect to the remote host, there are two
+When @value{tramp} does not connect to the remote host, there are three
reasons heading the bug mailing list:
@itemize @minus
-
@item
Unknown characters in the prompt
@value{tramp} needs to recognize the prompt on the remote machine
-after execution any command. This is not possible, when the prompt
+after execution any command. This is not possible when the prompt
contains unknown characters like escape sequences for coloring. This
should be avoided on the remote side. @xref{Remote shell setup}. for
setting the regular expression detecting the prompt.
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
@end example
+Furthermore it has been reported, that @value{tramp} (like sshfs,
+incidentally) doesn't work with WinSSHD due to strange prompt settings.
+
+@item
+Echoed characters after login
+
+When the remote machine opens an echoing shell, there might be control
+characters in the welcome message. @value{tramp} tries to suppress
+such echoes via the @code{stty -echo} command, but sometimes this
+command is not reached, because the echoed output has confused
+@value{tramp} already. In such situations it might be helpful to use
+the @option{sshx} or @option{scpx} methods, which allocate a pseudo tty.
+@xref{Inline methods}.
@item
@value{tramp} doesn't transfer strings with more than 500 characters
(when (file-remote-p default-directory)
(set (make-local-variable 'file-precious-flag) t))))
@end lisp
-
@end itemize
+@item
+@value{tramp} does not recognize hung @command{ssh} sessions
+
+When your network connection is down, @command{ssh} sessions might
+hang. @value{tramp} cannot detect it safely, because it still sees a
+running @command{ssh} process. Timeouts cannot be used as well,
+because it cannot be predicted how long a remote command will last,
+for example when copying very large files.
+
+Therefore, you must configure the @command{ssh} process to die
+in such a case. The following entry in @file{~/.ssh/config} would do
+the job:
+
+@example
+Host *
+ ServerAliveInterval 5
+@end example
+
+
@item
File name completion does not work with @value{tramp}
The file name left to type would be
@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
-Note, that there are some useful settings already. Accessing your
+Note that there are some useful settings already. Accessing your
local host as @samp{root} user, is possible just by @kbd{C-x C-f
@trampfn{su, , ,}}.
@end lisp
Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
-are. The disadvantage is, that you cannot edit the file name, because
+are. The disadvantage is that you cannot edit the file name, because
environment variables are not expanded during editing in the
minibuffer.
'("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
@end lisp
-This shortens the file openening command to @kbd{C-x C-f /xy
+This shortens the file opening command to @kbd{C-x C-f /xy
@key{RET}}. The disadvantage is, again, that you cannot edit the file
name, because the expansion happens after entering the file name only.
Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
Because BBDB is not prepared for @value{tramp} syntax, you must
-specify a method together with the user name, when needed. Example:
+specify a method together with the user name when needed. Example:
@example
@kbd{M-x bbdb-create-ftp-site @key{RET}}
@end enumerate
-I would like to thank all @value{tramp} users, who have contributed to
+I would like to thank all @value{tramp} users who have contributed to
the different recipes!
+@ifset emacs
@item
-How can I disable @value{tramp}?
+How can I use @value{tramp} to connect to a remote @value{emacsname}
+session?
-Shame on you, why did you read until now?
+You can configure Emacs Client doing this.
+@ifinfo
+@xref{Emacs Server, , , @value{emacsdir}}.
+@end ifinfo
+
+On the remote host, you start the Emacs Server:
+
+@lisp
+(require 'server)
+(setq server-host (system-name)
+ server-use-tcp t)
+(server-start)
+@end lisp
+
+Make sure that the result of @code{(system-name)} can be resolved on
+your local host; otherwise you might use a hard coded IP address.
+
+The resulting file @file{~/.emacs.d/server/server} must be copied to
+your local host, at the same location. You can call then the Emacs
+Client from the command line:
+
+@example
+emacsclient @trampfn{ssh, user, host, /file/to/edit}
+@end example
+
+@code{user} and @code{host} shall be related to your local host.
+
+If you want to use Emacs Client also as editor for other programs, you
+could write a script @file{emacsclient.sh}:
+
+@example
+#!/bin/sh
+emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
+@end example
+
+Then you must set the environment variable @code{EDITOR} pointing to
+that script:
+
+@example
+export EDITOR=/path/to/emacsclient.sh
+@end example
+@end ifset
+
+
+@item
+There are packages which call @value{tramp} although I haven't entered
+a remote file name ever. I dislike it, how could I disable it?
+
+In general, @value{tramp} functions are used only when
+you apply remote file name syntax. However, some packages enable
+@value{tramp} on their own.
@itemize @minus
+@item
+@file{ido.el}
+
+You could disable @value{tramp} file name completion:
+
+@lisp
+(custom-set-variables
+ '(ido-enable-tramp-completion nil))
+@end lisp
@item
+@file{rlogin.el}
+
+You could disable remote directory tracking mode:
+
+@lisp
+(rlogin-directory-tracking-mode -1)
+@end lisp
+@end itemize
+
+
+@item
+How can I disable @value{tramp} at all?
+
+Shame on you, why did you read until now?
+
+@itemize @minus
@ifset emacs
+@item
If you just want to have @value{ftppackagename} as default remote
files access package, you should apply the following code:
@c For the developer
-@node Version Control
-@chapter The inner workings of remote version control
-@cindex Version Control
-
-Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
-remote machine. This makes it possible to provide version control for
-files accessed under @value{tramp}.
-
-The actual version control binaries must be installed on the remote
-machine, accessible in the directories specified in
-@code{tramp-remote-path}.
-
-This transparent integration with the version control systems is one of
-the most valuable features provided by @value{tramp}, but it is far from perfect.
-Work is ongoing to improve the transparency of the system.
-
-@menu
-* Version Controlled Files:: Determining if a file is under version control.
-* Remote Commands:: Executing the version control commands on the remote machine.
-* Changed workfiles:: Detecting if the working file has changed.
-* Checking out files:: Bringing the workfile out of the repository.
-* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
-@end menu
-
-
-@node Version Controlled Files
-@section Determining if a file is under version control
-
-The VC package uses the existence of on-disk revision control master
-files to determine if a given file is under revision control. These file
-tests happen on the remote machine through the standard @value{tramp} mechanisms.
-
-
-@node Remote Commands
-@section Executing the version control commands on the remote machine
-
-There are no hooks provided by VC to allow intercepting of the version
-control command execution. The calls occur through the
-@code{call-process} mechanism, a function that is somewhat more
-efficient than the @code{shell-command} function but that does not
-provide hooks for remote execution of commands.
-
-To work around this, the functions @code{vc-do-command} and
-@code{vc-simple-command} have been advised to intercept requests for
-operations on files accessed via @value{tramp}.
-
-In the case of a remote file, the @code{shell-command} interface is
-used, with some wrapper code, to provide the same functionality on the
-remote machine as would be seen on the local machine.
-
-
-@node Changed workfiles
-@section Detecting if the working file has changed
-
-As there is currently no way to get access to the mtime of a file on a
-remote machine in a portable way, the @code{vc-workfile-unchanged-p}
-function is advised to call an @value{tramp} specific function for remote files.
-
-The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
-diff functionality to determine if any changes have occurred between the
-workfile and the version control master.
-
-This requires that a shell command be executed remotely, a process that
-is notably heavier-weight than the mtime comparison used for local
-files. Unfortunately, unless a portable solution to the issue is found,
-this will remain the cost of remote version control.
-
-
-@node Checking out files
-@section Bringing the workfile out of the repository
-
-VC will, by default, check for remote files and refuse to act on them
-when checking out files from the repository. To work around this
-problem, the function @code{vc-checkout} knows about @value{tramp} files and
-allows version control to occur.
-
-
-@node Miscellaneous Version Control
-@section Things related to Version Control that don't fit elsewhere
-
-Minor implementation details, &c.
-
-@menu
-* Remote File Ownership:: How VC determines who owns a workfile.
-* Back-end Versions:: How VC determines what release your RCS is.
-@end menu
-
-
-@node Remote File Ownership
-@subsection How VC determines who owns a workfile
-
-@value{emacsname} provides the @code{user-login-name} function to
-return the login name of the current user as well as mapping from
-arbitrary user id values back to login names. The VC code uses this
-functionality to map from the uid of the owner of a workfile to the
-login name in some circumstances.
-
-This will not, for obvious reasons, work if the remote system has a
-different set of logins. As such, it is necessary to delegate to the
-remote machine the job of determining the login name associated with a
-uid.
-
-Unfortunately, with the profusion of distributed management systems such
-as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
-reliable and portable method for performing this mapping.
-
-Thankfully, the only place in the VC code that depends on the mapping of
-a uid to a login name is the @code{vc-file-owner} function. This returns
-the login of the owner of the file as a string.
-
-This function has been advised to use the output of @command{ls} on the
-remote machine to determine the login name, delegating the problem of
-mapping the uid to the login to the remote system which should know more
-about it than I do.
-
-
-@node Back-end Versions
-@subsection How VC determines what release your RCS is
-
-VC needs to know what release your revision control binaries you are
-running as not all features VC supports are available with older
-versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
-
-The default implementation of VC determines this value the first time it
-is needed and then stores the value globally to avoid the overhead of
-executing a process and parsing its output each time the information is
-needed.
-
-Unfortunately, life is not quite so easy when remote version control
-comes into the picture. Each remote machine may have a different version
-of the version control tools and, while this is painful, we need to
-ensure that unavailable features are not used remotely.
-
-To resolve this issue, @value{tramp} currently takes the sledgehammer
-approach of making the release values of the revision control tools
-local to each @value{tramp} buffer, forcing VC to determine these values
-again each time a new file is visited.
-
-This has, quite obviously, some performance implications. Thankfully,
-most of the common operations performed by VC do not actually require
-that the remote version be known. This makes the problem far less
-apparent.
-
-Eventually these values will be captured by @value{tramp} on a system by
-system basis and the results cached to improve performance.
-
-
@node Files directories and localnames
@chapter How file names, directories and localnames are mangled and managed.
@ifset emacs
@node External packages
@section Integration with external Lisp packages.
+@subsection Filename completion.
While reading filenames in the minibuffer, @value{tramp} must decide
whether it completes possible incomplete filenames, or not. Imagine
External packages, which use other characters for completing filenames
in the minibuffer, must signal this to @value{tramp}. For this case,
the variable @code{tramp-completion-mode} can be bound temporarily to
-a non-nil value.
+a non-@code{nil} value.
@lisp
(let ((tramp-completion-mode t))
...)
@end lisp
+
+
+@subsection File attributes cache.
+
+When @value{tramp} runs remote processes, files on the remote host
+could change their attributes. Consequently, @value{tramp} must flush
+its complete cache keeping attributes for all files of the remote host
+it has seen so far.
+
+This is a performance degradation, because the lost file attributes
+must be recomputed when needed again. In cases the caller of
+@code{process-file} knows that there are no file attribute changes, it
+shall let-bind the variable @code{process-file-side-effects} to
+@code{nil}. @value{tramp} wouldn't flush the file attributes cache then.
+
+@lisp
+(let (process-file-side-effects)
+ ...)
+@end lisp
+
+For asynchronous processes, @value{tramp} flushes the file attributes
+cache via a process sentinel. If the caller of
+@code{start-file-process} knows that there are no file attribute
+changes, it shall set the process sentinel to @code{nil}. In case the
+caller defines an own process sentinel, @value{tramp}'s process
+sentinel is overwritten. The caller can still flush the file
+attributes cache in its process sentinel with this code:
+
+@lisp
+(unless (memq (process-status proc) '(run open))
+ (dired-uncache remote-directory))
+@end lisp
+
+@code{remote-directory} shall be the root directory, where file
+attribute changes can happen during the process lifetime.
+@value{tramp} traverses all subdirectories, starting at this
+directory. Often, it is sufficient to use @code{default-directory} of
+the process buffer as root directory.
@end ifset
@*@indent @w{ 6} sent and received strings
@*@indent @w{ 7} file caching
@*@indent @w{ 8} connection properties
+@*@indent @w{ 9} test commands
@*@indent @w{10} traces (huge)
When @code{tramp-verbose} is greater than or equal to 4, the messages
are also written into a @value{tramp} debug buffer. This debug buffer
-is useful for analysing problems; sending a @value{tramp} bug report
+is useful for analyzing problems; sending a @value{tramp} bug report
should be done with @code{tramp-verbose} set to a verbosity level of at
least 6 (@pxref{Bug Reports}).
But I have decided that this is too fragile to reliably work, so on some
systems you'll have to do without the uuencode methods.
-@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
+@item The @value{tramp} filename syntax differs between Emacs and XEmacs.
-The GNU Emacs maintainers wish to use a unified filename syntax for
+The Emacs maintainers wish to use a unified filename syntax for
Ange-FTP and @value{tramp} so that users don't have to learn a new
syntax. It is sufficient to learn some extensions to the old syntax.
@unnumbered Concept Index
@printindex cp
-@contents
-@c End of tramp.texi - the TRAMP User Manual
@bye
@c TODO
@c shells.
@c * Explain how tramp.el works in principle: open a shell on a remote
@c host and then send commands to it.
-@c * Make terminology "inline" vs "out-of-band" consistent.
-@c It seems that "external" is also used instead of "out-of-band".
-
-@c * M. Albinus
-@c ** Use `filename' resp. `file name' consistently.
-@c ** Use `host' resp. `machine' consistently.
-@c ** Consistent small or capitalized words especially in menues.
-
-@ignore
- arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
-@end ignore
+@c * Use `filename' resp. `file name' consistently.
+@c * Use `host' resp. `machine' consistently.
+@c * Consistent small or capitalized words especially in menus.
HCoop / bpt / emacs.git / blobdiff