Document remote file name syntax change
* doc/emacs/files.texi (Remote Files, Quoted File Names): * doc/misc/org.texi (dir): Change examples to use a method. * doc/misc/tramp.texi (Top) [trampf]: Remove macro. Add `Testing' menu entry. (History): Fix typos. Mention syntax change. (Configuration, Default Host, File name Syntax) (File name completion, Frequently Asked Questions): Change examples to use a method. (External methods, Default Host, Multi-hops, Remote processes): Fix typos. (Default Method): Mention pseudo method "-". (External packages): Rewrite intention of `non-essential'. * etc/NEWS: Mark recent Tramp entries as documented.
This commit is contained in:
Michael Albinus
parent
f6b995ef4e
commit
265a5d9791
4 changed files with 97 additions and 105 deletions
|
|
@ -1777,9 +1777,7 @@ syntax:
|
|||
|
||||
@example
|
||||
@group
|
||||
/@var{host}:@var{filename}
|
||||
/@var{user}@@@var{host}:@var{filename}
|
||||
/@var{user}@@@var{host}#@var{port}:@var{filename}
|
||||
/@var{method}:@var{host}:@var{filename}
|
||||
/@var{method}:@var{user}@@@var{host}:@var{filename}
|
||||
/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
|
||||
@end group
|
||||
|
|
@ -1788,11 +1786,11 @@ syntax:
|
|||
@noindent
|
||||
To carry out this request, Emacs uses a remote-login program such as
|
||||
@command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}.
|
||||
You can always specify in the file name which method to use---for
|
||||
You must always specify in the file name which method to use---for
|
||||
example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP,
|
||||
whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
|
||||
@command{ssh}. When you don't specify a method in the file name,
|
||||
Emacs chooses the method as follows:
|
||||
@command{ssh}. When you specify the pseudo method @var{-} in the file
|
||||
name, Emacs chooses the method as follows:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
|
|
@ -1884,7 +1882,7 @@ can refer to that file in Emacs as @samp{/:/foo:/bar}.
|
|||
|
||||
If you want to quote only special characters in the local part of a
|
||||
remote file name, you can quote just the local part.
|
||||
@samp{/baz:/:/foo:/bar} refers to the file @file{bar} of directory
|
||||
@samp{/ssh:baz:/:/foo:/bar} refers to the file @file{bar} of directory
|
||||
@file{/foo:} on the host @file{baz}.
|
||||
|
||||
@samp{/:} can also prevent @samp{~} from being treated as a special
|
||||
|
|
|
|||
|
|
@ -15090,7 +15090,7 @@ A directory on a remote machine can be specified using tramp file syntax, in
|
|||
which case the code will be evaluated on the remote machine. An example is
|
||||
|
||||
@example
|
||||
#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
|
||||
#+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
|
||||
plot(1:10, main=system("hostname", intern=TRUE))
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
|
|
|||
|
|
@ -24,13 +24,6 @@
|
|||
\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.
|
||||
|
||||
|
|
@ -133,8 +126,8 @@ For the developer:
|
|||
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
|
||||
|
|
@ -398,12 +391,12 @@ Run @command{autoconf} as follows to generate an up-to-date
|
|||
@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
|
||||
|
|
@ -412,7 +405,8 @@ September 2011. Ad-hoc multi-hop methods (with a changed syntax)
|
|||
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.
|
||||
|
|
@ -428,7 +422,7 @@ XEmacs support has been stopped in January 2016.
|
|||
|
||||
@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
|
||||
|
|
@ -819,9 +813,9 @@ Using @command{smbclient} requires a few tweaks when working with
|
|||
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
|
||||
|
|
@ -834,7 +828,7 @@ handling}.
|
|||
|
||||
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
|
||||
|
|
@ -1002,6 +996,9 @@ Other methods to include are: @option{ftp} and @option{smb}.
|
|||
@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
|
||||
|
|
@ -1145,25 +1142,21 @@ for catch-all or most often used login.
|
|||
@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
|
||||
|
|
@ -1248,7 +1241,7 @@ access, then use this alist entry:
|
|||
|
||||
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.
|
||||
|
|
@ -2151,35 +2144,34 @@ is a feature of Emacs that may cause missed prompts when using
|
|||
@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}}.
|
||||
|
|
@ -2190,31 +2182,23 @@ remote user name for log in to the remote host. Specifying a different
|
|||
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
|
||||
|
|
@ -2228,38 +2212,52 @@ in @file{.emacs}.
|
|||
@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
|
||||
|
|
@ -2288,13 +2286,13 @@ 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
|
||||
|
|
@ -2527,9 +2525,9 @@ host. 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
|
||||
|
|
@ -3113,7 +3111,7 @@ You can define default methods and user names for hosts,
|
|||
@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
|
||||
|
|
@ -3472,18 +3470,12 @@ handlers.
|
|||
@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
|
||||
|
|
|
|||
4
etc/NEWS
4
etc/NEWS
|
|
@ -634,10 +634,12 @@ header's value.
|
|||
|
||||
** Tramp
|
||||
|
||||
+++
|
||||
*** The method part of remote file names is mandatory now. A valid
|
||||
remote file name starts with "/method:host:" or "/method:user@host:".
|
||||
|
||||
*** The new virtual method "-" is a marker for the default method.
|
||||
+++
|
||||
*** The new pseudo method "-" is a marker for the default method.
|
||||
"/-::" is the shortest remote file name then.
|
||||
|
||||
+++
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue