8 |
@c This is *so* much nicer :) |
@c This is *so* much nicer :) |
9 |
@footnotestyle end |
@footnotestyle end |
10 |
|
|
11 |
|
@c In the Tramp CVS, the version number is auto-frobbed from the |
12 |
|
@c Makefile, so you should edit the top-level Makefile to change |
13 |
|
@c the version number. |
14 |
|
@macro trampver{} |
15 |
|
2.0.20 |
16 |
|
@end macro |
17 |
|
|
18 |
@c Entries for @command{install-info} to use |
@c Entries for @command{install-info} to use |
19 |
@dircategory Emacs |
@dircategory Emacs |
27 |
@sc{tramp} |
@sc{tramp} |
28 |
@end macro |
@end macro |
29 |
|
|
30 |
@c Copying permissions, et al |
@c Distinguish between GNU Emacs and XEmacs. Derived from the |
31 |
@copying |
@c Makefile variable $(EMACS-ID). Valid values are `emacs' and `xemacs'. |
32 |
This file documents @tramp{}, a remote file editing package for Emacs and |
@set emacs |
33 |
XEmacs. |
|
34 |
|
@c Some flags which make the text independent on the (X)Emacs flavor. |
35 |
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software |
@c GNU Emacs values. |
36 |
Foundation, Inc. |
@ifset emacs |
37 |
|
@set emacs-name Emacs |
38 |
@quotation |
@set emacs-dir emacs |
39 |
Permission is granted to copy, distribute and/or modify this document |
@set ftp-package-name Ange-FTP |
40 |
under the terms of the GNU Free Documentation License, Version 1.1 or |
@set tramp-prefix / |
41 |
any later version published by the Free Software Foundation; with no |
@set tramp-prefix-single-hop |
42 |
Invariant Sections, with the Front-Cover texts being ``A GNU |
@set tramp-postfix : |
43 |
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
@set tramp-postfix-single-hop : |
44 |
license is included in the section entitled ``GNU Free Documentation |
@set tramp-postfix-multi-hop : |
45 |
License'' in the Emacs manual. |
@end ifset |
46 |
|
|
47 |
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
@c XEmacs counterparts. |
48 |
this GNU Manual, like GNU software. Copies published by the Free |
@ifset xemacs |
49 |
Software Foundation raise funds for GNU development.'' |
@set emacs-name XEmacs |
50 |
|
@set emacs-dir xemacs |
51 |
This document is part of a collection distributed under the GNU Free |
@set ftp-package-name EFS |
52 |
Documentation License. If you want to distribute this document |
@set tramp-prefix /[ |
53 |
separately from the collection, you can do so by adding a copy of the |
@set tramp-prefix-single-hop [ |
54 |
license to the document, as described in section 6 of the license. |
@set tramp-postfix ] |
55 |
@end quotation |
@set tramp-postfix-single-hop / |
56 |
@end copying |
@set tramp-postfix-multi-hop : |
57 |
|
@end ifset |
58 |
|
|
59 |
|
@c Macros for formatting a filename. |
60 |
|
@c trampfn is for a full filename, trampfnmhp means method, host, path |
61 |
|
@c were given, and so on. |
62 |
|
@macro trampfn(method, user, host, path) |
63 |
|
@value{tramp-prefix}@value{method}@value{user}@@@value{host}@value{tramp-postfix}@value{path} |
64 |
|
@end macro |
65 |
|
|
66 |
@tex |
@tex |
67 |
|
|
68 |
@titlepage |
@titlepage |
69 |
@title @tramp{} User Manual |
@title @tramp{} version @trampver{} User Manual |
70 |
|
|
71 |
@author by Daniel Pittman |
@author by Daniel Pittman |
72 |
@author based on documentation by Kai Gro@ss{}johann |
@author based on documentation by Kai Gro@ss{}johann |
79 |
|
|
80 |
@ifnottex |
@ifnottex |
81 |
@node Top, Overview, (dir), (dir) |
@node Top, Overview, (dir), (dir) |
82 |
@top @tramp{} User Manual |
@top @tramp{} version @trampver{} User Manual |
83 |
|
|
84 |
|
This file documents @tramp{} version @trampver{}, a remote file |
85 |
|
editing package for @value{emacs-name}. |
86 |
|
|
87 |
@tramp{} stands for `Transparent Remote (file) Access, Multiple |
@tramp{} stands for `Transparent Remote (file) Access, Multiple |
88 |
Protocol'. This package provides remote file editing, similar to |
Protocol'. This package provides remote file editing, similar to |
89 |
@cite{Ange-FTP} and @cite{EFS}. |
@value{ftp-package-name}. |
90 |
|
|
91 |
The difference is that Ange-FTP uses FTP to transfer files between the |
The difference is that @value{ftp-package-name} uses FTP to transfer |
92 |
local and the remote host, whereas @tramp{} uses a combination of |
files between the local and the remote host, whereas @tramp{} uses a |
93 |
@command{rsh} and @command{rcp} or other work-alike programs, such as |
combination of @command{rsh} and @command{rcp} or other work-alike |
94 |
@command{ssh}/@command{scp}. |
programs, such as @command{ssh}/@command{scp}. |
95 |
|
|
96 |
You can find the latest version of this document on the web at |
You can find the latest version of this document on the web at |
97 |
@uref{http://www.freesoftware.fsf.org/tramp/}. |
@uref{http://www.freesoftware.fsf.org/tramp/}. |
118 |
|
|
119 |
@menu |
@menu |
120 |
* Overview:: What @tramp{} can and cannot do. |
* Overview:: What @tramp{} can and cannot do. |
121 |
|
* Copying:: The license for this documentation. |
122 |
|
|
123 |
For the end user: |
For the end user: |
124 |
* Obtaining @tramp{}:: How to obtain @tramp{}. |
* Obtaining @tramp{}:: How to obtain @tramp{}. |
125 |
* History:: History of @tramp{} |
* History:: History of @tramp{}. |
126 |
* Installation:: Installing @tramp{} with your (X)Emacs. |
* Installation:: Installing @tramp{} with your @value{emacs-name}. |
127 |
* Configuration:: Configuring @tramp{} for use. |
* Configuration:: Configuring @tramp{} for use. |
128 |
* Usage:: An overview of the operation of @tramp{}. |
* Usage:: An overview of the operation of @tramp{}. |
129 |
* Bug Reports:: Reporting Bugs and Problems |
* Bug Reports:: Reporting Bugs and Problems. |
130 |
* Frequently Asked Questions:: Questions and answers from the mailing list. |
* Frequently Asked Questions:: Questions and answers from the mailing list. |
131 |
|
|
132 |
For the developer: |
For the developer: |
133 |
* Version Control:: The inner workings of remote version control. |
* Version Control:: The inner workings of remote version control. |
134 |
* Files directories and paths:: How file names, directories and paths are mangled and managed. |
* Files directories and paths:: How file names, directories and paths are mangled and managed. |
135 |
* Issues:: |
* Issues:: Debatable Issues and What Was Decided. |
136 |
|
|
137 |
@detailmenu |
@detailmenu |
138 |
--- The Detailed Node Listing --- |
--- The Detailed Node Listing --- |
145 |
* Multi-hop Methods:: Connecting to a remote host using multiple hops. |
* Multi-hop Methods:: Connecting to a remote host using multiple hops. |
146 |
* Default Method:: Selecting a default method. |
* Default Method:: Selecting a default method. |
147 |
* Customizing Methods:: Using Non-Standard Methods. |
* Customizing Methods:: Using Non-Standard Methods. |
148 |
|
* Customizing Completion:: Selecting config files for user/host name completion. |
149 |
* Remote Programs:: How @tramp{} finds and uses programs on the remote machine. |
* Remote Programs:: How @tramp{} finds and uses programs on the remote machine. |
150 |
* Remote shell setup:: |
* Remote shell setup:: Remote shell setup hints. |
151 |
|
* Windows setup hints:: Issues with Cygwin ssh. |
152 |
|
|
153 |
Using @tramp |
Using @tramp |
154 |
|
|
155 |
* Filename Syntax:: @tramp{} filename conventions. |
* Filename Syntax:: @tramp{} filename conventions. |
156 |
* Multi-hop filename syntax:: Multi-hop filename conventions |
* Multi-hop filename syntax:: Multi-hop filename conventions. |
157 |
* Dired:: Dired and filename completion. |
* Filename completion:: Filename completion. |
158 |
|
* Dired:: Dired. |
159 |
|
|
160 |
The inner workings of remote version control |
The inner workings of remote version control |
161 |
|
|
163 |
* Remote Commands:: Executing the version control commands on the remote machine. |
* Remote Commands:: Executing the version control commands on the remote machine. |
164 |
* Changed workfiles:: Detecting if the working file has changed. |
* Changed workfiles:: Detecting if the working file has changed. |
165 |
* Checking out files:: Bringing the workfile out of the repository. |
* Checking out files:: Bringing the workfile out of the repository. |
166 |
* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere |
* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. |
167 |
|
|
168 |
Things related to Version Control that don't fit elsewhere |
Things related to Version Control that don't fit elsewhere |
169 |
|
|
177 |
@end detailmenu |
@end detailmenu |
178 |
@end menu |
@end menu |
179 |
|
|
|
|
|
180 |
@node Overview |
@node Overview |
181 |
@chapter An overview of @tramp |
@chapter An overview of @tramp |
182 |
@cindex overview |
@cindex overview |
183 |
|
|
184 |
After the installation of @tramp{} into your Emacs, you will be able |
After the installation of @tramp{} into your @value{emacs-name}, you |
185 |
to access files on remote machines as though they were local. Access |
will be able to access files on remote machines as though they were |
186 |
to the remote file system for editing files, version control, and |
local. Access to the remote file system for editing files, version |
187 |
@command{dired} are transparently enabled. |
control, and @command{dired} are transparently enabled. |
188 |
|
|
189 |
Your access to the remote machine can be with the @command{rsh}, |
Your access to the remote machine can be with the @command{rsh}, |
190 |
@command{rlogin}, @command{telnet} programs or with any similar |
@command{rlogin}, @command{telnet} programs or with any similar |
248 |
@tramp{} discovers that it needs a connection to the host. So it |
@tramp{} discovers that it needs a connection to the host. So it |
249 |
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l |
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l |
250 |
@var{user}} or a similar tool to connect to the remote host. |
@var{user}} or a similar tool to connect to the remote host. |
251 |
Communication with this process happens through an Emacs buffer, that |
Communication with this process happens through an |
252 |
is, the output from the remote end goes into a buffer. |
@value{emacs-name} buffer, that is, the output from the remote end |
253 |
|
goes into a buffer. |
254 |
|
|
255 |
@item |
@item |
256 |
The remote host may prompt for a login name (for @command{telnet}). The |
The remote host may prompt for a login name (for @command{telnet}). The |
274 |
say), then it issues an error message saying that it couldn't find the |
say), then it issues an error message saying that it couldn't find the |
275 |
remote shell prompt and shows you what the remote host has sent. |
remote shell prompt and shows you what the remote host has sent. |
276 |
|
|
277 |
If @tramp{} sees a `login failed' message, it tells you so, aborts the |
If @tramp{} sees a @samp{login failed} message, it tells you so, |
278 |
login attempt and allows you to try again. |
aborts the login attempt and allows you to try again. |
279 |
|
|
280 |
@item |
@item |
281 |
Suppose that the login was successful and @tramp{} sees the shell prompt |
Suppose that the login was successful and @tramp{} sees the shell prompt |
313 |
buffer that's used for communication, then decodes that output to |
buffer that's used for communication, then decodes that output to |
314 |
produce the file contents. |
produce the file contents. |
315 |
|
|
316 |
For out-of-band transfers, @tramp{} issues a command like @samp{rcp |
For out-of-band transfers, @tramp{} issues a command like the following: |
317 |
user@@host:/path/to/remote/file /tmp/tramp.4711} and then reads the local |
@example |
318 |
temporary file @file{/tmp/tramp.4711} into a buffer and deletes the |
rcp user@@host:/path/to/remote/file /tmp/tramp.4711 |
319 |
temporary file. |
@end example |
320 |
|
It then reads the local temporary file @file{/tmp/tramp.4711} into a |
321 |
|
buffer and deletes the temporary file. |
322 |
|
|
323 |
@item |
@item |
324 |
You now edit the buffer contents, blithely unaware of what has happened |
You now edit the buffer contents, blithely unaware of what has happened |
336 |
behind the scenes when you open a file with @tramp{}. |
behind the scenes when you open a file with @tramp{}. |
337 |
|
|
338 |
|
|
339 |
|
@c Copying permissions, et al |
340 |
|
@node Copying |
341 |
|
@chapter Copying. |
342 |
|
@cindex copying |
343 |
|
|
344 |
|
@copying |
345 |
|
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software |
346 |
|
Foundation, Inc. |
347 |
|
|
348 |
|
@quotation |
349 |
|
Permission is granted to copy, distribute and/or modify this document |
350 |
|
under the terms of the GNU Free Documentation License, Version 1.1 or |
351 |
|
any later version published by the Free Software Foundation; with no |
352 |
|
Invariant Sections, with the Front-Cover texts being ``A GNU |
353 |
|
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
354 |
|
license is included in the section entitled ``GNU Free Documentation |
355 |
|
License'' in the Emacs manual. |
356 |
|
|
357 |
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
358 |
|
this GNU Manual, like GNU software. Copies published by the Free |
359 |
|
Software Foundation raise funds for GNU development.'' |
360 |
|
|
361 |
|
This document is part of a collection distributed under the GNU Free |
362 |
|
Documentation License. If you want to distribute this document |
363 |
|
separately from the collection, you can do so by adding a copy of the |
364 |
|
license to the document, as described in section 6 of the license. |
365 |
|
@end quotation |
366 |
|
@end copying |
367 |
|
|
368 |
|
|
369 |
@c For the end user |
@c For the end user |
370 |
@node Obtaining @tramp{} |
@node Obtaining @tramp{} |
371 |
@chapter Obtaining @tramp{}. |
@chapter Obtaining @tramp{}. |
385 |
new issues. Use these versions at your own risk. |
new issues. Use these versions at your own risk. |
386 |
|
|
387 |
Instructions for obtaining the latest development version of @tramp{} |
Instructions for obtaining the latest development version of @tramp{} |
388 |
from CVS can be found by going to the Savannah project page at |
from CVS can be found by going to the Savannah project page at the |
389 |
@uref{http://savannah.gnu.org/projects/tramp/} and then clicking on the |
following URL and then clicking on the CVS link in the navigation bar at |
390 |
CVS link in the navigation bar at the top. Or follow the example |
the top. |
391 |
session below: |
|
392 |
|
@noindent |
393 |
|
@uref{http://savannah.gnu.org/projects/tramp/} |
394 |
|
|
395 |
|
@noindent |
396 |
|
Or follow the example session below: |
397 |
|
|
398 |
@example |
@example |
399 |
] @strong{cd ~/lisp} |
] @strong{cd ~/@value{emacs-dir}} |
400 |
] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login} |
] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login} |
401 |
|
|
402 |
(Logging in to anoncvs@@subversions.gnu.org) |
(Logging in to anoncvs@@subversions.gnu.org) |
406 |
] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp} |
] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp} |
407 |
@end example |
@end example |
408 |
|
|
409 |
You should now have a directory @file{~/lisp/tramp} containing the latest |
@noindent |
410 |
|
You should now have a directory @file{~/@value{emacs-dir}/tramp} containing the latest |
411 |
version of @tramp{}. You can fetch the latest updates from the repository |
version of @tramp{}. You can fetch the latest updates from the repository |
412 |
by issuing the command: |
by issuing the command: |
413 |
|
|
414 |
@example |
@example |
415 |
] @strong{cd ~/lisp/tramp} |
] @strong{cd ~/@value{emacs-dir}/tramp} |
416 |
] @strong{cvs update -d} |
] @strong{cvs update -d} |
417 |
@end example |
@end example |
418 |
|
|
436 |
|
|
437 |
|
|
438 |
@node Installation |
@node Installation |
439 |
@chapter Installing @tramp{} into Emacs or XEmacs |
@chapter Installing @tramp{} into @value{emacs-name}. |
440 |
@cindex installation |
@cindex installation |
441 |
|
|
442 |
If you use the version that comes with your Emacs or the XEmacs |
If you use the version that comes with your @value{emacs-name}, the |
443 |
package, the following information is not necessary. Installing |
following information is not necessary. Installing @tramp{} into your |
444 |
@tramp{} into your Emacs or XEmacs is a relatively easy process, at |
@value{emacs-name} is a relatively easy process, at least compared |
445 |
least compared to rebuilding your machine from scratch. ;) |
to rebuilding your machine from scratch. ;) |
446 |
|
|
447 |
Seriously though, the installation should be a fairly simple matter. |
Seriously though, the installation should be a fairly simple matter. |
448 |
|
|
449 |
The easiest way to proceed is as follows: |
The easiest way to proceed is as follows: |
450 |
|
|
451 |
@itemize |
@itemize @bullet |
452 |
@item |
@item |
453 |
Choose a directory, say @file{~/emacs/}. Change into that directory and |
Choose a directory, say @file{~/@value{emacs-dir}/}. Change into that directory and |
454 |
unpack the tarball. This will give you a directory |
unpack the tarball. This will give you a directory |
455 |
@file{~/emacs/tramp/} which contains subdirectories @file{lisp} for the |
@file{~/@value{emacs-dir}/tramp/} which contains subdirectories @file{lisp} for the |
456 |
Lisp code and @file{texi} for the documentation. |
Lisp code and @file{texi} for the documentation. |
457 |
|
|
458 |
@item |
@item |
459 |
Optionally byte-compile all files in the Lisp directory, |
Optionally byte-compile all files in the Lisp directory, |
460 |
@file{~/emacs/tramp/lisp/}, by issuing a command like the following from |
@file{~/@value{emacs-dir}/tramp/lisp/}, by issuing a command like the following from |
461 |
the top level directory @file{~/emacs/tramp/}: |
the top level directory @file{~/@value{emacs-dir}/tramp/}: |
462 |
|
|
463 |
@example |
@example |
464 |
make EMACS=emacs all # for Emacs users |
make EMACS=@value{emacs-dir} all |
|
make EMACS=xemacs all # for XEmacs users |
|
465 |
@end example |
@end example |
466 |
|
|
467 |
@item |
@item |
468 |
NOTE: |
NOTE: If you run into problems running the example @command{make} |
469 |
@example |
command, don't dispare. You can still byte compile the @file{*.el} |
470 |
If you run into problems running the example @command{make} |
files by opening @value{emacs-name} in @command{dired} (@command{C-x |
471 |
commands, don't dispare. You can still byte compile the |
d}) mode, at @file{~/@value{emacs-dir}/tramp/lisp}. Mark the lisp files with |
472 |
@file{*.el} files by opening emacs in @command{dired} |
@kbd{m}, then press @kbd{B} to byte compile your selections. |
473 |
(@command{C-x d}) mode, at @file{~/tramp/lisp}. Mark the lisp |
|
474 |
files with @kbd{m}, then press @kbd{B} to byte compile |
Something similar can be done to create the info manual. Just change |
475 |
your selections. |
to directory @file{~/@value{emacs-dir}/tramp/texi} and load the |
476 |
|
@file{tramp.texi} file in @value{emacs-name}. Then press @kbd{M-x |
477 |
Something similar can be done to create the info manual. |
makeinfo-buffer @key{RET}} to generate @file{tramp.info}. |
|
Just cd to @file{~/emacs/tramp/texi} and load the @file{tramp.texi} |
|
|
file in emacs. Then press @kbd{M-x makeinfo-buffer <RET>} |
|
|
to generate @file{tramp.info}. |
|
|
@end example |
|
478 |
|
|
479 |
@item |
@item |
480 |
Tell Emacs about the new Lisp directory and the @tramp{} package |
Tell @value{emacs-name} about the new Lisp directory and the |
481 |
with the following lines in @file{~/.emacs}: |
@tramp{} package with the following lines in @file{~/.emacs}: |
482 |
|
|
483 |
@lisp |
@lisp |
484 |
(add-to-list 'load-path "~/emacs/tramp/lisp/") |
(add-to-list 'load-path "~/@value{emacs-dir}/tramp/lisp/") |
485 |
(require 'tramp) |
(require 'tramp) |
486 |
@end lisp |
@end lisp |
487 |
|
|
488 |
@item |
@item |
489 |
To be able to read the Info documentation, create a file |
To be able to read the Info documentation, create a file |
490 |
@file{~/emacs/tramp/texi/dir} using for example the |
@file{~/@value{emacs-dir}/tramp/texi/dir} using the |
491 |
@command{install-info} command, and add the directory to the search |
@command{install-info} command, and add the directory to the search |
492 |
path for Info. |
path for Info. |
493 |
|
|
|
@item |
|
494 |
NOTE: |
NOTE: |
495 |
|
On systems using the @cite{gnu} version of @command{install-info}, the |
496 |
|
@command{install-info} syntax is very direct and simple. One can |
497 |
|
change to directory @file{~/@value{emacs-dir}/tramp/texi} and type: |
498 |
|
|
499 |
@example |
@example |
500 |
On systems using `gnu' @command{install-info}, the |
install-info tramp.info dir |
501 |
@command{install-info} syntax is very direct and simple. One can |
@end example |
502 |
cd to @file{~/emacs/tramp/texi} and type: |
|
|
@kbd{install-info tramp.info dir} |
|
503 |
and a @file{dir} file will be created with the @tramp{} |
and a @file{dir} file will be created with the @tramp{} |
504 |
entry. The info reader will know how to interpret it, but must |
entry. The info reader will know how to interpret it, but must |
505 |
be told where to find it (see below). If you want anything fancier |
be told where to find it (see below). If you want anything fancier |
506 |
you'll need to look through @kbd{man install-info}. |
you'll need to look through @kbd{man install-info}. |
507 |
|
|
508 |
Debian gnu/linux doesn't default to `gnu' @command{install-info} and |
Debian gnu/linux doesn't default to @cite{gnu} @command{install-info} |
509 |
uses its own version. This version does not create a @file{dir} file |
and uses its own version. This version does not create a @file{dir} |
510 |
for you from scratch. You must provide a skeleton dir file it |
file for you from scratch. You must provide a skeleton @file{dir} |
511 |
recognizes. One can be found in a default install at |
file it recognizes. One can be found in a default installation of |
512 |
@file{/usr/info/dir}. Copy the top of this file down to the first |
@value{emacs-name} at @file{/usr/info/dir}. Copy the top of this file |
513 |
occurrence of `* Menu' including that line plus one more blank line, |
down to the first occurrence of @code{* Menu} including that line plus |
514 |
to your working directory @file{texi/dir}, or use the sample provided |
one more blank line, to your working directory |
515 |
in the @file{texi} directory of this distribution. See |
@file{~/@value{emacs-dir}/tramp/texi}, or use the sample |
516 |
@file{texi/dir_sample} |
@file{~/@value{emacs-dir}/tramp/texi/dir_sample}. |
517 |
|
|
518 |
Once a @file{dir} file is in place, this command will make the entry. |
Once a @file{dir} file is in place, this command will make the entry: |
519 |
install-info --infodir=. tramp.info |
|
520 |
If you want it in a specific category |
@example |
521 |
(see @kbd{man install-info} for further details) |
install-info --infodir=. tramp.info |
522 |
@end example |
@end example |
523 |
|
|
524 |
|
If you want it in a specific category see @kbd{man install-info} for |
525 |
|
further details. |
526 |
|
|
527 |
If the environment variable @env{INFOPATH} is set, add the directory |
If the environment variable @env{INFOPATH} is set, add the directory |
528 |
@file{~/emacs/tramp/texi/} to it. Else, add the directory to |
@file{~/@value{emacs-dir}/tramp/texi/} to it. Else, add the directory to |
529 |
|
@ifset emacs |
530 |
@code{Info-default-directory-list}, as follows: |
@code{Info-default-directory-list}, as follows: |
531 |
|
|
532 |
@lisp |
@lisp |
533 |
(add-to-list 'Info-default-directory-list "~/emacs/tramp/texi/") |
(add-to-list 'Info-default-directory-list "~/@value{emacs-dir}/tramp/texi/") |
534 |
@end lisp |
@end lisp |
535 |
XEmacs 21 users should use @code{Info-directory-list} rather than |
@end ifset |
536 |
@code{Info-default-directory-list}. |
@ifset xemacs |
537 |
|
@code{Info-directory-list}, as follows: |
538 |
|
@lisp |
539 |
|
(add-to-list 'Info-directory-list "~/@value{emacs-dir}/tramp/texi/") |
540 |
|
@end lisp |
541 |
|
@end ifset |
542 |
|
|
543 |
@end itemize |
@end itemize |
544 |
|
|
545 |
|
@ifset xemacs |
546 |
For XEmacs users, the package @file{fsf-compat} must be installed. |
For @value{emacs-name}, the package @file{fsf-compat} must be installed. |
547 |
For details on package installation, see @ref{Packages, , ,xemacs}. |
For details on package installation, see @ref{Packages, , ,xemacs}. |
548 |
@ifhtml |
@ifhtml |
549 |
(If the previous link doesn't work, try the XEmacs documentation at |
(If the previous link doesn't work, try the @value{emacs-name} |
550 |
@uref{http://www.xemacs.org/Documentation/packageGuide.html,the XEmacs |
documentation at |
551 |
site}.) |
@uref{http://www.xemacs.org/Documentation/packageGuide.html,the |
552 |
|
@value{emacs-name} site}.) |
553 |
@end ifhtml |
@end ifhtml |
554 |
|
@end ifset |
555 |
|
|
556 |
@node Configuration |
@node Configuration |
557 |
@chapter Configuring @tramp{} for use |
@chapter Configuring @tramp{} for use |
559 |
|
|
560 |
@cindex default configuration |
@cindex default configuration |
561 |
@tramp{} is (normally) fully functional when it is initially |
@tramp{} is (normally) fully functional when it is initially |
562 |
installed. It is initially configured to use the @command{sh} program |
installed. It is initially configured to use the @command{ssh} program |
563 |
to connect to the remote host and to use base-64 encoding (on the |
to connect to the remote host and to use base-64 encoding (on the |
564 |
remote host, via @command{mimencode}, and on the local host via the |
remote host, via @command{mimencode}, and on the local host via the |
565 |
built-in support for base-64 encoding in Emacs). |
built-in support for base-64 encoding in Emacs). |
582 |
* Multi-hop Methods:: Connecting to a remote host using multiple hops. |
* Multi-hop Methods:: Connecting to a remote host using multiple hops. |
583 |
* Default Method:: Selecting a default method. |
* Default Method:: Selecting a default method. |
584 |
* Customizing Methods:: Using Non-Standard Methods. |
* Customizing Methods:: Using Non-Standard Methods. |
585 |
|
* Customizing Completion:: Selecting config files for user/host name completion. |
586 |
* Remote Programs:: How @tramp{} finds and uses programs on the remote machine. |
* Remote Programs:: How @tramp{} finds and uses programs on the remote machine. |
587 |
* Remote shell setup:: Remote shell setup hints. |
* Remote shell setup:: Remote shell setup hints. |
588 |
* Windows setup hints:: Issues with Cygwin ssh. |
* Windows setup hints:: Issues with Cygwin ssh. |
611 |
@cindex methods, external transfer |
@cindex methods, external transfer |
612 |
@cindex methods, out-of-band |
@cindex methods, out-of-band |
613 |
Loading or saving a remote file requires that the content of the file |
Loading or saving a remote file requires that the content of the file |
614 |
be transferred between the two machines. The content of the file can be |
be transfered between the two machines. The content of the file can be |
615 |
transferred over the same connection used to log in to the remote |
transfered over the same connection used to log in to the remote |
616 |
machine or the file can be transferred through another connection using |
machine or the file can be transfered through another connection using |
617 |
a remote copy program such as @command{rcp}, @command{scp} or |
a remote copy program such as @command{rcp}, @command{scp} or |
618 |
@command{rsync}. The former are called @dfn{inline methods}, the |
@command{rsync}. The former are called @dfn{inline methods}, the |
619 |
latter are called @dfn{out-of-band methods} or @dfn{external transfer |
latter are called @dfn{out-of-band methods} or @dfn{external transfer |
713 |
that use the @command{ssh1} and @command{ssh2} commands explicitly. If |
that use the @command{ssh1} and @command{ssh2} commands explicitly. If |
714 |
you don't know what these are, you do not need these options. |
you don't know what these are, you do not need these options. |
715 |
|
|
716 |
All the methods based on @command{ssh} have an additional kludgey |
All the methods based on @command{ssh} have an additional kludgy |
717 |
feature: you can specify a host name which looks like @file{host#42} |
feature: you can specify a host name which looks like @file{host#42} |
718 |
(the real host name, then a hash sign, then a port number). This |
(the real host name, then a hash sign, then a port number). This |
719 |
means to connect to the given host but to also pass @code{-p 42} as |
means to connect to the given host but to also pass @code{-p 42} as |
846 |
As you expect, this is similar to @option{sm}, only a little |
As you expect, this is similar to @option{sm}, only a little |
847 |
different. Whereas @option{sm} opens a normal interactive shell on |
different. Whereas @option{sm} opens a normal interactive shell on |
848 |
the remote host, this option uses @samp{ssh -t -t @var{host} -l |
the remote host, this option uses @samp{ssh -t -t @var{host} -l |
849 |
@var{user} /bin/sh} tp open a connection. This is useful for users |
@var{user} /bin/sh} to open a connection. This is useful for users |
850 |
where the normal login shell is set up to ask them a number of |
where the normal login shell is set up to ask them a number of |
851 |
questions when logging in. This procedure avoids these questions, and |
questions when logging in. This procedure avoids these questions, and |
852 |
just gives @tramp{} a more-or-less `standard' login shell to work |
just gives @tramp{} a more-or-less `standard' login shell to work |
971 |
session can begin to absorb the advantage that the lack of encoding and |
session can begin to absorb the advantage that the lack of encoding and |
972 |
decoding presents. |
decoding presents. |
973 |
|
|
974 |
All the @command{ssh} based methods support the kludgey @samp{-p} |
All the @command{ssh} based methods support the kludgy @samp{-p} |
975 |
feature where you can specify a port number to connect to in the host |
feature where you can specify a port number to connect to in the host |
976 |
name. For example, the host name @file{host#42} tells Tramp to |
name. For example, the host name @file{host#42} tells Tramp to |
977 |
specify @samp{-p 42} in the argument list for @command{ssh}. |
specify @samp{-p 42} in the argument list for @command{ssh}. |
1167 |
example: |
example: |
1168 |
|
|
1169 |
@lisp |
@lisp |
1170 |
(add-to-list 'tramp-multi-connection-function-alist |
(add-to-list |
1171 |
'("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n")) |
'tramp-multi-connection-function-alist |
1172 |
|
'("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n")) |
1173 |
@end lisp |
@end lisp |
1174 |
|
|
1175 |
Now you can use a @code{sshf} hop which connects to port 4400 instead of |
Now you can use an @code{sshf} hop which connects to port 4400 instead of |
1176 |
the standard port. |
the standard port. |
1177 |
|
|
1178 |
|
|
1246 |
variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. |
variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. |
1247 |
|
|
1248 |
|
|
1249 |
|
@node Customizing Completion |
1250 |
|
@section Selecting config files for user/host name completion |
1251 |
|
@cindex customizing completion |
1252 |
|
@cindex selecting config files |
1253 |
|
@vindex tramp-completion-function-alist |
1254 |
|
|
1255 |
|
The variable @code{tramp-completion-function-alist} is intended to |
1256 |
|
customize, which files are taken into account for user and host name |
1257 |
|
completion (@pxref{Filename completion}). For every method, it keeps |
1258 |
|
a set of configuration files, accompanied by a Lisp function able to |
1259 |
|
parse that file. Entries in @code{tramp-completion-function-alist} |
1260 |
|
have the form (@var{method} @var{pair1} @var{pair2} ...). |
1261 |
|
|
1262 |
|
Each @var{pair} is composed of (@var{function} @var{file}). |
1263 |
|
@var{function} is responsible to extract user names and host names |
1264 |
|
from @var{file} for completion. There are two functions which access |
1265 |
|
this variable: |
1266 |
|
|
1267 |
|
@defun tramp-get-completion-function method |
1268 |
|
This function returns the list of completion functions for @var{method}. |
1269 |
|
|
1270 |
|
Example: |
1271 |
|
@example |
1272 |
|
(tramp-get-completion-function "rsh") |
1273 |
|
|
1274 |
|
@result{} ((tramp-parse-rhosts "/etc/hosts.equiv") |
1275 |
|
(tramp-parse-rhosts "~/.rhosts")) |
1276 |
|
@end example |
1277 |
|
@end defun |
1278 |
|
|
1279 |
|
@defun tramp-set-completion-function method function-list |
1280 |
|
This function sets @var{function-list} as list of completion functions |
1281 |
|
for @var{method}. |
1282 |
|
|
1283 |
|
Example: |
1284 |
|
@example |
1285 |
|
(tramp-set-completion-function "ssh" |
1286 |
|
'((tramp-parse-shosts "/etc/ssh_known_hosts") |
1287 |
|
(tramp-parse-shosts "~/.ssh/known_hosts"))) |
1288 |
|
|
1289 |
|
@result{} ((tramp-parse-shosts "/etc/ssh_known_hosts") |
1290 |
|
(tramp-parse-shosts "~/.ssh/known_hosts")) |
1291 |
|
@end example |
1292 |
|
@end defun |
1293 |
|
|
1294 |
|
The following predefined functions parsing configuration files exists: |
1295 |
|
|
1296 |
|
@table @asis |
1297 |
|
@item @code{tramp-parse-rhosts} |
1298 |
|
@findex tramp-parse-rhosts |
1299 |
|
|
1300 |
|
This function parses files which are syntactical equivalent to |
1301 |
|
@file{~/.rhosts}. It returns both host names and user names, if |
1302 |
|
specified. |
1303 |
|
|
1304 |
|
@item @code{tramp-parse-shosts} |
1305 |
|
@findex tramp-parse-shosts |
1306 |
|
|
1307 |
|
This function parses files which are syntactical equivalent to |
1308 |
|
@file{/etc/ssh_known_hosts}. Since there are no user names specified |
1309 |
|
in such files, it can return host names only. |
1310 |
|
|
1311 |
|
@item @code{tramp-parse-hosts} |
1312 |
|
@findex tramp-parse-hosts |
1313 |
|
|
1314 |
|
A function dedicated to @file{/etc/hosts} style files. It returns |
1315 |
|
host names only. |
1316 |
|
|
1317 |
|
@item @code{tramp-parse-passwd} |
1318 |
|
@findex tramp-parse-passwd |
1319 |
|
|
1320 |
|
Finally a method which parses @file{/etc/passwd} like files. |
1321 |
|
Obviously, it can return user names only. |
1322 |
|
@end table |
1323 |
|
|
1324 |
|
@ifset emacs |
1325 |
|
A function which parses @file{~/.netrc"} file syntax doesn't exist in |
1326 |
|
@tramp{}, because this task is delegated to |
1327 |
|
@value{ftp-package-name}. Its customization should be used instead. |
1328 |
|
@end ifset |
1329 |
|
|
1330 |
|
If you want to keep your own data in a file, with your own structure, |
1331 |
|
you might provide such a function as well. This function must meet |
1332 |
|
the following conventions: |
1333 |
|
|
1334 |
|
@defun my-tramp-parse file |
1335 |
|
@var{file} must be either a file name on your host, or @code{nil}. The |
1336 |
|
function must return a list of (@var{user} @var{host}), which are |
1337 |
|
taken as candidates for user and host name completion. |
1338 |
|
|
1339 |
|
Example: |
1340 |
|
@example |
1341 |
|
(my-tramp-parse "~/.my-tramp-hosts") |
1342 |
|
|
1343 |
|
@result{} ((nil "toto") ("daniel" "melancholia")) |
1344 |
|
@end example |
1345 |
|
@end defun |
1346 |
|
|
1347 |
|
|
1348 |
@node Remote Programs |
@node Remote Programs |
1349 |
@section How @tramp{} finds and uses programs on the remote machine. |
@section How @tramp{} finds and uses programs on the remote machine. |
1350 |
|
|
1379 |
To add a directory to the remote search path, you could use code such |
To add a directory to the remote search path, you could use code such |
1380 |
as: |
as: |
1381 |
|
|
1382 |
@example |
@lisp |
1383 |
(require 'tramp) @i{; @tramp{} must be loaded before this} |
@i{;; We load @tramp{} to define the variable.} |
1384 |
@i{; happens.} |
(require 'tramp) |
1385 |
|
@i{;; We have @command{perl} in "/usr/local/perl/bin"} |
|
@i{; We have @command{perl} in "/usr/local/perl/bin"} |
|
1386 |
(add-to-list 'tramp-remote-path "/usr/local/perl/bin") |
(add-to-list 'tramp-remote-path "/usr/local/perl/bin") |
1387 |
@end example |
@end lisp |
1388 |
|
|
1389 |
|
|
1390 |
@node Remote shell setup |
@node Remote shell setup |
1391 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
1398 |
As explained in the @ref{Overview} section, @tramp{} connects to the |
As explained in the @ref{Overview} section, @tramp{} connects to the |
1399 |
remote host and talks to the shell it finds there. Of course, when you |
remote host and talks to the shell it finds there. Of course, when you |
1400 |
log in, the shell executes its init files. Suppose your init file |
log in, the shell executes its init files. Suppose your init file |
1401 |
requires you to enter the birthdate of your mother; clearly @tramp{} |
requires you to enter the birth date of your mother; clearly @tramp{} |
1402 |
does not know this and hence fails to log you in to that host. |
does not know this and hence fails to log you in to that host. |
1403 |
|
|
1404 |
There are different possible strategies for pursuing this problem. One |
There are different possible strategies for pursuing this problem. One |
1440 |
recognizes the @code{>} character as the end of the prompt, but it is |
recognizes the @code{>} character as the end of the prompt, but it is |
1441 |
not at the end of the buffer. |
not at the end of the buffer. |
1442 |
|
|
1443 |
|
@item @var{tramp-shell-prompt-pattern} |
1444 |
|
@vindex tramp-shell-prompt-pattern |
1445 |
|
|
1446 |
|
This regular expression is used by @tramp{} in the same way as |
1447 |
|
@code{shell-prompt-pattern}, to match prompts from the remote shell. |
1448 |
|
This second variable exists because the prompt from the remote shell |
1449 |
|
might be different from the prompt from a local shell --- after all, |
1450 |
|
the whole point of @tramp{} is to log in to remote hosts as a |
1451 |
|
different user. The default value of |
1452 |
|
@code{tramp-shell-prompt-pattern} is the same as the default value of |
1453 |
|
@code{shell-prompt-pattern}, which is reported to work well in many |
1454 |
|
circumstances. |
1455 |
|
|
1456 |
@item @code{tset} and other questions |
@item @code{tset} and other questions |
1457 |
@cindex Unix command tset |
@cindex Unix command tset |
1458 |
@cindex tset Unix command |
@cindex tset Unix command |
1459 |
|
|
1460 |
Some people invoke the @code{tset} program from their shell startup |
Some people invoke the @code{tset} program from their shell startup |
1461 |
scripts which asks the user about the terminal type of the shell. Maybe |
scripts which asks the user about the terminal type of the shell. |
1462 |
some shells ask other questions when they are started. @tramp{} does |
Maybe some shells ask other questions when they are started. @tramp{} |
1463 |
not know how to answer these questions. (A facility for enabling |
does not know how to answer these questions. There are two approaches |
1464 |
@tramp{} to answer these questions is planned for some future version, |
for dealing with this problem. One approach is to take care that the |
1465 |
but don't hold your breath.) |
shell does not ask any questions when invoked from @tramp{}. You can |
1466 |
|
do this by checking the @code{TERM} environment variable, it will be |
1467 |
Therefore, you should take care that the shell does not ask any |
set to @code{dumb} when connecting. |
|
questions when invoked from @tramp{}. You can do this by checking the |
|
|
@code{TERM} environment variable, it will be set to @code{dumb} when |
|
|
connecting. |
|
1468 |
|
|
1469 |
@vindex tramp-terminal-type |
@vindex tramp-terminal-type |
1470 |
The variable @code{tramp-terminal-type} can be used to change this value |
The variable @code{tramp-terminal-type} can be used to change this value |
1471 |
@code{dumb}. |
to @code{dumb}. |
1472 |
|
|
1473 |
|
The other approach is to teach @tramp{} about these questions. See |
1474 |
|
the variables @code{tramp-actions-before-shell} and |
1475 |
|
@code{tramp-multi-actions} (for multi-hop connections). |
1476 |
|
|
1477 |
@end table |
@end table |
1478 |
|
|
1501 |
|
|
1502 |
Files are specified to @tramp{} using a formalized syntax specifying the |
Files are specified to @tramp{} using a formalized syntax specifying the |
1503 |
details of the system to connect to. This is similar to the syntax used |
details of the system to connect to. This is similar to the syntax used |
1504 |
by the @command{EFS} and @command{Ange-FTP} packages. |
by the @value{ftp-package-name} package. |
1505 |
|
|
1506 |
|
@cindex type-ahead |
1507 |
|
Something that might happen which surprises you is that Emacs |
1508 |
|
remembers all your keystrokes, so if you see a password prompt from |
1509 |
|
Emacs, say, and hit @kbd{@key{RET}} twice instead of once, then the |
1510 |
|
second keystroke will be processed by Emacs after @tramp{} has done |
1511 |
|
its thing. Why, this type-ahead is normal behavior, you say. Right |
1512 |
|
you are, but be aware that opening a remote file might take quite a |
1513 |
|
while, maybe half a minute when a connection needs to be opened. |
1514 |
|
Maybe after half a minute you have already forgotten that you hit that |
1515 |
|
key! |
1516 |
|
|
1517 |
@menu |
@menu |
1518 |
* Filename Syntax:: @tramp{} filename conventions. |
* Filename Syntax:: @tramp{} filename conventions. |
1519 |
* Multi-hop filename syntax:: Multi-hop filename conventions |
* Multi-hop filename syntax:: Multi-hop filename conventions. |
1520 |
* Dired:: Dired and filename completion. |
* Filename completion:: Filename completion. |
1521 |
|
* Dired:: Dired. |
1522 |
@end menu |
@end menu |
1523 |
|
|
1524 |
|
|
1527 |
@cindex filename syntax |
@cindex filename syntax |
1528 |
@cindex filename examples |
@cindex filename examples |
1529 |
|
|
1530 |
On Emacs, the Ange-FTP and Tramp filenames use a unified syntax. On |
To access the file @var{path} on the remote machine @var{machine} you |
1531 |
XEmacs, EFS and Tramp use different formats for the filenames. |
would specify the filename |
1532 |
Therefore, the following will describe the Emacs and XEmacs cases |
@file{@value{tramp-prefix}@var{machine}@value{tramp-postfix}@var{path}}. |
1533 |
separately. |
This will connect to @var{machine} and transfer the file using the |
1534 |
|
default method. @xref{Default Method}. |
1535 |
On Emacs, to access the file @var{path} on the remote machine |
|
1536 |
@var{machine} you would specify the filename |
Some examples of @tramp{} filenames are shown below. |
|
@file{/@var{machine}:@var{path}}. This will connect to @var{machine} |
|
|
and transfer the file using the default method. @xref{Default |
|
|
Method}. On XEmacs, use @file{/[@var{machine}]@var{path}}. (The |
|
|
square brackets are part of the file name.) |
|
|
|
|
|
Some examples of @tramp{} filenames are shown below. In each case, |
|
|
the Emacs-style filename is shown first, then the XEmacs-style |
|
|
filename. |
|
1537 |
|
|
1538 |
@table @file |
@table @file |
1539 |
@item /melancholia:.emacs |
@item @value{tramp-prefix}melancholia@value{tramp-postfix}.emacs |
|
@itemx /[melancholia].emacs |
|
1540 |
Edit the file @file{.emacs} in your home directory on the machine |
Edit the file @file{.emacs} in your home directory on the machine |
1541 |
@code{melancholia}. |
@code{melancholia}. |
1542 |
|
|
1543 |
@item /melancholia.danann.net:.emacs |
@item @value{tramp-prefix}melancholia.danann.net@value{tramp-postfix}.emacs |
|
@itemx /[melancholia.danann.net].emacs |
|
1544 |
This edits the same file, using the fully qualified domain name of |
This edits the same file, using the fully qualified domain name of |
1545 |
the machine. |
the machine. |
1546 |
|
|
1547 |
@item /melancholia:~/.emacs |
@item @value{tramp-prefix}melancholia@value{tramp-postfix}~/.emacs |
|
@itemx /[melancholia]~/.emacs |
|
1548 |
This also edits the same file --- the @file{~} is expanded to your |
This also edits the same file --- the @file{~} is expanded to your |
1549 |
home directory on the remote machine, just like it is locally. |
home directory on the remote machine, just like it is locally. |
1550 |
|
|
1551 |
@item /melancholia:~daniel/.emacs |
@item @value{tramp-prefix}melancholia@value{tramp-postfix}~daniel/.emacs |
|
@itemx /[melancholia]~daniel/.emacs |
|
1552 |
This edits the file @file{.emacs} in the home directory of the user |
This edits the file @file{.emacs} in the home directory of the user |
1553 |
@code{daniel} on the machine @code{melancholia}. The @file{~<user>} |
@code{daniel} on the machine @code{melancholia}. The @file{~<user>} |
1554 |
construct is expanded to the home directory of that user on the remote |
construct is expanded to the home directory of that user on the remote |
1555 |
machine. |
machine. |
1556 |
|
|
1557 |
@item /melancholia:/etc/squid.conf |
@item @value{tramp-prefix}melancholia@value{tramp-postfix}/etc/squid.conf |
|
@itemx /[melancholia]/etc/squid.conf |
|
1558 |
This edits the file @file{/etc/squid.conf} on the machine |
This edits the file @file{/etc/squid.conf} on the machine |
1559 |
@code{melancholia}. |
@code{melancholia}. |
1560 |
|
|
1561 |
@end table |
@end table |
1562 |
|
|
1563 |
Unless you specify a different name to use, @tramp{} will use the current |
Unless you specify a different name to use, @tramp{} will use the |
1564 |
local user name as the remote user name to log in with. If you need to |
current local user name as the remote user name to log in with. If you |
1565 |
log in as a different user, you can specify the user name as part of the |
need to log in as a different user, you can specify the user name as |
1566 |
filename. |
part of the filename. |
1567 |
|
|
1568 |
On Emacs, to log in to the remote machine as a specific user, you use |
To log in to the remote machine as a specific user, you use the syntax |
1569 |
the syntax @file{/@var{user}@@@var{machine}:/path/to.file}. On |
@file{@value{tramp-prefix}@var{user}@@@var{machine}@value{tramp-postfix}/@var{path/to.file}}. |
1570 |
XEmacs, use @file{/[@var{user}@@@var{machine}]/path/to.file}. That |
That means that connecting to @code{melancholia} as @code{daniel} and |
|
means that connecting to @code{melancholia} as @code{daniel} and |
|
1571 |
editing @file{.emacs} in your home directory you would specify |
editing @file{.emacs} in your home directory you would specify |
1572 |
@file{/daniel@@melancholia:.emacs} on Emacs and |
@file{@value{tramp-prefix}daniel@@melancholia@value{tramp-postfix}.emacs}. |
|
@file{/[daniel@@melancholia].emacs} on XEmacs. |
|
|
|
|
1573 |
|
|
1574 |
It is also possible to specify other file transfer methods |
It is also possible to specify other file transfer methods |
1575 |
(@pxref{Default Method}) as part of the filename. On Emacs, this is |
(@pxref{Default Method}) as part of the filename. |
1576 |
done by puttig the method before the user and host name, as in |
@ifset emacs |
1577 |
@file{/@var{method}:} (note the trailing colon). On XEmacs, it is |
This is done by putting the method before the user and host name, as |
1578 |
done by replacing the initial @file{/[} with @file{/[<method>/}. |
in |
1579 |
(Note the trailing slash!) The user, machine and file specification |
@file{@value{tramp-prefix}@var{method}@value{tramp-postfix-single-hop}} |
1580 |
remain the same. |
(note the trailing colon). |
1581 |
|
@end ifset |
1582 |
|
@ifset xemacs |
1583 |
|
This is done by replacing the initial |
1584 |
|
@file{@value{tramp-prefix}} with |
1585 |
|
@file{@value{tramp-prefix}<method>@value{tramp-postfix-single-hop}}. |
1586 |
|
(Note the trailing slash!). |
1587 |
|
@end ifset |
1588 |
|
The user, machine and file specification remain the same. |
1589 |
|
|
1590 |
So, to connect to the machine @code{melancholia} as @code{daniel}, |
So, to connect to the machine @code{melancholia} as @code{daniel}, |
1591 |
using the @option{su} method to transfer files, and edit @file{.emacs} |
using the @option{su} method to transfer files, and edit @file{.emacs} |
1592 |
in my home directory I would specify the filename |
in my home directory I would specify the filename |
1593 |
@file{/su:daniel@@melancholia:.emacs} on Emacs and |
@file{@value{tramp-prefix}su@value{tramp-postfix-single-hop}daniel@@melancholia@value{tramp-postfix}.emacs}. |
|
@file{/[su/daniel@@melancholia].emacs} on XEmacs. |
|
1594 |
|
|
1595 |
|
|
1596 |
@node Multi-hop filename syntax |
@node Multi-hop filename syntax |
1599 |
@cindex multi-hop filename syntax |
@cindex multi-hop filename syntax |
1600 |
|
|
1601 |
The syntax of multi-hop file names is necessarily slightly different |
The syntax of multi-hop file names is necessarily slightly different |
1602 |
than the syntax of other @tramp{} file names. Here's an example multi-hop |
than the syntax of other @tramp{} file names. Here's an example |
1603 |
file name, first in Emacs syntax and then in XEmacs syntax: |
multi-hop file name, first in Emacs syntax and then in XEmacs syntax: |
1604 |
|
|
1605 |
@file{/multi:rsh:out@@gate:telnet:kai@@real.host:/path/to.file} |
@example |
1606 |
@file{/[multi/rsh:out@@gate/telnet:kai@@real.host]/path/to.file} |
@value{tramp-prefix}multi@value{tramp-postfix-single-hop}rsh@value{tramp-postfix-multi-hop}out@@gate@value{tramp-postfix-single-hop}telnet@value{tramp-postfix-multi-hop}kai@@real.host@value{tramp-postfix}/path/to.file |
1607 |
|
@end example |
1608 |
|
|
1609 |
This is quite a mouthful. So let's go through it step by step. The |
This is quite a mouthful. So let's go through it step by step. The |
1610 |
file name consists of three parts. On Emacs, the parts are separated |
file name consists of three parts. |
1611 |
by colons, on XEmacs they are separated by slashes and square |
@ifset emacs |
1612 |
brackets. The first part is @file{/multi:} (or @file{/[multi}), the |
The parts are separated by colons |
1613 |
method specification. The second part is |
@end ifset |
1614 |
@file{rsh:out@@gate:telnet:kai@@real.host} (or |
@ifset xemacs |
1615 |
@file{rsh:out@@gate/telnet:kai@@real.host}) and specifies the hops. |
The parts are separated by slashes and square brackets. |
1616 |
(Yes, on Emacs the second part may contain even more colons, so that's why |
@end ifset |
1617 |
this file name has more than two colons in it.) The final part is |
The first part is @file{@value{tramp-prefix}multi}, the method |
1618 |
@file{/path/to.file} and specifies the file name on the remote host. |
specification. The second part is |
1619 |
|
@file{rsh@value{tramp-postfix-multi-hop}out@@gate@value{tramp-postfix-single-hop}telnet@value{tramp-postfix-multi-hop}kai@@real.host} |
1620 |
|
and specifies the hops. The final part is @file{/path/to.file} and |
1621 |
|
specifies the file name on the remote host. |
1622 |
|
|
1623 |
The first part and the final part should be clear. @ref{Multi-hop |
The first part and the final part should be clear. @ref{Multi-hop |
1624 |
Methods}, for a list of alternatives for the method specification. |
Methods}, for a list of alternatives for the method specification. |
1625 |
|
|
1626 |
The second part can be subdivided again into components, so-called hops. |
The second part can be subdivided again into components, so-called |
1627 |
In the above file name, there are two hops, @file{rsh:out@@gate} and |
hops. In the above file name, there are two hops, |
1628 |
@file{telnet:kai@@real.host}. |
@file{rsh@value{tramp-postfix-multi-hop}out@@gate} and |
1629 |
|
@file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}. |
1630 |
|
|
1631 |
Each hop can @emph{again} be subdivided into (three) components, the |
Each hop can @emph{again} be subdivided into (three) components, the |
1632 |
@dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The |
@dfn{hop method}, the @dfn{user name} and the @dfn{host name}. The |
1633 |
meaning of the second and third component should be clear, and the hop |
meaning of the second and third component should be clear, and the hop |
1634 |
method says what program to use to perform that hop. |
method says what program to use to perform that hop. |
1635 |
|
|
1636 |
The first hop, @file{rsh:out@@gate}, says to use @command{rsh} to log in |
The first hop, @file{rsh@value{tramp-postfix-multi-hop}out@@gate}, |
1637 |
as user @code{out} to the host @code{gate}. Starting at that host, the |
says to use @command{rsh} to log in as user @code{out} to the host |
1638 |
second hop, @file{telnet:kai@@real.host}, says to use @command{telnet} |
@code{gate}. Starting at that host, the second hop, |
1639 |
to log in as user @code{kai} to host @code{real.host}. |
@file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}, says to |
1640 |
|
use @command{telnet} to log in as user @code{kai} to host |
1641 |
@xref{Multi-hop Methods}, for a list of possible hop method values. The |
@code{real.host}. |
1642 |
variable @var{tramp-multi-connection-function-alist} contains the list of |
|
1643 |
possible hop methods and information on how to execute them, should you |
@xref{Multi-hop Methods}, for a list of possible hop method values. |
1644 |
want to add your own. |
The variable @code{tramp-multi-connection-function-alist} contains the |
1645 |
|
list of possible hop methods and information on how to execute them, |
1646 |
|
should you want to add your own. |
1647 |
|
|
1648 |
|
|
1649 |
|
@node Filename completion |
1650 |
|
@section Filename completion |
1651 |
|
@cindex filename completion |
1652 |
|
|
1653 |
|
Filename completion works with @tramp{} for both completing methods, |
1654 |
|
user names and machine names (except multi hop methods) as well as for |
1655 |
|
files on remote machines. |
1656 |
|
|
1657 |
|
If you, for example, type @kbd{C-x C-f @value{tramp-prefix}t |
1658 |
|
@key{TAB}}, @tramp{} might give you as result the choice for |
1659 |
|
|
1660 |
|
@example |
1661 |
|
@ifset emacs |
1662 |
|
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop} tmp/ |
1663 |
|
@value{tramp-prefix-single-hop}toto@value{tramp-postfix} |
1664 |
|
@end ifset |
1665 |
|
@ifset xemacs |
1666 |
|
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop} @value{tramp-prefix-single-hop}toto@value{tramp-postfix} |
1667 |
|
@end ifset |
1668 |
|
@end example |
1669 |
|
|
1670 |
|
@samp{@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}} |
1671 |
|
is a possible completion for the respective method, |
1672 |
|
@ifset emacs |
1673 |
|
@samp{tmp/} stands for the directory @file{/tmp} on your local |
1674 |
|
machine, |
1675 |
|
@end ifset |
1676 |
|
and @samp{@value{tramp-prefix-single-hop}toto@value{tramp-postfix}} |
1677 |
|
might be a host @tramp has detected in your @file{~/.ssh/known_hosts} |
1678 |
|
file (given you're using default method @option{ssh}). |
1679 |
|
|
1680 |
|
If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to |
1681 |
|
@samp{@value{tramp-prefix}telnet@value{tramp-postfix-single-hop}}. |
1682 |
|
Next @kbd{@key{TAB}} brings you all machine names @tramp{} detects in |
1683 |
|
your @file{/etc/hosts} file, let's say |
1684 |
|
|
1685 |
|
@example |
1686 |
|
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}127.0.0.1@value{tramp-postfix} @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}192.168.0.1@value{tramp-postfix} |
1687 |
|
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}localhost@value{tramp-postfix} @value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}melancholia.danann.net@value{tramp-postfix} |
1688 |
|
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}melancholia@value{tramp-postfix} |
1689 |
|
@end example |
1690 |
|
|
1691 |
|
Now you can choose the desired machine, and you can continue to |
1692 |
|
complete file names on that machine. |
1693 |
|
|
1694 |
|
As filename completion needs to fetch the listing of files from the |
1695 |
|
remote machine, this feature is sometimes fairly slow. As @tramp{} |
1696 |
|
does not yet cache the results of directory listing, there is no gain |
1697 |
|
in performance the second time you complete filenames. |
1698 |
|
|
1699 |
|
If the configuration files (@pxref{Customizing Completion}), which |
1700 |
|
@tramp{} uses for analysis of completion, offer user names, those user |
1701 |
|
names will be taken into account as well. |
1702 |
|
|
1703 |
|
|
1704 |
@node Dired |
@node Dired |
1705 |
@section Dired and filename completion |
@section Dired |
1706 |
@cindex dired |
@cindex dired |
|
@cindex filename completion |
|
1707 |
|
|
1708 |
@tramp{} works transparently with dired, enabling you to use this powerful |
@tramp{} works transparently with dired, enabling you to use this powerful |
1709 |
file management tool to manage files on any machine you have access to |
file management tool to manage files on any machine you have access to |
1710 |
over the Internet. |
over the Internet. |
1711 |
|
|
|
Filename completion also works with @tramp{} for files on remote machines |
|
|
although there is no completion for user names or machine names at this |
|
|
stage. |
|
|
|
|
|
As filename completion needs to fetch the listing of files from the |
|
|
remote machine, this feature is sometimes fairly slow. As @tramp{} does not |
|
|
yet cache the results of directory listing, there is no gain in |
|
|
performance the second time you complete filenames. |
|
|
|
|
1712 |
If you need to browse a directory tree, Dired is a better choice, at |
If you need to browse a directory tree, Dired is a better choice, at |
1713 |
present, than filename completion. Dired has its own cache mechanism |
present, than filename completion. Dired has its own cache mechanism |
1714 |
and will only fetch the directory listing once. |
and will only fetch the directory listing once. |
1754 |
@item |
@item |
1755 |
Where can I get the latest @tramp{}? |
Where can I get the latest @tramp{}? |
1756 |
|
|
1757 |
@tramp{} is available at |
@tramp{} is available under the URL below. |
|
@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}. |
|
|
There is also a Savannah project page, at |
|
|
@uref{https://savannah.gnu.org/projects/tramp/}. |
|
1758 |
|
|
1759 |
|
@noindent |
1760 |
|
@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz} |
1761 |
|
|
1762 |
|
@noindent |
1763 |
|
There is also a Savannah project page. |
1764 |
|
|
1765 |
|
@noindent |
1766 |
|
@uref{https://savannah.gnu.org/projects/tramp/} |
1767 |
|
|
1768 |
@item |
@item |
1769 |
Which systems does it work on? |
Which systems does it work on? |
1798 |
@tramp{} installed. |
@tramp{} installed. |
1799 |
|
|
1800 |
If you do, please try and find out exactly the conditions required for |
If you do, please try and find out exactly the conditions required for |
1801 |
the @code{EFS} handlers to fire. If you can, putting a breakpoint on |
the EFS handlers to fire. If you can, putting a breakpoint on |
1802 |
@code{efs-ftp-path} and sending in the stack trace along with your bug |
@code{efs-ftp-path} and sending in the stack trace along with your bug |
1803 |
report would make it easier for the developers to work out what is going |
report would make it easier for the developers to work out what is |
1804 |
wrong. |
going wrong. |
1805 |
|
|
1806 |
|
|
1807 |
@item |
@item |
1900 |
@node Version Control |
@node Version Control |
1901 |
@chapter The inner workings of remote version control |
@chapter The inner workings of remote version control |
1902 |
|
|
1903 |
Unlike EFS and Ange-FTP, @tramp{} has full shell access to the remote |
Unlike @value{ftp-package-name}, @tramp{} has full shell access to the |
1904 |
machine. This makes it possible to provide version control for files |
remote machine. This makes it possible to provide version control for |
1905 |
accessed under @tramp{}. |
files accessed under @tramp{}. |
1906 |
|
|
1907 |
The actual version control binaries must be installed on the remote |
The actual version control binaries must be installed on the remote |
1908 |
machine, accessible in the directories specified in |
machine, accessible in the directories specified in |
1917 |
* Remote Commands:: Executing the version control commands on the remote machine. |
* Remote Commands:: Executing the version control commands on the remote machine. |
1918 |
* Changed workfiles:: Detecting if the working file has changed. |
* Changed workfiles:: Detecting if the working file has changed. |
1919 |
* Checking out files:: Bringing the workfile out of the repository. |
* Checking out files:: Bringing the workfile out of the repository. |
1920 |
* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere |
* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. |
1921 |
@end menu |
@end menu |
1922 |
|
|
1923 |
|
|
2123 |
@c * Make terminology "inline" vs "out-of-band" consistent. |
@c * Make terminology "inline" vs "out-of-band" consistent. |
2124 |
@c It seems that "external" is also used instead of "out-of-band". |
@c It seems that "external" is also used instead of "out-of-band". |
2125 |
|
|
2126 |
|
@c * M. Albinus |
2127 |
|
@c ** Use `filename' resp. `file name' consistently. |
2128 |
|
@c ** Use `host' resp. `machine' consistently. |
2129 |
|
@c ** Consistent small or capitalized words especially in menues. |