@include trampver.texi
@c Macro for formatting a file name according to the respective syntax.
-@c xxx and yyy are auxiliary macros in order to omit leading and
+@c Macro arguments should not have any leading or
@c trailing whitespace. Not very elegant, but I don't know it better.
-@c There are subtle differences between texinfo 4.13 and 5.0. We must
-@c declare two versions of the macro. This will be improved, hopefully.
-
-@c Texinfo 5.0.
-@ifset txicommandconditionals
-@macro xxx {one}
-@set \one\
-@end macro
-
-@macro yyy {one, two}
-@xxx{x\one\}@c
-@ifclear x
-\one\@w{}\two\@c
-@end ifclear
-@clear x\one\
-@end macro
-
-@macro trampfn {method, user, host, localname}
+@macro trampfn {method, userhost, localname}
@value{prefix}@c
-@yyy{\method\,@value{postfixhop}}@c
-@yyy{\user\,@@}@c
-\host\@value{postfix}\localname\
+\method\@value{postfixhop}@c
+\userhost\@value{postfix}\localname\
@end macro
-@end ifset
-@c Texinfo 4.13.
-@ifclear txicommandconditionals
-@macro xxx {one}@c
-@set \one\@c
-@end macro
+@c Similar, but without a method prefix.
-@macro yyy {one, two}@c
-@xxx{x\one\}@c
-@ifclear x@c
-\one\@w{}\two\@c
-@end ifclear
-@clear x\one\@c
-@end macro
-
-@macro trampfn {method, user, host, localname}@c
-@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
+@macro trampf {userhost, localname}
+@value{prefix}@c
+\userhost\@value{postfix}\localname\
@end macro
-@end ifclear
@copying
Copyright @copyright{} 1999--2016 Free Software Foundation, Inc.
@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{@trampfn{, user, host, /path/to.file}}. For details,
+file name @file{@trampf{user@@host,/path/to.file}}. For details,
see @xref{Default Method}.
For problems related to the behavior of remote shell, see @ref{Remote
percent symbol, and domain is the windows domain name). An example:
@example
-@trampfn{smb, daniel%BIZARRE, melancholia, /daniel$$/.emacs}
+@trampfn{smb,daniel%BIZARRE@@melancholia,/daniel$$/.emacs}
@end example
where user @code{daniel} connects as a domain user to the SMB host
UPPERCASE as shown here:
@example
-@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}
+@trampfn{smb,daniel%MELANCHOLIA@@melancholia,/daniel$$/.emacs}
@end example
where user @code{daniel} connects as local user to the SMB host
@value{tramp} does not require a host name part of the remote file
name when a single Android device is connected to @command{adb}.
-@value{tramp} instead uses @file{@trampfn{adb, , ,}} as the default
+@value{tramp} instead uses @file{@trampfn{adb,,}} as the default
name. @command{adb devices} shows available host names.
@option{adb} method normally does not need user name to authenticate
This method is for connecting to remote hosts with the Apple Filing
Protocol for accessing files on Mac OS X volumes. @value{tramp} access
syntax requires a leading volume (share) name, for example:
-@file{@trampfn{afp, user, host, /volume}}.
+@file{@trampfn{afp,user@@host,/volume}}.
@item @option{dav}
@item @option{davs}
@file{/etc/motd} file on the otherhost:
@example
-@kbd{C-x C-f @trampfn{ssh, root, otherhost,/etc/motd} @key{RET}}
+@kbd{C-x C-f @trampfn{ssh,root@@otherhost,/etc/motd} @key{RET}}
@end example
If @option{ssh} is unavailable for whatever reason, look for other
the shortened syntax of @samp{root}:
@example
-@kbd{C-x C-f @trampfn{su, , , /etc/motd} @key{RET}}
+@kbd{C-x C-f @trampfn{su,,/etc/motd} @key{RET}}
@end example
For editing large files, @option{scp} is faster than @option{ssh}.
tramp-default-host "target")
@end lisp
-With both defaults set, @samp{@trampfn{ssh, , ,}} will connect
+With both defaults set, @samp{@trampfn{ssh,,}} will connect
@value{tramp} to John's home directory on target.
@strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix
@lisp
(add-to-list 'tramp-default-proxies-alist
- '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
+ '("\\." nil "@trampfn{ssh,bird@@bastion.your.domain,}"))
(add-to-list 'tramp-default-proxies-alist
'("\\.your\\.domain\\'" nil nil))
@end lisp
(add-to-list 'tramp-default-proxies-alist
'("\\`bastion\\.your\\.domain\\'"
"\\`bird\\'"
- "@trampfn{ssh, , jump.your.domain,}"))
+ "@trampfn{ssh,jump.your.domain,}"))
@end lisp
@var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or
@lisp
(add-to-list 'tramp-default-proxies-alist
- '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
+ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh,%h,}"))
@end lisp
-Opening @file{@trampfn{sudo, , randomhost.your.domain,}} first
+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.
@lisp
(add-to-list 'tramp-default-proxies-alist
- '(nil "\\`root\\'" "@trampfn{ssh, , %h,}"))
+ '(nil "\\`root\\'" "@trampfn{ssh,%h,}"))
(add-to-list 'tramp-default-proxies-alist
'((regexp-quote (system-name)) nil nil))
@end lisp
@lisp
(add-to-list 'tramp-default-proxies-alist
'("\\`host\\.other\\.domain\\'" nil
- "@trampfn{tunnel, , proxy.your.domain#3128,}"))
+ "@trampfn{tunnel,proxy.your.domain#3128,}"))
@end lisp
Gateway methods in a multiple hop chain can be declared only as the first hop.
information. For example, connecting to a host using @command{ssh} and
connecting to the same host through @code{sshd} on port 3001. Both
access methods result in nearly identical persistent specifications
-@file{@trampfn{ssh, , localhost,}} and @file{@trampfn{ssh, ,
-localhost#3001,}}.
+@file{@trampfn{ssh,localhost,}} and @file{@trampfn{ssh,localhost#3001,}}.
Changing host names could avoid duplicates. One way is to add a
@option{Host} section in @file{~/.ssh/config} (@pxref{Frequently Asked
@lisp
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell" "/bin/ksh"))
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"remote-shell-login" '("-")))
@end lisp
@lisp
(add-to-list 'tramp-connection-properties
- (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}")
+ (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}")
"busybox" t))
@end lisp
@end lisp
@noindent
-Open a remote connection with the command @kbd{C-x C-f @trampfn{ssh, ,
-192.168.0.26#2222, }}, where @command{sshd} is listening on port
+Open a remote connection with the command @kbd{C-x C-f
+@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening on port
@samp{2222}.
To add a corresponding entry to the @file{~/.ssh/config} file
@noindent
Open a remote connection with a more concise command @kbd{C-x C-f
-@trampfn{ssh, , android, }}.
+@trampfn{ssh,android,}}.
@node Auto-save and Backup
files unless changed to another location, such as
@file{~/.emacs.d/backups/}. Such a directory will also be used by
default by @value{tramp} when using, say, a restricted file
-@file{@trampfn{su, root, localhost, /etc/secretfile}}. The backup
+@file{@trampfn{su,root@@localhost,/etc/secretfile}}. The backup
file of the secretfile is now owned by the user logged in from tramp
and not root.
@end lisp
@noindent
-The backup file name of @file{@trampfn{su, root, localhost,
-/etc/secretfile}} would be @file{@trampfn{su, root, localhost,
-~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
+The backup file name of
+@file{@trampfn{su,root@@localhost,/etc/secretfile}} would be
+@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}.
Just as for backup files, similar issues of file naming affect
auto-saving @value{tramp} files. Auto-saved files are saved in the
@cindex file name syntax
@cindex file name examples
-@file{@trampfn{, , host, localfilename}}
+@file{@trampf{host,localfilename}}
opens file @var{localfilename} on the remote host @var{host}, using
the default method. @xref{Default Method}.
@end table
-@var{host} can take IPv4 or IPv6 address, as in @file{@trampfn{, ,
-127.0.0.1, .emacs}} or @file{@trampfn{, ,
-@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. For syntactical
-reasons, IPv6 addresses must be embedded in square brackets
-@file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
+@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}}.
+For syntactical reasons, IPv6 addresses must be embedded in square
+brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}.
By default, @value{tramp} will use the current local user name as the
remote user name for log in to the remote host. Specifying a different
name using the proper syntax will override this default behavior:
@example
-@trampfn{, user, host, path/to.file}
+@trampf{user@@host,path/to.file}
@end example
-@file{@trampfn{, daniel, melancholia, .emacs}} is for file
+@file{@trampf{daniel@@melancholia,.emacs}} is for file
@file{.emacs} in @code{daniel}'s home directory on the host,
@code{melancholia}.
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}}.
+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.
For specifying port numbers, affix @file{#<port>} to the host
-name. For example: @file{@trampfn{ssh, daniel, melancholia#42,
-.emacs}}.
+name. For example: @file{@trampfn{ssh,daniel@@melancholia#42,.emacs}}.
@node File name completion
@value{tramp} completion choices show up as
@example
-@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}}
+@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
@example
@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,}
-@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,}
-@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,}
+@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,}
@end multitable
@end example
Example:
@example
-@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{telnet,melancholia,/usr/local/bin//etc} @key{TAB}}
+ @print{} @trampfn{telnet,melancholia,/etc}
-@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}}
+@kbd{C-x C-f @trampfn{telnet,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{telnet,melancholia,/usr/local/bin///etc} @key{TAB}}
@print{} /etc
@end example
proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}:
@example
-@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh, you,
-@c remotehost, /path}}
+@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path}}
@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path}
@end example
@value{tramp} adds the ad-hoc definitions on the fly to
@code{tramp-default-proxies-alist} and is available for re-use during
that Emacs session. Subsequent @value{tramp} connections to the same
-remote host can then use the shortcut form: @samp{@trampfn{ssh, you,
-remotehost, /path}}.
+remote host can then use the shortcut form:
+@samp{@trampfn{ssh,you@@remotehost,/path}}.
@defopt tramp-save-ad-hoc-proxies
@vindex tramp-save-ad-hoc-proxies
host. Example:
@example
-@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}}
+@kbd{C-x C-f @trampfn{sudo,,} @key{RET}}
@kbd{M-! tail -f /var/log/syslog.log & @key{RET}}
@end example
@kbd{M-x eshell} on a remote host:
@example
-@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
-@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
+@b{~ $} cd @trampfn{sudo,,/etc} @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} hostname @key{RET}
host
-@b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} id @key{RET}
uid=0(root) gid=0(root) groups=0(root)
-@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
+@b{@trampfn{sudo,root@@host,/etc} $} find-file shadow @key{RET}
#<buffer shadow>
-@b{@trampfn{sudo, root, host, /etc} $}
+@b{@trampfn{sudo,root@@host,/etc} $}
@end example
@code{eshell} in Emacs 23.2 added custom @code{su} and @code{sudo}
(@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}
+@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}
+@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} $}
+@b{@trampfn{su,root@@remotehost,/root} $}
@end example
@example
@kbd{M-x gdb @key{RET}}
-@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
+@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh,host,~/myprog} @key{RET}
@end example
Relative file names are based on the remote default directory. When
-@file{myprog.pl} exists in @file{@trampfn{ssh, , host, /home/user}},
+@file{myprog.pl} exists in @file{@trampfn{ssh,host,/home/user}},
valid calls include:
@example
This command flushes all connection related objects. @option{vec} is
the internal representation of a remote connection. When called
interactively, this command lists active remote connections in the
-minibuffer. Each connection is of the format @file{@trampfn{method,
-user, host, }}. Flushing remote connections also cleans the password
+minibuffer. Each connection is of the format
+@file{@trampfn{method,user@@host,}}. Flushing remote connections also
+cleans the password
cache (@pxref{Password handling}), file cache, connection cache
(@pxref{Connection caching}), and connection buffers.
@end deffn
How to shorten long file names when typing in @value{tramp}?
Adapt several of these approaches to reduce typing. If the full name
-is @file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, then:
+is @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, then:
@enumerate
tramp-default-user "news")
@end lisp
-The reduced typing: @kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampf{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
-@trampfn{su, , ,}}.
+@trampfn{su,,}}.
@item
Use configuration options of the access method:
User news
@end example
-The reduced typing: @kbd{C-x C-f @trampfn{ssh, , xy, /opt/news/etc}}.
+The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}.
Depending on the number of files in the directories, host names
completion can further reduce key strokes: @kbd{C-x C-f
inside Emacs with Lisp:
@lisp
-(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
+(setenv "xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")
@end lisp
The reduced typing: @kbd{C-x C-f $xy @key{RET}}.
(find-file
(read-file-name
"Find Tramp file: "
- "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
+ "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))))
@end lisp
Simply typing @kbd{C-x C-y} would prepare minibuffer editing of file
@lisp
(add-to-list
'directory-abbrev-alist
- '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
+ '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
@end lisp
The reduced typing: @kbd{C-x C-f /xy @key{RET}}.
@lisp
(define-abbrev-table 'my-tramp-abbrev-table
- '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
+ '(("xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")))
(add-hook
'minibuffer-setup-hook
@lisp
(eval-after-load "filecache"
'(file-cache-add-directory
- "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
+ "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
@end lisp
Then use directory completion in the minibuffer with @kbd{C-x C-f
When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc
multi-hops}) via bookmarks, recent files, filecache, bbdb, or another
package, use the full ad-hoc file name including all hops, like
-@file{@trampfn{ssh, bird, bastion|ssh@value{postfixhop}news.my.domain,
-/opt/news/etc}}.
+@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}news.my.domain,/opt/news/etc}}.
Alternatively, when saving abbreviated multi-hop file names
-@file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, the custom
+@file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the custom
option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil}
value.
Then start Emacs Client from the command line:
@example
-emacsclient @trampfn{ssh, user, host, /file/to/edit}
+emacsclient @trampfn{ssh,user@@host,/file/to/edit}
@end example
@code{user} and @code{host} refer to the local host.
@example
#!/bin/sh
-emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}
+emacsclient @trampfn{ssh,$(whoami)@@$(hostname --fqdn),$1}
@end example
Then change the environment variable @env{EDITOR} to point to the