/[emacs]/emacs/man/tramp.texi
ViewVC logotype

Diff of /emacs/man/tramp.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.10 by eggert, Fri Aug 16 06:29:40 2002 UTC revision 1.11 by kai, Sun Sep 22 13:23:36 2002 UTC
# Line 8  Line 8 
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
# Line 21  Line 27 
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
# Line 66  license to the document, as described in Line 79  license to the document, as described in
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/}.
# Line 102  well as the usual Savannah archives. Line 118  well as the usual Savannah archives.
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 ---
# Line 128  Configuring @tramp{} for use Line 145  Configuring @tramp{} for use
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    
# Line 143  The inner workings of remote version con Line 163  The inner workings of remote version con
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    
# Line 157  How file names, directories and paths ar Line 177  How file names, directories and paths ar
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
# Line 229  what happens: Line 248  what happens:
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
# Line 254  If @tramp{} sees neither of them after a Line 274  If @tramp{} sees neither of them after a
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
# Line 293  For inline transfers, @tramp{} issues a Line 313  For inline transfers, @tramp{} issues a
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
# Line 314  I hope this has provided you with a basi Line 336  I hope this has provided you with a basi
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{}.
# Line 333  is the latest version of the code and ma Line 385  is the latest version of the code and ma
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)
# Line 349  CVS password: @strong{(just hit RET here Line 406  CVS password: @strong{(just hit RET here
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    
# Line 378  filenames in July 2002. Line 436  filenames in July 2002.
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
# Line 490  site}.) Line 559  site}.)
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).
# Line 513  can use to connect to remote machines an Line 582  can use to connect to remote machines an
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.
# Line 541  differ. Line 611  differ.
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
# Line 643  There are also two variants, @option{sm- Line 713  There are also two variants, @option{sm-
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
# Line 776  rather than @command{su} to become a dif Line 846  rather than @command{su} to become a dif
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
# Line 901  The cost of the cryptographic handshake Line 971  The cost of the cryptographic handshake
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}.
# Line 1097  also be accomplished within Tramp, by ad Line 1167  also be accomplished within Tramp, by ad
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    
# Line 1175  For the time being, I'll refer you to th Line 1246  For the time being, I'll refer you to th
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    
# Line 1209  found. Line 1379  found.
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
# Line 1228  as: Line 1398  as:
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
# Line 1270  suppose your shell prompt is @code{a <b> Line 1440  suppose your shell prompt is @code{a <b>
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    
# Line 1317  to as though they were local. Line 1501  to as though they were local.
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    
# Line 1332  by the @command{EFS} and @command{Ange-F Line 1527  by the @command{EFS} and @command{Ange-F
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
# Line 1413  in my home directory I would specify the Line 1599  in my home directory I would specify the
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.
# Line 1516  development team to analyze and correct Line 1754  development team to analyze and correct
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?
# Line 1555  first thing to do is to make sure that y Line 1798  first thing to do is to make sure that y
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
# Line 1657  fi Line 1900  fi
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
# Line 1674  Work is ongoing to improve the transpare Line 1917  Work is ongoing to improve the transpare
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    
# Line 1880  would have to be installed from the star Line 2123  would have to be installed from the star
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.

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26