\userhost\@value{postfix}\localname\
@end macro
-@c Similar, but without a method prefix.
-
-@macro trampf {userhost, localname}
-@value{prefix}@c
-\userhost\@value{postfix}\localname\
-@end macro
-
@copying
Copyright @copyright{} 1999--2017 Free Software Foundation, Inc.
Installing @value{tramp} with your Emacs
* Installation parameters:: Parameters in order to control installation.
+* Testing:: A test suite for @value{tramp}.
* Load paths:: How to plug-in @value{tramp} into your environment.
-
@end ifset
Configuring @value{tramp} for use
@value{tramp} development started at the end of November 1998 as
@file{rssh.el}. It provided only one method of access. It used
@command{ssh} for login and @command{scp} to transfer file contents.
-The name was changed to @file{rcp.el} before it got its preset name
+The name was changed to @file{rcp.el} before it got its present name
@value{tramp}. New methods of remote access were added, so was support
for version control.
April 2000 was the first time when multi-hop methods were added. In
-July 2002, @value{tramp} unified file names with Ange-FTP@. In July
+July 2002, @value{tramp} unified file names with Ange FTP@. In July
2004, proxy hosts replaced multi-hop methods. Running commands on
remote hosts was introduced in December 2005. Support for gateways
since April 2007 (and removed in December 2016). GVFS integration
re-enabled in November 2011. In November 2012, added Juergen
Hoetzel's @file{tramp-adb.el}.
-XEmacs support has been stopped in January 2016.
+XEmacs support has been stopped in January 2016. Since March 2017,
+@value{tramp} syntax requires a method mandatorily.
@c Installation chapter is necessary only in case of standalone
@c installation. Text taken from trampinst.texi.
@value{tramp} is initially configured to use the @command{scp} program
to connect to the remote host. Just type @kbd{C-x C-f} and then enter
-file name @file{@trampf{user@@host,/path/to/file}}. For details,
+file name @file{@trampfn{scp,user@@host,/path/to/file}}. For details,
@xref{Default Method}, @xref{Default User}, @xref{Default Host}.
For problems related to the behavior of the remote shell, @xref{Remote
The first directory in the localname must be a share name on the
remote host.
-Since SMB shares end in the @code{$} character, @value{tramp} must use
-@code{$$} when specifying those shares to avoid environment variable
-substitutions.
+Since some SMB share names end in the @code{$} character,
+@value{tramp} must use @code{$$} when specifying those shares to avoid
+environment variable substitutions.
When @value{tramp} is not specific about the share name or uses the
generic remote directory @file{/}, @command{smbclient} returns all
To accommodate user name/domain name syntax required by MS Windows
authorization, @value{tramp} provides for an extended syntax in
-@code{user%domain} format (where user is username, @code{%} is the
+@code{user%domain} format (where user is user name, @code{%} is the
percent symbol, and domain is the windows domain name). An example:
@example
@section Selecting a default method
@cindex default method
+In a remote file name, the use of a default method is indicated by the
+pseudo method @option{-}, @ref{File name Syntax}.
+
@defopt tramp-default-method
Default method is for transferring files. The user option
@option{tramp-default-method} sets it. @value{tramp} uses this user
@defopt tramp-default-host
When host name is omitted, @value{tramp} substitutes the value from
the @option{tramp-default-host} user option. It is initially
-populated with the local hostname where Emacs is running. Both the
-default user and default host can be overridden as follows:
+populated with the local host name where Emacs is running. The
+default method, default user and default host can be overridden as
+follows:
@lisp
@group
(custom-set-variables
+ '(tramp-default-method "ssh" nil (tramp))
'(tramp-default-user "john" nil (tramp))
'(tramp-default-host "target" nil (tramp)))
@end group
@end lisp
-With both defaults set, @samp{@trampfn{ssh,,}} will connect
-@value{tramp} to John's home directory on @code{target}.
-
-@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
-for quoted file names.
-@ifinfo
-@pxref{Quoted File Names, , , emacs}.
-@end ifinfo
+With all defaults set, @samp{@trampfn{-,,}} will connect @value{tramp}
+to John's home directory on @code{target} via @code{ssh}.
@end defopt
@defopt tramp-default-host-alist
Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects
to @samp{randomhost.your.domain} via @code{ssh} under your account
-name, and then perform @code{sudo -u root} on that host.
+name, and then performs @code{sudo -u root} on that host.
It is key for the sudo method in the above example to be applied on
the host after reaching it and not on the local host.
@cindex file name syntax
@cindex file name examples
-@file{@trampf{host,localfilename}} opens file @var{localfilename} on
-the remote host @var{host}, using the default method. @xref{Default
-Method}.
+@file{@trampfn{method,host,/path/to/file}} opens file @var{/path/to/file}
+on the remote host @var{host}, using the method @var{method}.
@table @file
-@item @value{prefix}melancholia@value{postfix}.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}.emacs
For the file @file{.emacs} located in the home directory, on the host
-@code{melancholia}.
+@code{melancholia}, using method @code{ssh}.
-@item @value{prefix}melancholia.danann.net@value{postfix}.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia.danann.net@value{postfix}.emacs
For the file @file{.emacs} specified using the fully qualified domain name of
the host.
-@item @value{prefix}melancholia@value{postfix}~/.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}~/.emacs
For the file @file{.emacs} specified using the @file{~}, which is expanded.
-@item @value{prefix}melancholia@value{postfix}~daniel/.emacs
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}~daniel/.emacs
For the file @file{.emacs} located in @code{daniel}'s home directory
on the host, @code{melancholia}. The @file{~<user>} construct is
expanded to the home directory of that user on the remote host.
-@item @value{prefix}melancholia@value{postfix}/etc/squid.conf
+@item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}/etc/squid.conf
For the file @file{/etc/squid.conf} on the host @code{melancholia}.
@end table
@var{host} can take IPv4 or IPv6 address, as in
-@file{@trampf{127.0.0.1,.emacs}} or
-@file{@trampf{@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}.
+@file{@trampfn{ssh,127.0.0.1,.emacs}} or
+@file{@trampfn{ssh,@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}.
@ifset unified
For syntactical reasons, IPv6 addresses must be embedded in square
brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
name using the proper syntax will override this default behavior:
@example
-@trampf{user@@host,path/to/file}
+@trampfn{method,user@@host,path/to/file}
@end example
-@file{@trampf{daniel@@melancholia,.emacs}} is for file @file{.emacs}
-in @code{daniel}'s home directory on the host, @code{melancholia}.
-
-Specify other file access methods (@pxref{Inline methods},
-@pxref{External methods}) as part of the file name.
-
-Method name comes before user name, as in
-@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing
-colon). The syntax specifications for user, host, and file do not
-change.
-
-To connect to the host @code{melancholia} as @code{daniel}, using
-@option{ssh} method for @file{.emacs} in @code{daniel}'s home
-directory, the full specification is:
-@file{@trampfn{ssh,daniel@@melancholia,.emacs}}.
-
-A remote file name containing a host name, which is the same string as
-a method name, is not allowed.
+@file{@trampfn{ssh,daniel@@melancholia,.emacs}} is for file
+@file{.emacs} in @code{daniel}'s home directory on the host,
+@code{melancholia}, accessing via method @code{ssh}.
For specifying port numbers, affix @file{#<port>} to the host
name. For example: @file{@trampfn{ssh,daniel@@melancholia#42,.emacs}}.
+All method, user name, host name, port number and local name parts are
+optional, @xref{Default Method}, @xref{Default User}, @xref{Default Host}.
+@ifset unified
+For syntactical reasons, the default method must be indicated by the
+pseudo method @file{-}.
+@end ifset
+
@node File name completion
@section File name completion
@xref{Completion Options, , , emacs}.
@end ifinfo
-For example, type @kbd{C-x C-f @value{prefix}t @key{TAB}},
+For example, type @kbd{C-x C-f @value{prefix}s @key{TAB}},
@value{tramp} completion choices show up as
@example
@group
-@c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}}
-@multitable @columnfractions .5 .5
-@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/
-@item @value{prefixhop}toto@value{postfix} @tab
+@multitable @columnfractions .2 .2 .2 .2 .2
+@item @c
+ sbin/ @tab @c
+ @value{prefixhop}scp@value{postfix} @tab @c
+ @value{prefixhop}scpx@value{postfix} @tab @c
+ @value{prefixhop}sftp@value{postfix} @tab @c
+ @value{prefixhop}sg@value{postfix}
+@item @c
+ @value{prefixhop}smb@value{postfix} @tab @c
+ srv/ @tab @c
+ @value{prefixhop}ssh@value{postfix} @tab @c
+ @value{prefixhop}sshx@value{postfix} @tab @c
+ @value{prefixhop}su@value{postfix}
+@item @c
+ @value{prefixhop}sudo@value{postfix} @tab @c
+ sys/
@end multitable
@end group
@end example
-@samp{@value{prefixhop}telnet@value{postfixhop}} is a possible
-completion for the respective method, @samp{tmp/} stands for the
-directory @file{/tmp} on your local host, and
-@samp{@value{prefixhop}toto@value{postfix}} might be a host
-@value{tramp} has detected in your @file{~/.ssh/known_hosts} file
-(when using @option{ssh} as default method).
+@samp{@value{prefixhop}ssh@value{postfixhop}} is a possible
+completion for the respective method, and @samp{sbin/} stands for the
+directory @file{/sbin} on your local host.
-Type @kbd{e @key{TAB}} for the minibuffer completion to
-@samp{@value{prefix}telnet@value{postfixhop}}. Typing @kbd{@key{TAB}}
-shows host names @value{tramp} from @file{/etc/hosts} file, for example.
+Type @kbd{s h @value{postfixhop}} for the minibuffer completion to
+@samp{@value{prefix}ssh@value{postfixhop}}. Typing @kbd{@key{TAB}}
+shows host names @value{tramp} extracts from @file{~/.ssh/config}
+file, for example.
@example
@group
@multitable @columnfractions .5 .5
-@c @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,}
-@c @item @trampfn{telnet,@value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet,localhost,}
-@item @value{prefix}telnet@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @trampfn{telnet,localhost,}
-@item @trampfn{telnet,melancholia.danann.net,} @tab @trampfn{telnet,melancholia,}
+@item @c
+ @value{prefixhop}ssh@value{postfixhop}127.0.0.1@value{postfix} @tab @c
+ @value{prefixhop}ssh@value{postfixhop}192.168.0.1@value{postfix}
+@item @c
+ @value{prefixhop}ssh@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @c
+ @value{prefixhop}ssh@value{postfixhop}localhost@value{postfix}
+@item @c
+ @value{prefixhop}ssh@value{postfixhop}melancholia.danann.net@value{postfix} @tab @c
+ @value{prefixhop}ssh@value{postfixhop}melancholia@value{postfix}
@end multitable
@end group
@end example
@example
@group
-@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}}
- @print{} @trampfn{telnet,melancholia,/etc}
+@kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin//etc} @key{TAB}}
+ @print{} @trampfn{ssh,melancholia,/etc}
-@kbd{C-x C-f @trampfn{telnet,melancholia,//etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{ssh,melancholia,//etc} @key{TAB}}
@print{} /etc
-@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin///etc} @key{TAB}}
@print{} /etc
@end group
@end example
@value{tramp} is integrated into @file{eshell.el}, which enables
interactive eshell sessions on remote hosts at the command prompt.
-You must add the module @code{eshell-tramp} to
-@code{eshell-modules-list}. Here's a sample interaction after opening
-@kbd{M-x eshell} on a remote host:
+You must add the module @code{em-tramp} to @code{eshell-modules-list}.
+Here's a sample interaction after opening @kbd{M-x eshell} on a remote
+host:
@example
@group
@end group
@end lisp
-The reduced typing: @kbd{C-x C-f @trampf{news.my.domain,/opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampfn{-,news.my.domain,/opt/news/etc}}.
@strong{Note} that there are some useful shortcuts already. Accessing
your local host as @samp{root} user, is possible just by @kbd{C-x C-f
@section Integrating with external Lisp packages
@subsection File name completion.
-For name completions in the minibuffer, @value{tramp} depends on the
-last input character to decide whether to look for method name
-completion or host name completion. For example, @kbd{C-x C-f
-@value{prefix}ssh@value{postfixhop} @key{TAB}} is not entirely clear
-if @option{ssh} is a method or a host name. But if the last input
-character was either @key{TAB}, @key{SPACE} or @kbd{?}, then
-@value{tramp} favors file name completion over host name completion.
-
-What about external packages using other characters to trigger file
-name completions? They must somehow signal this to @value{tramp}. Use
-the variable @code{non-essential} temporarily and bind it to
-non-@code{nil} value.
+Sometimes, it is not convenient to open a new connection to a remote
+host, including entering the password and alike. For example, this is
+nasty for packages providing file name completion. Such a package
+could signal to @value{tramp}, that they don't want it to establish a
+new connection. Use the variable @code{non-essential} temporarily and
+bind it to non-@code{nil} value.
@lisp
@group
projects / emacs.git / commitdiff