comparison man/tramp.texi @ 47576:b31c8ab7336a

Sync with version 2.0.20. Lengthy ChangeLog follows: 2002-09-22 Kai Gro?ohann <[e-mail]> Version 2.0.20 released. 2002-09-20 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-completion-function-alist): Escape open paren in docstring. (tramp-user-regexp, tramp-host-regexp): Allow empty strings. (tramp-handle-insert-file-contents): Call tramp-message-for-buffer instead of tramp-message. (tramp-open-connection-rsh): Handle empty string as user name. (tramp-open-connection-su): Handle empty string as host name. Handle nil user name. (tramp-handle-file-local-copy, tramp-handle-write-region) (tramp-completion-handle-file-name-all-completions) (tramp-open-connection-telnet, tramp-open-connection-rsh) (tramp-open-connection-su, tramp-post-connection) (tramp-maybe-open-connection, tramp-method-out-of-band-p) (tramp-get-connection-function, tramp-get-remote-sh) (tramp-get-rsh-program, tramp-get-rsh-args) (tramp-get-rcp-program, tramp-get-rcp-args) (tramp-get-rcp-keep-date-arg, tramp-get-su-program) (tramp-get-su-args, tramp-get-telnet-program) (tramp-get-telnet-args): Use `tramp-find-method', perhaps require additional args USER, HOST. (tramp-action-password, tramp-open-connection-telnet) (tramp-open-connection-su, tramp-open-connection-multi) (tramp-method-out-of-band-p): `tramp-method-out-of-band-p' now takes USER and HOST arguments, to be able to use `tramp-find-method'. Update callers. (tramp-find-method): New function. 2002-09-20 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-handle-insert-directory): Handle "--dired" in SWITCHES (by removing it). 2002-09-18 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-file-name-handler): Add `file-remote-p' property. 2002-09-17 Kai Gro?ohann <[e-mail]> * net/tramp.el (top-level): Maybe autoload uudecode-decode-region. 2002-09-16 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-bug): Add tramp-methods. 2002-09-16 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-methods): Update docstring: tramp-encoding-command, tramp-decoding-command, tramp-encoding-function and tramp-decoding-function are not parameters anymore. (tramp-uuencode-region): Autoload it. 2002-09-13 Kai Gro?ohann <[e-mail]> Version 2.0.19 released. * net/tramp-uu.el: New file, implements uuencode in Lisp. * net/tramp.el (tramp-coding-commands): Use `tramp-uuencode-region' as local encoder for the uuencode based entries. 2002-09-13 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-handle-write-region): Wrong parens. 2002-09-13 Kai Gro?ohann <[e-mail]> Version 2.0.18 released. * net/tramp.el (tramp-perl-decode): Perl changes to accomodate older versions of Perl. Now tested with 5.004. Suggestion from Michael Albinus. 2002-09-12 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-find-inline-encoding): Call tramp-call-local-coding-command with nil for INPUT and OUTPUT. (tramp-call-local-coding-command): OUTPUT equals nil means to discard the output. INPUT equals nil means /dev/null. 2002-09-12 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-encoding-shell): Default to environment variable COMSPEC on Windows. (tramp-handle-write-region): More debugging output. (tramp-find-inline-encoding): Ditto. 2002-09-11 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-handle-file-name-all-completions): Define `result1'. (tramp-parse-hosts-group): Discard IPv6 entries. 2002-09-11 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-post-connection): Only send Perl mime-encode/decode implementations when using inline method. (tramp-handle-file-local-copy) (tramp-handle-write-region, tramp-post-connection) (tramp-coding-commands, tramp-find-inline-encoding): For the inline encodings, distinguish between local and remote commands, instead of between commands and functions. (The local commands can be functions, too.) If the local host is a Windows machine, we can't expect the same commands to work there as on the remote host. (tramp-call-local-coding-command): New function for calling local encoding and decoding commands. (tramp-set-remote-encoding, tramp-get-remote-encoding) (tramp-set-remote-decoding, tramp-get-remote-decoding) (tramp-set-local-encoding, tramp-get-local-encoding) (tramp-set-local-decoding, tramp-get-local-decoding): New functions. (tramp-get-encoding-command, tramp-set-encoding-command) (tramp-get-decoding-command, tramp-set-decoding-command) (tramp-get-encoding-function, tramp-set-encoding-function) (tramp-get-decoding-function, tramp-set-decoding-function): Old functions, removed. 2002-09-10 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-open-connection-setup-interactive-shell): Change command to invoke /bin/sh slightly to make it compatible with the `rc' shell. Suggested by Daniel Pittman. 2002-09-10 Michael Albinus <[e-mail]> * net/tramp.el (tramp-handle-write-region): Added missing `)'. Hope it's the right place. 2002-09-09 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-open-connection-setup-interactive-shell): Do "exec env PS1='$ ' /bin/sh" instead of just "exec /bin/sh" in order to get a sane shell prompt. If people have ${CWD}, say, in their shell prompt, then the default login shell might display something harmless, but the /bin/sh will display a dollar sign which confused the subsequent prompt recognition. (tramp-multi-action-password): More debugging output. (tramp-encoding-shell): Renamed from tramp-sh-program. More documentation. Default to cmd.exe on Windows NT. (tramp-encoding-command-switch): New variable. Use instead of hard-wired "-c" which is only good for /bin/sh. (tramp-encoding-reads-stdin): New variable. If t, commands are called like "/bin/sh -c COMMAND <INPUT", if nil, they are called like "/bin/sh -c COMMAND INPUT", ie the input file is the last argument. (tramp-multi-sh-program): Always default to tramp-encoding-shell. (tramp-handle-file-local-copy, tramp-handle-write-region): Respect tramp-encoding-shell and friends. (tramp-find-inline-encoding): Use new-style calls for checking if the local commands work. 2002-09-07 Michael Albinus <[e-mail]> * net/tramp.el (tramp-methods): Remove `tramp-completion-function' entries. They are handled now by `tramp-completion-function-alist'. (tramp-completion-function): Defvar removed. I've never used it. Hmm. (tramp-get-completion-function) (tramp-get-completion-rsh, tramp-get-completion-ssh) (tramp-get-completion-telnet, tramp-get-completion-su): Functions removed as well. Not necessary any longer due to extended customization means. (tramp-completion-function-alist): New defcustom. Holds all FUNCTION FILE pairs used for user and host name completion relevant for METHOD. (tramp-completion-function-alist-rsh) (tramp-completion-function-alist-ssh) (tramp-completion-function-alist-telnet) (tramp-completion-function-alist-su): Defconst for initializing `tramp-completion-function-alist'. Unfortunately, mainly UNIX-like values are known for me until now. Needs to be completed for at least VMS++ like operating systems. (tramp-set-completion-function) (tramp-get-completion-function): New functions for configuration of `tramp-completion-function-alist'. The old definition of `tramp-get-completion-function' has been discarded. (tramp-completion-handle-file-name-all-completions): Change function call for user/host completion according to definition in `tramp-completion-function-alist'. (tramp-parse-passwd): Added exception handling for "root", because `tramp-get-completion-su' (the previous place for this stuff) doesn't exist any longer. 2002-09-07 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-enter-password): Use `tramp-password-end-of-line' to terminate the line. (tramp-bug): Include new variable `tramp-password-end-of-line'. (tramp-password-end-of-line): New variable. People who use plink under Windows might have to issue "\r\n" after the password, but they need to send just "\n" after the other commands. So this variable was introduced to complement `tramp-rsh-end-of-line'. (tramp-wait-for-output, tramp-post-connection): Allow "\r" at end of line of the output delimiter. 2002-09-06 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-handle-file-local-copy, tramp-find-shell) (tramp-open-connection-setup-interactive-shell): Add some comments about Douglas Grey Stephen's suggestions to make Tramp work better with plink under Windows. I'm not sure what to think of them, but now I have a guinea pig to try it out on. Said guinea pig is having other problems, though... Also remove some commented-out code. 2002-09-06 Michael Albinus <[e-mail]> * net/tramp.el (tramp-get-completion-methods): Algorithm slightly tuned. (tramp-get-completion-user-host): Accept user names as they are if typed until "@". (tramp-completion-mode): Replace `last-input-char' by modern `last-input-event'. Check for `event-modifiers'. 2002-09-06 Kai Gro?ohann <[e-mail]> * net/tramp.el (file-expand-wildcards): Corrected check to see if advising is necessary. 2002-09-05 Michael Albinus <[e-mail]> * net/tramp.el (tramp-postfix-single-method-format) (tramp-postfix-multi-method-format) (tramp-postfix-multi-hop-format) (tramp-postfix-user-format): New format strings. (tramp-postfix-single-method-regexp) (tramp-postfix-multi-method-regexp) (tramp-postfix-multi-hop-regexp) (tramp-postfix-user-regexp) (tramp-make-multi-tramp-file-format) (tramp-make-tramp-file-name): Apply them. (tramp-completion-handle-file-name-all-completions): Fix for invoking ange-ftp in case of "/ftp:xxx" file names. 2002-09-04 Michael Albinus <[e-mail]> * net/tramp.el (tramp-prefix-format) (tramp-postfix-host-format): New format strings. (tramp-prefix-regexp, tramp-method-regexp) (tramp-postfix-single-method-regexp) (tramp-postfix-multi-method-regexp) (tramp-postfix-multi-hop-regexp) (tramp-user-regexp, tramp-postfix-user-regexp) (tramp-host-regexp, tramp-postfix-host-regexp) (tramp-path-regexp): New atomar regular expressions. If corresponding format strings exist, derived from them. (tramp-file-name-structure) (tramp-multi-file-name-structure) (tramp-multi-file-name-hop-structure) (tramp-make-multi-tramp-file-format) (tramp-completion-mode) (tramp-completion-dissect-file-name) (tramp-parse-rhosts-group) (tramp-parse-shosts-group) (tramp-parse-hosts-group) (tramp-parse-passwd-group): Apply these expressions. (tramp-file-name-structure-unified) (tramp-file-name-structure-separate) (tramp-make-tramp-file-format-unified) (tramp-make-tramp-file-format-separate) (tramp-make-tramp-file-format) (tramp-make-tramp-file-user-nil-format-unified) (tramp-make-tramp-file-user-nil-format-separate) (tramp-make-tramp-file-user-nil-format) (tramp-multi-file-name-structure-unified) (tramp-multi-file-name-structure-separate) (tramp-multi-file-name-hop-structure-unified) (tramp-multi-file-name-hop-structure-separate) (tramp-make-multi-tramp-file-format-unified) (tramp-make-multi-tramp-file-format-separate): Removed. (tramp-make-tramp-file-name): Allow partial tramp file names. Generate tramp file format on-the-fly depending on parameters. Apply atomar format strings resp expressions. (tramp-get-completion-methods) (tramp-get-completion-user-host): Apply `tramp-make-tramp-file-name'. (tramp-parse-hosts-group): Take all host names and IP addresses into account. (tramp-bug): Remove `tramp-make-tramp-file-format'. 2002-09-01 Michael Albinus <[e-mail]> * net/tramp.el (tramp-methods): Add `tramp-completion-function' for "su" and "sudo". (tramp-get-completion-telnet): Implement it. (tramp-parse-hosts) (tramp-parse-hosts-group) (tramp-get-completion-su) (tramp-parse-passwd) (tramp-parse-passwd-group): New functions. 2002-08-31 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-mode): Check for `last-input-char'. (tramp-completion-file-name-handler-alist): Add handler for `file-exists-p. (tramp-completion-handle-file-exists-p): New function. (tramp-completion-handle-file-name-completion): Simplified. (tramp-completion-dissect-file-name): Regexp's reorganised. (tramp-completion-handle-file-name-all-completions): Call completion-function only if `user' or `host' is given. (tramp-get-completion-user-host): New function. (tramp-get-completion-rsh) (tramp-get-completion-ssh): Apply it. 2002-08-29 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-file-name-handler-alist): Add handler for `expand-file-name'. (tramp-completion-handle-expand-file-name): New function. 2002-08-26 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-mode): New function. (tramp-completion-handle-file-name-directory) (tramp-completion-handle-file-name-all-completions): Apply it. (tramp-methods): Remove double definition of `ssh1-old' and `ssh2-old'. (tramp-point-at-eol): New defalias. (tramp-parse-rhosts-group) (tramp-parse-shosts-group):: Apply it. 2002-08-25 Michael Albinus <[e-mail]> * net/tramp.el (tramp-get-completion-methods) (tramp-get-completion-rsh) (tramp-get-completion-ssh): Add "[" for Xemacs. (tramp-completion-file-name-regexp-separate): Expression adapted. (tramp-completion-file-name-handler-alist): Add handler for `file-name-directory' and `file-name-nondirectory'. (tramp-completion-handle-file-name-directory) (tramp-completion-handle-file-name-nondirectory) (tramp-completion-run-real-handler): New functions. (tramp-completion-file-name-handler) (tramp-completion-handle-file-name-all-completions): Apply `tramp-completion-run-real-handler'. (tramp-parse-rhosts) (tramp-parse-shosts): Use `with-temp-buffer'. `result? renamed to `res' (otherwise side effects in XEmacs). 2002-08-24 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-file-name-regexp) (tramp-completion-file-name-handler-alist) (tramp-flatten-list) (tramp-completion-dissect-file-name) (tramp-get-completion-rsh) (tramp-parse-rhosts) (tramp-parse-rhosts-group) (tramp-get-completion-ssh): Doc string tuned. (tramp-methods): Doc string and custom type extended for `tramp-completion-function'. (tramp-completion-function): Variable added. Is it really used? Other variables like `tramp-completion-function' aren't used. (tramp-completion-file-name-handler-alist): Add handler for `file-name-completion'. (tramp-completion-handle-file-name-completion): New function. 2002-08-18 Michael Albinus <[e-mail]> * net/tramp.el (tramp-parse-rhosts) (tramp-parse-rhosts-group) (tramp-parse-shosts) (tramp-parse-shosts-group): New functions. 2002-08-17 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-dissect-file-name) (tramp-completion-dissect-file-name1): New functions. 2002-08-16 Michael Albinus <[e-mail]> * net/tramp.el (tramp-get-completion-function) (tramp-get-completion-rsh) (tramp-get-completion-ssh) (tramp-get-completion-telnet): New functions. (tramp-methods): Add `tramp-completion-function' for all methods. 2002-08-15 Michael Albinus <[e-mail]> * net/tramp.el (tramp-get-completion-methods): New function. (tramp-find-default-method): Allow host to be nil (like user). 2002-08-14 Michael Albinus <[e-mail]> * net/tramp.el (tramp-completion-file-name-regexp-unified) (tramp-completion-file-name-regexp-separate) (tramp-completion-file-name-regexp) (tramp-completion-file-name-handler-alist): New defcustoms. (tramp-completion-file-name-handler): New function. Add `tramp-completion-file-name-handler' to `file-name-handler-alist'. (tramp-run-real-handler): Add `tramp-completion-file-name-handler' to `inhibit-file-name-handlers'. (tramp-completion-handle-file-name-all-completions) (tramp-completion-handle-file-name-completion): New functions. 2002-08-12 Michael Albinus <[e-mail]> * net/tramp.el (tramp-invoke-ange-ftp): `tramp-disable-ange-ftp' must be called again after activating `ange-ftp'. (tramp-ange-ftp-file-name-p): Check for Xemacs. 2002-08-08 Michael Albinus <[e-mail]> * net/tramp.el (tramp-do-copy-or-rename-file): Don't pass KEEP-DATE to tramp-invoke-ange-ftp 'rename. (tramp-handle-write-region): Don't pass LOCKNAME and CONFIRM to tramp-invoke-ange-ftp 'write-region. (tramp-handle-set-file-modes): Change order of FILENAME and MODE passing to tramp-invoke-ange-ftp 'set-file-modes. (tramp-flatten-list): New function. Maybe this functionality does exist already elsewhere in the libraries. (tramp-invoke-ange-ftp): Apply `tramp-flatten-list' to parameter list in order to avoid nested lists, f.e. when invoked from `tramp-handle-dired-call-process'. 2002-09-05 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-chunksize): New kluge variable. (tramp-send-region): If tramp-chunksize is non-nil, send region in parts and sleep 0.1 seconds between chunks. 2002-09-03 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-handle-insert-directory): Use `insert-buffer-substring' instead of `insert-buffer', which is not supposed to be used from Lisp. Remember old point in a variable instead of using `mark'. Suggestion from Stefan Monnier. (tramp-unified-filenames): New variable. Use it in default value of other filename variables. (file-expand-wildcards): Don't advise unless "[" and "]" are used in the filename format. 2002-09-01 Kai Gro?ohann <[e-mail]> * net/tramp.el (tramp-methods): Remove duplicate definition of ssh1-old and ssh2-old.

47575:4d9f899a5963

@c %**end of header

@c This is *so* much nicer :)
@footnotestyle end


@c Entries for @command{install-info} to use
@dircategory Emacs
@direntry
* TRAMP: (tramp).                Transparent Remote Access, Multiple Protocol

@c Macro to make formatting of the tramp program name consistent.
@macro tramp
@sc{tramp}
@end macro

@c Copying permissions, et al
@copying
This file documents @tramp{}, a remote file editing package for Emacs and
XEmacs.
     
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software
Foundation, Inc.

@quotation     
Permission is granted to copy, distribute and/or modify this document

license to the document, as described in section 6 of the license.
@end quotation
@end copying


@tex

@titlepage
@title @tramp{} User Manual

@author by Daniel Pittman
@author based on documentation by Kai Gro@ss{}johann
@page

@end titlepage
@page

@end tex

@ifnottex
@node Top, Overview, (dir), (dir)
@top @tramp{} User Manual

@tramp{} stands for `Transparent Remote (file) Access, Multiple
Protocol'.  This package provides remote file editing, similar to
@cite{Ange-FTP} and @cite{EFS}.

The difference is that Ange-FTP uses FTP to transfer files between the
local and the remote host, whereas @tramp{} uses a combination of
@command{rsh} and @command{rcp} or other work-alike programs, such as
@command{ssh}/@command{scp}.

You can find the latest version of this document on the web at
@uref{http://www.freesoftware.fsf.org/tramp/}.

@ifhtml
This manual is also available as a @uref{tramp_ja.html, Japanese
translation}.

The latest release of @tramp{} is available for
@uref{http://savannah.gnu.org/download/tramp/,
download}, or you may see @ref{Obtaining @tramp{}} for more details,
including the CVS server details.

@tramp{} also has a @uref{https://savannah.gnu.org/projects/tramp/,
Savannah Project Page}.
@end ifhtml

There is a mailing list for @tramp{}, available at
@email{tramp-devel@@mail.freesoftware.fsf.org}, and archived at
@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/} as
well as the usual Savannah archives.

@end ifnottex

@menu
* Overview::                    What @tramp{} can and cannot do.

For the end user:
* Obtaining @tramp{}::          How to obtain @tramp{}.
* History::                     History of @tramp{}
* Installation::                Installing @tramp{} with your (X)Emacs.
* Configuration::               Configuring @tramp{} for use.
* Usage::                       An overview of the operation of @tramp{}.
* Bug Reports::                 Reporting Bugs and Problems
* Frequently Asked Questions::  Questions and answers from the mailing list.

For the developer:
* Version Control::             The inner workings of remote version control.
* Files directories and paths::  How file names, directories and paths are mangled and managed.
* Issues::                      

@detailmenu
 --- The Detailed Node Listing ---

Configuring @tramp{} for use

* Connection types::            Types of connections made to remote machines.
* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
* Customizing Methods::         Using Non-Standard Methods.
* Remote Programs::             How @tramp{} finds and uses programs on the remote machine.
* Remote shell setup::          

Using @tramp

* Filename Syntax::             @tramp{} filename conventions.
* Multi-hop filename syntax::   Multi-hop filename conventions
* Dired::                       Dired and filename completion.

The inner workings of remote version control

* Version Controlled Files::    Determining if a file is under version control.
* Remote Commands::             Executing the version control commands on the remote machine.
* Changed workfiles::           Detecting if the working file has changed.
* Checking out files::          Bringing the workfile out of the repository.
* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere

Things related to Version Control that don't fit elsewhere

* Remote File Ownership::       How VC determines who owns a workfile.
* Back-end Versions::           How VC determines what release your RCS is.

How file names, directories and paths are mangled and managed.

* Path deconstruction::         Breaking a path into its components.

@end detailmenu
@end menu


@node Overview
@chapter An overview of @tramp
@cindex overview

After the installation of @tramp{} into your Emacs, you will be able
to access files on remote machines as though they were local.  Access
to the remote file system for editing files, version control, and
@command{dired} are transparently enabled.

Your access to the remote machine can be with the @command{rsh},
@command{rlogin}, @command{telnet} programs or with any similar
connection method.  This connection must pass ASCII successfully to be
usable but need not be 8-bit clean.

The package provides support for @command{ssh} connections out of the
box, one of the more common uses of the package.  This allows
relatively secure access to machines, especially if @command{ftp}
access is disabled.

The majority of activity carried out by @tramp{} requires only that
the remote login is possible and is carried out at the terminal.  In
order to access remote files @tramp{} needs to transfer their content
to the local machine temporarily.

@tramp{} can transfer files between the machines in a variety of ways.
The details are easy to select, depending on your needs and the
machines in question.

The fastest transfer methods (for large files) rely on a remote file
transfer package such as @command{rcp}, @command{scp} or
@command{rsync}.  The use of these methods is only possible if the
file copy command does not ask for a password for the remote machine.

If the remote copy methods are not suitable for you, @tramp{} also
supports the use of encoded transfers directly through the shell.
This requires that the @command{mimencode} or @command{uuencode} tools
are available on the remote machine.  These methods are generally
faster for small files.

Within these limitations, @tramp{} is quite powerful.  It is worth
noting that, as of the time of writing, it is far from a polished
end-user product.  For a while yet you should expect to run into rough
edges and problems with the code now and then.

It is finished enough that the developers use it for day to day work but
the installation and setup can be a little difficult to master, as can
the terminology.

@tramp{} is still under active development and any problems you encounter,
trivial or major, should be reported to the @tramp{} developers.
@xref{Bug Reports}.


@subsubheading Behind the scenes
@cindex behind the scenes
@cindex details of operation
@cindex how it works

This section tries to explain what goes on behind the scenes when you
access a remote file through @tramp{}.

Suppose you type @kbd{C-x C-f} and enter part of an @tramp{} file name,
then hit @kbd{@key{TAB}} for completion.  Suppose further that this is
the first time that @tramp{} is invoked for the host in question.  Here's
what happens:

@itemize
@item
@tramp{} discovers that it needs a connection to the host.  So it
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
@var{user}} or a similar tool to connect to the remote host.
Communication with this process happens through an Emacs buffer, that
is, the output from the remote end goes into a buffer.

@item
The remote host may prompt for a login name (for @command{telnet}).  The
login name is given in the file name, so @tramp{} sends the login name and
a newline.

@item
The remote host may prompt for a password or pass phrase (for
@command{rsh} or for @command{telnet} after sending the login name).
@tramp{} displays the prompt in the minibuffer, asking you for the
password or pass phrase.

You enter the password or pass phrase.  @tramp{} sends it to the remote
host, followed by a newline.

@item
@tramp{} now waits for the shell prompt or for a message that the login
failed.

If @tramp{} sees neither of them after a certain period of time (a minute,
say), then it issues an error message saying that it couldn't find the
remote shell prompt and shows you what the remote host has sent.

If @tramp{} sees a `login failed' message, it tells you so, aborts the
login attempt and allows you to try again.

@item
Suppose that the login was successful and @tramp{} sees the shell prompt
from the remote host.  Now @tramp{} invokes @command{/bin/sh} because
Bourne shells and C shells have different command
syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
shell doesn't recognize @samp{exec /bin/sh} as a valid command.
Maybe you use the Scheme shell @command{scsh}@dots{}}

After the Bourne shell has come up, @tramp{} sends a few commands to
ensure a good working environment.  It turns off echoing, it sets the
shell prompt, and a few other things.

@item
Now the remote shell is up and it good working order.  Remember, what
was supposed to happen is that @tramp{} tries to find out what files exist
on the remote host so that it can do filename completion.

So, @tramp{} basically issues @command{cd} and @command{ls} commands and
also sometimes @command{echo} with globbing.  Another command that is
often used is @command{test} to find out whether a file is writable or a
directory or the like.  The output of each command is parsed for the
necessary operation.

@item
Suppose you are finished with filename completion, have entered @kbd{C-x
C-f}, a full file name and hit @kbd{@key{RET}}.  Now comes the time to
transfer the file contents from the remote host to the local host so
that you can edit them.

See above for an explanation of how @tramp{} transfers the file contents.

For inline transfers, @tramp{} issues a command like @samp{mimencode -b
/path/to/remote/file}, waits until the output has accumulated in the
buffer that's used for communication, then decodes that output to
produce the file contents.

For out-of-band transfers, @tramp{} issues a command like @samp{rcp
user@@host:/path/to/remote/file /tmp/tramp.4711} and then reads the local
temporary file @file{/tmp/tramp.4711} into a buffer and deletes the
temporary file.

@item
You now edit the buffer contents, blithely unaware of what has happened
behind the scenes.  (Unless you have read this section, that is.)  When
you are finished, you type @kbd{C-x C-s} to save the buffer.

@item
Again, @tramp{} transfers the file contents to the remote host either
inline or out-of-band.  This is the reverse of what happens when reading
the file.

@end itemize

I hope this has provided you with a basic overview of what happens
behind the scenes when you open a file with @tramp{}.


@c For the end user
@node Obtaining @tramp{}
@chapter Obtaining @tramp{}.
@cindex obtaining Tramp

For the especially brave, @tramp{} is available from CVS.  The CVS version
is the latest version of the code and may contain incomplete features or
new issues. Use these versions at your own risk.

Instructions for obtaining the latest development version of @tramp{}
from CVS can be found by going to the Savannah project page at
@uref{http://savannah.gnu.org/projects/tramp/} and then clicking on the
CVS link in the navigation bar at the top.  Or follow the example
session below:

@example
] @strong{cd ~/lisp}
] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login}

(Logging in to anoncvs@@subversions.gnu.org)
CVS password: @strong{(just hit RET here)}
@dots{}

] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp}
@end example

You should now have a directory @file{~/lisp/tramp} containing the latest
version of @tramp{}. You can fetch the latest updates from the repository
by issuing the command:

@example
] @strong{cd ~/lisp/tramp}
] @strong{cvs update -d}
@end example


@node History

added in April 2000 and the unification of @tramp{} and Ange-FTP
filenames in July 2002.


@node Installation
@chapter Installing @tramp{} into Emacs or XEmacs
@cindex installation

If you use the version that comes with your Emacs or the XEmacs
package, the following information is not necessary.  Installing
@tramp{} into your Emacs or XEmacs is a relatively easy process, at
least compared to rebuilding your machine from scratch. ;)

Seriously though, the installation should be a fairly simple matter.

The easiest way to proceed is as follows:

@itemize
@item
Choose a directory, say @file{~/emacs/}.  Change into that directory and
unpack the tarball.  This will give you a directory
@file{~/emacs/tramp/} which contains subdirectories @file{lisp} for the
Lisp code and @file{texi} for the documentation.

@item
Optionally byte-compile all files in the Lisp directory,
@file{~/emacs/tramp/lisp/}, by issuing a command like the following from
the top level directory @file{~/emacs/tramp/}:
@example
make EMACS=emacs all            # for Emacs users
make EMACS=xemacs all           # for XEmacs users
@end example

@item
NOTE:
@example
If you run into problems running the example @command{make}
commands, don't dispare.  You can still byte compile the
@file{*.el} files by opening emacs in @command{dired}
(@command{C-x d}) mode, at @file{~/tramp/lisp}.  Mark the lisp
files with @kbd{m}, then press @kbd{B} to byte compile
your selections.

Something similar can be done to create the info manual.  
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     

@item
Tell Emacs about the new Lisp directory and the @tramp{} package 
with the following lines in @file{~/.emacs}:
@lisp
(add-to-list 'load-path "~/emacs/tramp/lisp/")
(require 'tramp)
@end lisp

@item
To be able to read the Info documentation, create a file
@file{~/emacs/tramp/texi/dir} using for example the
@command{install-info} command, and add the directory to the search 
path for Info.

@item
NOTE:
@example
On systems using `gnu' @command{install-info}, the
@command{install-info} syntax is very direct and simple.  One can 
cd to @file{~/emacs/tramp/texi} and type:
    @kbd{install-info tramp.info dir}
and a @file{dir} file will be created with the @tramp{}
entry.  The info reader will know how to interpret it, but must
be told where to find it (see below).  If you want anything fancier
you'll need to look through @kbd{man install-info}.

Debian gnu/linux doesn't default to `gnu' @command{install-info} and
uses its own version.  This version does not create a @file{dir} file
for you from scratch.  You must provide a skeleton dir file it
recognizes.  One can be found in a default install at
@file{/usr/info/dir}.  Copy the top of this file down to the first
occurrence of `* Menu' including that line plus one more blank line,
to your working directory @file{texi/dir}, or use the sample provided
in the @file{texi} directory of this distribution.  See
@file{texi/dir_sample}

Once a @file{dir} file is in place, this command will make the entry.
     install-info --infodir=. tramp.info
If you want it in a specific category
   (see @kbd{man install-info} for further details)
@end example

If the environment variable @env{INFOPATH} is set, add the directory
@file{~/emacs/tramp/texi/} to it.  Else, add the directory to
@code{Info-default-directory-list}, as follows:
@lisp
(add-to-list 'Info-default-directory-list "~/emacs/tramp/texi/")
@end lisp
XEmacs 21 users should use @code{Info-directory-list} rather than
@code{Info-default-directory-list}.

@end itemize


For XEmacs users, the package @file{fsf-compat} must be installed.
For details on package installation, see @ref{Packages, , ,xemacs}.
@ifhtml
(If the previous link doesn't work, try the XEmacs documentation at
@uref{http://www.xemacs.org/Documentation/packageGuide.html,the XEmacs
site}.)
@end ifhtml

@node Configuration
@chapter Configuring @tramp{} for use
@cindex configuration

@cindex default configuration
@tramp{} is (normally) fully functional when it is initially
installed.  It is initially configured to use the @command{sh} program
to connect to the remote host and to use base-64 encoding (on the
remote host, via @command{mimencode}, and on the local host via the
built-in support for base-64 encoding in Emacs).

On some hosts, there are problems with opening a connection.  These are

* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
* Customizing Methods::         Using Non-Standard Methods.
* Remote Programs::             How @tramp{} finds and uses programs on the remote machine.
* Remote shell setup::          Remote shell setup hints.
* Windows setup hints::         Issues with Cygwin ssh.
@end menu

@cindex out-of-band methods
@cindex methods, inline
@cindex methods, external transfer
@cindex methods, out-of-band
Loading or saving a remote file requires that the content of the file
be transferred between the two machines. The content of the file can be
transferred over the same connection used to log in to the remote
machine or the file can be transferred through another connection using
a remote copy program such as @command{rcp}, @command{scp} or
@command{rsync}.  The former are called @dfn{inline methods}, the
latter are called @dfn{out-of-band methods} or @dfn{external transfer
methods} (@dfn{external methods} for short).

There are also two variants, @option{sm-ssh1} and @option{sm-ssh2}
that use the @command{ssh1} and @command{ssh2} commands explicitly. If
you don't know what these are, you do not need these options.

All the methods based on @command{ssh} have an additional kludgey
feature: you can specify a host name which looks like @file{host#42}
(the real host name, then a hash sign, then a port number).  This
means to connect to the given host but to also pass @code{-p 42} as
arguments to the @command{ssh} command.

@cindex Cygwin (with smx method)

As you expect, this is similar to @option{sm}, only a little
different.  Whereas @option{sm} opens a normal interactive shell on
the remote host, this option uses @samp{ssh -t -t @var{host} -l
@var{user} /bin/sh} tp open a connection.  This is useful for users
where the normal login shell is set up to ask them a number of
questions when logging in.  This procedure avoids these questions, and
just gives @tramp{} a more-or-less `standard' login shell to work
with.

the inline methods when you often open and close small files however.
The cost of the cryptographic handshake at the start of an @command{scp}
session can begin to absorb the advantage that the lack of encoding and
decoding presents.

All the @command{ssh} based methods support the kludgey @samp{-p}
feature where you can specify a port number to connect to in the host
name.  For example, the host name @file{host#42} tells Tramp to
specify @samp{-p 42} in the argument list for @command{ssh}.

specifies a different port number for a certain host name.  But it can
also be accomplished within Tramp, by adding a multi-hop method.  For
example:

@lisp
(add-to-list 'tramp-multi-connection-function-alist
             '("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n"))
@end lisp

Now you can use a @code{sshf} hop which connects to port 4400 instead of
the standard port.


@node Default Method
@section Selecting a default method

For the time being, I'll refer you to the Lisp documentation of that
variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.


@node Remote Programs
@section How @tramp{} finds and uses programs on the remote machine.

@tramp{} depends on a number of programs on the remote host in order to
function, including @command{ls}, @command{test}, @command{find} and

found.

To add a directory to the remote search path, you could use code such
as:

@example
(require 'tramp)                @i{; @tramp{} must be loaded before this}
                                @i{; happens.}

@i{; We have @command{perl} in "/usr/local/perl/bin"}
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end example

@node Remote shell setup
@comment  node-name,  next,  previous,  up
@section Remote shell setup hints
@cindex remote shell setup

@cindex shell init files

As explained in the @ref{Overview} section, @tramp{} connects to the
remote host and talks to the shell it finds there.  Of course, when you
log in, the shell executes its init files.  Suppose your init file
requires you to enter the birthdate of your mother; clearly @tramp{}
does not know this and hence fails to log you in to that host.

There are different possible strategies for pursuing this problem.  One
strategy is to enable @tramp{} to deal with all possible situations.
This is a losing battle, since it is not possible to deal with

following as the value for the variable: @code{"^[^>$][>$] *"}.  Now
suppose your shell prompt is @code{a <b> c $ }.  In this case, Tramp
recognizes the @code{>} character as the end of the prompt, but it is
not at the end of the buffer.

@item @code{tset} and other questions
@cindex Unix command tset
@cindex tset Unix command

Some people invoke the @code{tset} program from their shell startup
scripts which asks the user about the terminal type of the shell.  Maybe
some shells ask other questions when they are started.  @tramp{} does
not know how to answer these questions.  (A facility for enabling
@tramp{} to answer these questions is planned for some future version,
but don't hold your breath.)

Therefore, you should take care that the shell does not ask any
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.

@vindex tramp-terminal-type
The variable @code{tramp-terminal-type} can be used to change this value
@code{dumb}.

@end table


@node Windows setup hints

will be able to access files on any remote machine that you can log in
to as though they were local.

Files are specified to @tramp{} using a formalized syntax specifying the
details of the system to connect to.  This is similar to the syntax used
by the @command{EFS} and @command{Ange-FTP} packages.


@menu
* Filename Syntax::             @tramp{} filename conventions.
* Multi-hop filename syntax::   Multi-hop filename conventions
* Dired::                       Dired and filename completion.
@end menu


@node Filename Syntax
@section @tramp{} filename conventions
@cindex filename syntax
@cindex filename examples

On Emacs, the Ange-FTP and Tramp filenames use a unified syntax.  On
XEmacs, EFS and Tramp use different formats for the filenames.
Therefore, the following will describe the Emacs and XEmacs cases
separately.

On Emacs, to access the file @var{path} on the remote machine
@var{machine} you would specify the filename
@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.

@table @file
@item /melancholia:.emacs
@itemx /[melancholia].emacs
Edit the file @file{.emacs} in your home directory on the machine
@code{melancholia}.

@item /melancholia.danann.net:.emacs
@itemx /[melancholia.danann.net].emacs
This edits the same file, using the fully qualified domain name of
the machine.

@item /melancholia:~/.emacs
@itemx /[melancholia]~/.emacs
This also edits the same file --- the @file{~} is expanded to your
home directory on the remote machine, just like it is locally.

@item /melancholia:~daniel/.emacs
@itemx /[melancholia]~daniel/.emacs
This edits the file @file{.emacs} in the home directory of the user
@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
construct is expanded to the home directory of that user on the remote
machine.

@item /melancholia:/etc/squid.conf
@itemx /[melancholia]/etc/squid.conf
This edits the file @file{/etc/squid.conf} on the machine
@code{melancholia}.

@end table

Unless you specify a different name to use, @tramp{} will use the current
local user name as the remote user name to log in with. If you need to
log in as a different user, you can specify the user name as part of the
filename.

On Emacs, to log in to the remote machine as a specific user, you use
the syntax @file{/@var{user}@@@var{machine}:/path/to.file}.  On
XEmacs, use @file{/[@var{user}@@@var{machine}]/path/to.file}.  That
means that connecting to @code{melancholia} as @code{daniel} and
editing @file{.emacs} in your home directory you would specify
@file{/daniel@@melancholia:.emacs} on Emacs and
@file{/[daniel@@melancholia].emacs} on XEmacs.


It is also possible to specify other file transfer methods
(@pxref{Default Method}) as part of the filename.  On Emacs, this is
done by puttig the method before the user and host name, as in
@file{/@var{method}:} (note the trailing colon).  On XEmacs, it is
done by replacing the initial @file{/[} with @file{/[<method>/}.
(Note the trailing slash!)  The user, machine and file specification
remain the same.

So, to connect to the machine @code{melancholia} as @code{daniel},
using the @option{su} method to transfer files, and edit @file{.emacs}
in my home directory I would specify the filename
@file{/su:daniel@@melancholia:.emacs} on Emacs and
@file{/[su/daniel@@melancholia].emacs} on XEmacs.


@node Multi-hop filename syntax
@section Multi-hop filename conventions
@cindex filename syntax for multi-hop files
@cindex multi-hop filename syntax

The syntax of multi-hop file names is necessarily slightly different
than the syntax of other @tramp{} file names.  Here's an example multi-hop
file name, first in Emacs syntax and then in XEmacs syntax:

@file{/multi:rsh:out@@gate:telnet:kai@@real.host:/path/to.file}
@file{/[multi/rsh:out@@gate/telnet:kai@@real.host]/path/to.file}

This is quite a mouthful.  So let's go through it step by step.  The
file name consists of three parts.  On Emacs, the parts are separated
by colons, on XEmacs they are separated by slashes and square
brackets.  The first part is @file{/multi:} (or @file{/[multi}), the
method specification.  The second part is
@file{rsh:out@@gate:telnet:kai@@real.host} (or
@file{rsh:out@@gate/telnet:kai@@real.host}) and specifies the hops.
(Yes, on Emacs the second part may contain even more colons, so that's why
this file name has more than two colons in it.)  The final part is
@file{/path/to.file} and specifies the file name on the remote host.

The first part and the final part should be clear.  @ref{Multi-hop
Methods}, for a list of alternatives for the method specification.

The second part can be subdivided again into components, so-called hops.
In the above file name, there are two hops, @file{rsh:out@@gate} and
@file{telnet:kai@@real.host}.

Each hop can @emph{again} be subdivided into (three) components, the
@dfn{hop method}, the @dfn{user name} and the @dfn{host name}.  The
meaning of the second and third component should be clear, and the hop
method says what program to use to perform that hop.

The first hop, @file{rsh:out@@gate}, says to use @command{rsh} to log in
as user @code{out} to the host @code{gate}.  Starting at that host, the
second hop, @file{telnet:kai@@real.host}, says to use @command{telnet}
to log in as user @code{kai} to host @code{real.host}.

@xref{Multi-hop Methods}, for a list of possible hop method values.  The
variable @var{tramp-multi-connection-function-alist} contains the list of
possible hop methods and information on how to execute them, should you
want to add your own.


@node Dired
@section Dired and filename completion
@cindex dired
@cindex filename completion

@tramp{} works transparently with dired, enabling you to use this powerful
file management tool to manage files on any machine you have access to
over the Internet.

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.

If you need to browse a directory tree, Dired is a better choice, at
present, than filename completion.  Dired has its own cache mechanism
and will only fetch the directory listing once.

@itemize @bullet
@item
Where can I get the latest @tramp{}?

@tramp{} is available at
@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/}.


@item
Which systems does it work on?

The package has been used successfully on Emacs 20 and Emacs 21, as well

Not all the older versions of @tramp{} supported XEmacs correctly. The
first thing to do is to make sure that you have the latest version of
@tramp{} installed.

If you do, please try and find out exactly the conditions required for
the @code{EFS} handlers to fire. If you can, putting a breakpoint on
@code{efs-ftp-path} and sending in the stack trace along with your bug
report would make it easier for the developers to work out what is going
wrong.


@item
File name completion does not work with @tramp{}

@c For the developer
@node Version Control
@chapter The inner workings of remote version control

Unlike EFS and Ange-FTP, @tramp{} has full shell access to the remote
machine. This makes it possible to provide version control for files
accessed under @tramp{}.

The actual version control binaries must be installed on the remote
machine, accessible in the directories specified in
@var{tramp-remote-path}.

@menu
* Version Controlled Files::    Determining if a file is under version control.
* Remote Commands::             Executing the version control commands on the remote machine.
* Changed workfiles::           Detecting if the working file has changed.
* Checking out files::          Bringing the workfile out of the repository.
* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere
@end menu


@node Version Controlled Files
@section Determining if a file is under version control

@c   host and then send commands to it.
@c * Mention that bookmarks are a cool feature to go along with Tramp.
@c * Make terminology "inline" vs "out-of-band" consistent.
@c   It seems that "external" is also used instead of "out-of-band".

47576:b31c8ab7336a

@c %**end of header

@c This is *so* much nicer :)
@footnotestyle end

@c In the Tramp CVS, the version number is auto-frobbed from the
@c Makefile, so you should edit the top-level Makefile to change
@c the version number.
@macro trampver{}
2.0.20
@end macro

@c Entries for @command{install-info} to use
@dircategory Emacs
@direntry
* TRAMP: (tramp).                Transparent Remote Access, Multiple Protocol

@c Macro to make formatting of the tramp program name consistent.
@macro tramp
@sc{tramp}
@end macro

@c Distinguish between GNU Emacs and XEmacs.  Derived from the
@c Makefile variable $(EMACS-ID).  Valid values are `emacs' and `xemacs'.
@set emacs

@c Some flags which make the text independent on the (X)Emacs flavor.
@c GNU Emacs values.
@ifset emacs
@set emacs-name               Emacs
@set emacs-dir                emacs
@set ftp-package-name         Ange-FTP
@set tramp-prefix             /
@set tramp-prefix-single-hop
@set tramp-postfix            :
@set tramp-postfix-single-hop :
@set tramp-postfix-multi-hop  :
@end ifset

@c XEmacs counterparts.
@ifset xemacs
@set emacs-name               XEmacs
@set emacs-dir                xemacs
@set ftp-package-name         EFS
@set tramp-prefix             /[
@set tramp-prefix-single-hop  [
@set tramp-postfix            ]
@set tramp-postfix-single-hop /
@set tramp-postfix-multi-hop  :
@end ifset

@c Macros for formatting a filename.
@c trampfn is for a full filename, trampfnmhp means method, host, path
@c were given, and so on.
@macro trampfn(method, user, host, path)
@value{tramp-prefix}@value{method}@value{user}@@@value{host}@value{tramp-postfix}@value{path}
@end macro

@tex

@titlepage
@title @tramp{} version @trampver{} User Manual

@author by Daniel Pittman
@author based on documentation by Kai Gro@ss{}johann
@page

@end titlepage
@page

@end tex

@ifnottex
@node Top, Overview, (dir), (dir)
@top @tramp{} version @trampver{} User Manual

This file documents @tramp{} version @trampver{}, a remote file
editing package for @value{emacs-name}.

@tramp{} stands for `Transparent Remote (file) Access, Multiple
Protocol'.  This package provides remote file editing, similar to
@value{ftp-package-name}.

The difference is that @value{ftp-package-name} uses FTP to transfer
files between the local and the remote host, whereas @tramp{} uses a
combination of @command{rsh} and @command{rcp} or other work-alike
programs, such as @command{ssh}/@command{scp}.

You can find the latest version of this document on the web at
@uref{http://www.freesoftware.fsf.org/tramp/}.

@ifhtml
This manual is also available as a @uref{tramp_ja.html, Japanese
translation}.

The latest release of @tramp{} is available for
@uref{http://savannah.gnu.org/download/tramp/,
download}, or you may see @ref{Obtaining @tramp{}} for more details,
including the CVS server details.

@tramp{} also has a @uref{https://savannah.gnu.org/projects/tramp/,
Savannah Project Page}.
@end ifhtml

There is a mailing list for @tramp{}, available at
@email{tramp-devel@@mail.freesoftware.fsf.org}, and archived at
@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/} as
well as the usual Savannah archives.

@end ifnottex

@menu
* Overview::                    What @tramp{} can and cannot do.
* Copying::                     The license for this documentation.

For the end user:
* Obtaining @tramp{}::          How to obtain @tramp{}.
* History::                     History of @tramp{}.
* Installation::                Installing @tramp{} with your @value{emacs-name}.
* Configuration::               Configuring @tramp{} for use.
* Usage::                       An overview of the operation of @tramp{}.
* Bug Reports::                 Reporting Bugs and Problems.
* Frequently Asked Questions::  Questions and answers from the mailing list.

For the developer:
* Version Control::             The inner workings of remote version control.
* Files directories and paths::  How file names, directories and paths are mangled and managed.
* Issues::                      Debatable Issues and What Was Decided.

@detailmenu
 --- The Detailed Node Listing ---

Configuring @tramp{} for use

* Connection types::            Types of connections made to remote machines.
* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
* Remote Programs::             How @tramp{} finds and uses programs on the remote machine.
* Remote shell setup::          Remote shell setup hints.
* Windows setup hints::         Issues with Cygwin ssh.

Using @tramp

* Filename Syntax::             @tramp{} filename conventions.
* Multi-hop filename syntax::   Multi-hop filename conventions.
* Filename completion::         Filename completion.
* Dired::                       Dired.

The inner workings of remote version control

* Version Controlled Files::    Determining if a file is under version control.
* Remote Commands::             Executing the version control commands on the remote machine.
* Changed workfiles::           Detecting if the working file has changed.
* Checking out files::          Bringing the workfile out of the repository.
* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere.

Things related to Version Control that don't fit elsewhere

* Remote File Ownership::       How VC determines who owns a workfile.
* Back-end Versions::           How VC determines what release your RCS is.

How file names, directories and paths are mangled and managed.

* Path deconstruction::         Breaking a path into its components.

@end detailmenu
@end menu

@node Overview
@chapter An overview of @tramp
@cindex overview

After the installation of @tramp{} into your @value{emacs-name}, you
will be able to access files on remote machines as though they were
local.  Access to the remote file system for editing files, version
control, and @command{dired} are transparently enabled.

Your access to the remote machine can be with the @command{rsh},
@command{rlogin}, @command{telnet} programs or with any similar
connection method.  This connection must pass ASCII successfully to be
usable but need not be 8-bit clean.

The package provides support for @command{ssh} connections out of the
box, one of the more common uses of the package.  This allows
relatively secure access to machines, especially if @command{ftp}
access is disabled.

The majority of activity carried out by @tramp{} requires only that
the remote login is possible and is carried out at the terminal.  In
order to access remote files @tramp{} needs to transfer their content
to the local machine temporarily.

@tramp{} can transfer files between the machines in a variety of ways.
The details are easy to select, depending on your needs and the
machines in question.

The fastest transfer methods (for large files) rely on a remote file
transfer package such as @command{rcp}, @command{scp} or
@command{rsync}.  The use of these methods is only possible if the
file copy command does not ask for a password for the remote machine.

If the remote copy methods are not suitable for you, @tramp{} also
supports the use of encoded transfers directly through the shell.
This requires that the @command{mimencode} or @command{uuencode} tools
are available on the remote machine.  These methods are generally
faster for small files.

Within these limitations, @tramp{} is quite powerful.  It is worth
noting that, as of the time of writing, it is far from a polished
end-user product.  For a while yet you should expect to run into rough
edges and problems with the code now and then.

It is finished enough that the developers use it for day to day work but
the installation and setup can be a little difficult to master, as can
the terminology.

@tramp{} is still under active development and any problems you encounter,
trivial or major, should be reported to the @tramp{} developers.
@xref{Bug Reports}.


@subsubheading Behind the scenes
@cindex behind the scenes
@cindex details of operation
@cindex how it works

This section tries to explain what goes on behind the scenes when you
access a remote file through @tramp{}.

Suppose you type @kbd{C-x C-f} and enter part of an @tramp{} file name,
then hit @kbd{@key{TAB}} for completion.  Suppose further that this is
the first time that @tramp{} is invoked for the host in question.  Here's
what happens:

@itemize
@item
@tramp{} discovers that it needs a connection to the host.  So it
invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
@var{user}} or a similar tool to connect to the remote host.
Communication with this process happens through an
@value{emacs-name} buffer, that is, the output from the remote end
goes into a buffer.

@item
The remote host may prompt for a login name (for @command{telnet}).  The
login name is given in the file name, so @tramp{} sends the login name and
a newline.

@item
The remote host may prompt for a password or pass phrase (for
@command{rsh} or for @command{telnet} after sending the login name).
@tramp{} displays the prompt in the minibuffer, asking you for the
password or pass phrase.

You enter the password or pass phrase.  @tramp{} sends it to the remote
host, followed by a newline.

@item
@tramp{} now waits for the shell prompt or for a message that the login
failed.

If @tramp{} sees neither of them after a certain period of time (a minute,
say), then it issues an error message saying that it couldn't find the
remote shell prompt and shows you what the remote host has sent.

If @tramp{} sees a @samp{login failed} message, it tells you so,
aborts the login attempt and allows you to try again.

@item
Suppose that the login was successful and @tramp{} sees the shell prompt
from the remote host.  Now @tramp{} invokes @command{/bin/sh} because
Bourne shells and C shells have different command
syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
shell doesn't recognize @samp{exec /bin/sh} as a valid command.
Maybe you use the Scheme shell @command{scsh}@dots{}}

After the Bourne shell has come up, @tramp{} sends a few commands to
ensure a good working environment.  It turns off echoing, it sets the
shell prompt, and a few other things.

@item
Now the remote shell is up and it good working order.  Remember, what
was supposed to happen is that @tramp{} tries to find out what files exist
on the remote host so that it can do filename completion.

So, @tramp{} basically issues @command{cd} and @command{ls} commands and
also sometimes @command{echo} with globbing.  Another command that is
often used is @command{test} to find out whether a file is writable or a
directory or the like.  The output of each command is parsed for the
necessary operation.

@item
Suppose you are finished with filename completion, have entered @kbd{C-x
C-f}, a full file name and hit @kbd{@key{RET}}.  Now comes the time to
transfer the file contents from the remote host to the local host so
that you can edit them.

See above for an explanation of how @tramp{} transfers the file contents.

For inline transfers, @tramp{} issues a command like @samp{mimencode -b
/path/to/remote/file}, waits until the output has accumulated in the
buffer that's used for communication, then decodes that output to
produce the file contents.

For out-of-band transfers, @tramp{} issues a command like the following:
@example
rcp user@@host:/path/to/remote/file /tmp/tramp.4711
@end example
It then reads the local temporary file @file{/tmp/tramp.4711} into a
buffer and deletes the temporary file.

@item
You now edit the buffer contents, blithely unaware of what has happened
behind the scenes.  (Unless you have read this section, that is.)  When
you are finished, you type @kbd{C-x C-s} to save the buffer.

@item
Again, @tramp{} transfers the file contents to the remote host either
inline or out-of-band.  This is the reverse of what happens when reading
the file.

@end itemize

I hope this has provided you with a basic overview of what happens
behind the scenes when you open a file with @tramp{}.


@c Copying permissions, et al
@node Copying
@chapter Copying.
@cindex copying

@copying
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software
Foundation, Inc.

@quotation     
Permission is granted to copy, distribute and/or modify this document

license to the document, as described in section 6 of the license.
@end quotation
@end copying


@c For the end user
@node Obtaining @tramp{}
@chapter Obtaining @tramp{}.
@cindex obtaining Tramp

For the especially brave, @tramp{} is available from CVS.  The CVS version
is the latest version of the code and may contain incomplete features or
new issues. Use these versions at your own risk.

Instructions for obtaining the latest development version of @tramp{}
from CVS can be found by going to the Savannah project page at the
following URL and then clicking on the CVS link in the navigation bar at
the top.

@noindent
@uref{http://savannah.gnu.org/projects/tramp/}

@noindent
Or follow the example session below:

@example
] @strong{cd ~/@value{emacs-dir}}
] @strong{cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp login}

(Logging in to anoncvs@@subversions.gnu.org)
CVS password: @strong{(just hit RET here)}
@dots{}

] @strong{cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/tramp co tramp}
@end example

@noindent
You should now have a directory @file{~/@value{emacs-dir}/tramp} containing the latest
version of @tramp{}. You can fetch the latest updates from the repository
by issuing the command:

@example
] @strong{cd ~/@value{emacs-dir}/tramp}
] @strong{cvs update -d}
@end example


@node History

added in April 2000 and the unification of @tramp{} and Ange-FTP
filenames in July 2002.


@node Installation
@chapter Installing @tramp{} into @value{emacs-name}.
@cindex installation

If you use the version that comes with your @value{emacs-name}, the
following information is not necessary.  Installing @tramp{} into your
@value{emacs-name} is a relatively easy process, at least compared
to rebuilding your machine from scratch. ;)

Seriously though, the installation should be a fairly simple matter.

The easiest way to proceed is as follows:

@itemize @bullet
@item
Choose a directory, say @file{~/@value{emacs-dir}/}.  Change into that directory and
unpack the tarball.  This will give you a directory
@file{~/@value{emacs-dir}/tramp/} which contains subdirectories @file{lisp} for the
Lisp code and @file{texi} for the documentation.

@item
Optionally byte-compile all files in the Lisp directory,
@file{~/@value{emacs-dir}/tramp/lisp/}, by issuing a command like the following from
the top level directory @file{~/@value{emacs-dir}/tramp/}:

@example
make EMACS=@value{emacs-dir} all
@end example

@item
NOTE: If you run into problems running the example @command{make}
command, don't dispare.  You can still byte compile the @file{*.el}
files by opening @value{emacs-name} in @command{dired} (@command{C-x
d}) mode, at @file{~/@value{emacs-dir}/tramp/lisp}.  Mark the lisp files with
@kbd{m}, then press @kbd{B} to byte compile your selections.

Something similar can be done to create the info manual.  Just change
to directory @file{~/@value{emacs-dir}/tramp/texi} and load the
@file{tramp.texi} file in @value{emacs-name}.  Then press @kbd{M-x
makeinfo-buffer @key{RET}} to generate @file{tramp.info}.

@item
Tell @value{emacs-name} about the new Lisp directory and the
@tramp{} package with the following lines in @file{~/.emacs}:

@lisp
(add-to-list 'load-path "~/@value{emacs-dir}/tramp/lisp/")
(require 'tramp)
@end lisp

@item
To be able to read the Info documentation, create a file
@file{~/@value{emacs-dir}/tramp/texi/dir} using the
@command{install-info} command, and add the directory to the search
path for Info.

NOTE:
On systems using the @cite{gnu} version of @command{install-info}, the
@command{install-info} syntax is very direct and simple.  One can
change to directory @file{~/@value{emacs-dir}/tramp/texi} and type:

@example
install-info tramp.info dir
@end example

and a @file{dir} file will be created with the @tramp{}
entry.  The info reader will know how to interpret it, but must
be told where to find it (see below).  If you want anything fancier
you'll need to look through @kbd{man install-info}.

Debian gnu/linux doesn't default to @cite{gnu} @command{install-info}
and uses its own version.  This version does not create a @file{dir}
file for you from scratch.  You must provide a skeleton @file{dir}
file it recognizes.  One can be found in a default installation of
@value{emacs-name} at @file{/usr/info/dir}.  Copy the top of this file
down to the first occurrence of @code{* Menu} including that line plus
one more blank line, to your working directory
@file{~/@value{emacs-dir}/tramp/texi}, or use the sample
@file{~/@value{emacs-dir}/tramp/texi/dir_sample}.

Once a @file{dir} file is in place, this command will make the entry:

@example
install-info --infodir=. tramp.info
@end example

If you want it in a specific category see @kbd{man install-info} for
further details.

If the environment variable @env{INFOPATH} is set, add the directory
@file{~/@value{emacs-dir}/tramp/texi/} to it.  Else, add the directory to
@ifset emacs
@code{Info-default-directory-list}, as follows:

@lisp
(add-to-list 'Info-default-directory-list "~/@value{emacs-dir}/tramp/texi/")
@end lisp
@end ifset
@ifset xemacs
@code{Info-directory-list}, as follows:
@lisp
(add-to-list 'Info-directory-list "~/@value{emacs-dir}/tramp/texi/")
@end lisp
@end ifset

@end itemize

@ifset xemacs
For @value{emacs-name}, the package @file{fsf-compat} must be installed.
For details on package installation, see @ref{Packages, , ,xemacs}.
@ifhtml
(If the previous link doesn't work, try the @value{emacs-name}
documentation at
@uref{http://www.xemacs.org/Documentation/packageGuide.html,the
@value{emacs-name} site}.)
@end ifhtml
@end ifset

@node Configuration
@chapter Configuring @tramp{} for use
@cindex configuration

@cindex default configuration
@tramp{} is (normally) fully functional when it is initially
installed.  It is initially configured to use the @command{ssh} program
to connect to the remote host and to use base-64 encoding (on the
remote host, via @command{mimencode}, and on the local host via the
built-in support for base-64 encoding in Emacs).

On some hosts, there are problems with opening a connection.  These are

* Inline methods::              Inline methods.
* External transfer methods::   External transfer methods.
* Multi-hop Methods::           Connecting to a remote host using multiple hops.
* Default Method::              Selecting a default method.
* Customizing Methods::         Using Non-Standard Methods.
* Customizing Completion::      Selecting config files for user/host name completion.
* Remote Programs::             How @tramp{} finds and uses programs on the remote machine.
* Remote shell setup::          Remote shell setup hints.
* Windows setup hints::         Issues with Cygwin ssh.
@end menu

@cindex out-of-band methods
@cindex methods, inline
@cindex methods, external transfer
@cindex methods, out-of-band
Loading or saving a remote file requires that the content of the file
be transfered between the two machines. The content of the file can be
transfered over the same connection used to log in to the remote
machine or the file can be transfered through another connection using
a remote copy program such as @command{rcp}, @command{scp} or
@command{rsync}.  The former are called @dfn{inline methods}, the
latter are called @dfn{out-of-band methods} or @dfn{external transfer
methods} (@dfn{external methods} for short).

There are also two variants, @option{sm-ssh1} and @option{sm-ssh2}
that use the @command{ssh1} and @command{ssh2} commands explicitly. If
you don't know what these are, you do not need these options.

All the methods based on @command{ssh} have an additional kludgy
feature: you can specify a host name which looks like @file{host#42}
(the real host name, then a hash sign, then a port number).  This
means to connect to the given host but to also pass @code{-p 42} as
arguments to the @command{ssh} command.

@cindex Cygwin (with smx method)

As you expect, this is similar to @option{sm}, only a little
different.  Whereas @option{sm} opens a normal interactive shell on
the remote host, this option uses @samp{ssh -t -t @var{host} -l
@var{user} /bin/sh} to open a connection.  This is useful for users
where the normal login shell is set up to ask them a number of
questions when logging in.  This procedure avoids these questions, and
just gives @tramp{} a more-or-less `standard' login shell to work
with.

the inline methods when you often open and close small files however.
The cost of the cryptographic handshake at the start of an @command{scp}
session can begin to absorb the advantage that the lack of encoding and
decoding presents.

All the @command{ssh} based methods support the kludgy @samp{-p}
feature where you can specify a port number to connect to in the host
name.  For example, the host name @file{host#42} tells Tramp to
specify @samp{-p 42} in the argument list for @command{ssh}.

specifies a different port number for a certain host name.  But it can
also be accomplished within Tramp, by adding a multi-hop method.  For
example:

@lisp
(add-to-list
 'tramp-multi-connection-function-alist
 '("sshf" tramp-multi-connect-rlogin "ssh %h -l %u -p 4400%n"))
@end lisp

Now you can use an @code{sshf} hop which connects to port 4400 instead of
the standard port.


@node Default Method
@section Selecting a default method

For the time being, I'll refer you to the Lisp documentation of that
variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.


@node Customizing Completion
@section Selecting config files for user/host name completion
@cindex customizing completion
@cindex selecting config files
@vindex tramp-completion-function-alist

The variable @code{tramp-completion-function-alist} is intended to
customize, which files are taken into account for user and host name
completion (@pxref{Filename completion}).  For every method, it keeps
a set of configuration files, accompanied by a Lisp function able to
parse that file.  Entries in @code{tramp-completion-function-alist}
have the form (@var{method} @var{pair1} @var{pair2} ...).

Each @var{pair} is composed of (@var{function} @var{file}).
@var{function} is responsible to extract user names and host names
from @var{file} for completion.  There are two functions which access
this variable:

@defun tramp-get-completion-function method
This function returns the list of completion functions for @var{method}.

Example:
@example
(tramp-get-completion-function "rsh")

     @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
         (tramp-parse-rhosts "~/.rhosts"))
@end example
@end defun

@defun tramp-set-completion-function method function-list
This function sets @var{function-list} as list of completion functions
for @var{method}. 

Example:
@example
(tramp-set-completion-function "ssh"
 '((tramp-parse-shosts "/etc/ssh_known_hosts")
   (tramp-parse-shosts "~/.ssh/known_hosts")))

     @result{} ((tramp-parse-shosts "/etc/ssh_known_hosts")
         (tramp-parse-shosts "~/.ssh/known_hosts"))
@end example
@end defun

The following predefined functions parsing configuration files exists:

@table @asis
@item @code{tramp-parse-rhosts}
@findex tramp-parse-rhosts

This function parses files which are syntactical equivalent to
@file{~/.rhosts}.  It returns both host names and user names, if
specified.

@item @code{tramp-parse-shosts}
@findex tramp-parse-shosts

This function parses files which are syntactical equivalent to
@file{/etc/ssh_known_hosts}.  Since there are no user names specified
in such files, it can return host names only.

@item @code{tramp-parse-hosts}
@findex tramp-parse-hosts

A function dedicated to @file{/etc/hosts} style files.  It returns
host names only.

@item @code{tramp-parse-passwd}
@findex tramp-parse-passwd

Finally a method which parses @file{/etc/passwd} like files.
Obviously, it can return user names only.
@end table

@ifset emacs
A function which parses @file{~/.netrc"} file syntax doesn't exist in
@tramp{}, because this task is delegated to
@value{ftp-package-name}. Its customization should be used instead.
@end ifset

If you want to keep your own data in a file, with your own structure,
you might provide such a function as well.  This function must meet
the following conventions:

@defun my-tramp-parse file
@var{file} must be either a file name on your host, or @code{nil}. The
function must return a list of (@var{user} @var{host}), which are
taken as candidates for user and host name completion.

Example:
@example
(my-tramp-parse "~/.my-tramp-hosts")

     @result{} ((nil "toto") ("daniel" "melancholia"))
@end example
@end defun


@node Remote Programs
@section How @tramp{} finds and uses programs on the remote machine.

@tramp{} depends on a number of programs on the remote host in order to
function, including @command{ls}, @command{test}, @command{find} and

found.

To add a directory to the remote search path, you could use code such
as:

@lisp
@i{;; We load @tramp{} to define the variable.}
(require 'tramp)
@i{;; We have @command{perl} in "/usr/local/perl/bin"}
(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
@end lisp


@node Remote shell setup
@comment  node-name,  next,  previous,  up
@section Remote shell setup hints
@cindex remote shell setup

@cindex shell init files

As explained in the @ref{Overview} section, @tramp{} connects to the
remote host and talks to the shell it finds there.  Of course, when you
log in, the shell executes its init files.  Suppose your init file
requires you to enter the birth date of your mother; clearly @tramp{}
does not know this and hence fails to log you in to that host.

There are different possible strategies for pursuing this problem.  One
strategy is to enable @tramp{} to deal with all possible situations.
This is a losing battle, since it is not possible to deal with

following as the value for the variable: @code{"^[^>$][>$] *"}.  Now
suppose your shell prompt is @code{a <b> c $ }.  In this case, Tramp
recognizes the @code{>} character as the end of the prompt, but it is
not at the end of the buffer.

@item @var{tramp-shell-prompt-pattern}
@vindex tramp-shell-prompt-pattern

This regular expression is used by @tramp{} in the same way as
@code{shell-prompt-pattern}, to match prompts from the remote shell.
This second variable exists because the prompt from the remote shell
might be different from the prompt from a local shell --- after all,
the whole point of @tramp{} is to log in to remote hosts as a
different user.  The default value of
@code{tramp-shell-prompt-pattern} is the same as the default value of
@code{shell-prompt-pattern}, which is reported to work well in many
circumstances.

@item @code{tset} and other questions
@cindex Unix command tset
@cindex tset Unix command

Some people invoke the @code{tset} program from their shell startup
scripts which asks the user about the terminal type of the shell.
Maybe some shells ask other questions when they are started.  @tramp{}
does not know how to answer these questions.  There are two approaches
for dealing with this problem.  One approach is to take care that the
shell does not ask any 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.

@vindex tramp-terminal-type
The variable @code{tramp-terminal-type} can be used to change this value
to @code{dumb}.

The other approach is to teach @tramp{} about these questions.  See
the variables @code{tramp-actions-before-shell} and
@code{tramp-multi-actions} (for multi-hop connections).

@end table


@node Windows setup hints

will be able to access files on any remote machine that you can log in
to as though they were local.

Files are specified to @tramp{} using a formalized syntax specifying the
details of the system to connect to.  This is similar to the syntax used
by the @value{ftp-package-name} package.

@cindex type-ahead
Something that might happen which surprises you is that Emacs
remembers all your keystrokes, so if you see a password prompt from
Emacs, say, and hit @kbd{@key{RET}} twice instead of once, then the
second keystroke will be processed by Emacs after @tramp{} has done
its thing.  Why, this type-ahead is normal behavior, you say.  Right
you are, but be aware that opening a remote file might take quite a
while, maybe half a minute when a connection needs to be opened.
Maybe after half a minute you have already forgotten that you hit that
key!

@menu
* Filename Syntax::             @tramp{} filename conventions.
* Multi-hop filename syntax::   Multi-hop filename conventions.
* Filename completion::         Filename completion.
* Dired::                       Dired.
@end menu


@node Filename Syntax
@section @tramp{} filename conventions
@cindex filename syntax
@cindex filename examples

To access the file @var{path} on the remote machine @var{machine} you
would specify the filename
@file{@value{tramp-prefix}@var{machine}@value{tramp-postfix}@var{path}}.
This will connect to @var{machine} and transfer the file using the
default method.  @xref{Default Method}.

Some examples of @tramp{} filenames are shown below.

@table @file
@item @value{tramp-prefix}melancholia@value{tramp-postfix}.emacs
Edit the file @file{.emacs} in your home directory on the machine
@code{melancholia}.

@item @value{tramp-prefix}melancholia.danann.net@value{tramp-postfix}.emacs
This edits the same file, using the fully qualified domain name of
the machine.

@item @value{tramp-prefix}melancholia@value{tramp-postfix}~/.emacs
This also edits the same file --- the @file{~} is expanded to your
home directory on the remote machine, just like it is locally.

@item @value{tramp-prefix}melancholia@value{tramp-postfix}~daniel/.emacs
This edits the file @file{.emacs} in the home directory of the user
@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
construct is expanded to the home directory of that user on the remote
machine.

@item @value{tramp-prefix}melancholia@value{tramp-postfix}/etc/squid.conf
This edits the file @file{/etc/squid.conf} on the machine
@code{melancholia}.

@end table

Unless you specify a different name to use, @tramp{} will use the
current local user name as the remote user name to log in with. If you
need to log in as a different user, you can specify the user name as
part of the filename.

To log in to the remote machine as a specific user, you use the syntax
@file{@value{tramp-prefix}@var{user}@@@var{machine}@value{tramp-postfix}/@var{path/to.file}}.
That means that connecting to @code{melancholia} as @code{daniel} and
editing @file{.emacs} in your home directory you would specify
@file{@value{tramp-prefix}daniel@@melancholia@value{tramp-postfix}.emacs}.

It is also possible to specify other file transfer methods
(@pxref{Default Method}) as part of the filename.
@ifset emacs
This is done by putting the method before the user and host name, as
in
@file{@value{tramp-prefix}@var{method}@value{tramp-postfix-single-hop}}
(note the trailing colon).
@end ifset
@ifset xemacs
This is done by replacing the initial
@file{@value{tramp-prefix}} with
@file{@value{tramp-prefix}<method>@value{tramp-postfix-single-hop}}.
(Note the trailing slash!).
@end ifset
The user, machine and file specification remain the same.

So, to connect to the machine @code{melancholia} as @code{daniel},
using the @option{su} method to transfer files, and edit @file{.emacs}
in my home directory I would specify the filename
@file{@value{tramp-prefix}su@value{tramp-postfix-single-hop}daniel@@melancholia@value{tramp-postfix}.emacs}.


@node Multi-hop filename syntax
@section Multi-hop filename conventions
@cindex filename syntax for multi-hop files
@cindex multi-hop filename syntax

The syntax of multi-hop file names is necessarily slightly different
than the syntax of other @tramp{} file names.  Here's an example
multi-hop file name, first in Emacs syntax and then in XEmacs syntax:

@example
@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
@end example

This is quite a mouthful.  So let's go through it step by step.  The
file name consists of three parts.
@ifset emacs
The parts are separated by colons
@end ifset
@ifset xemacs
The parts are separated by slashes and square brackets.
@end ifset
The first part is @file{@value{tramp-prefix}multi}, the method
specification.  The second part is
@file{rsh@value{tramp-postfix-multi-hop}out@@gate@value{tramp-postfix-single-hop}telnet@value{tramp-postfix-multi-hop}kai@@real.host}
and specifies the hops.  The final part is @file{/path/to.file} and
specifies the file name on the remote host.

The first part and the final part should be clear.  @ref{Multi-hop
Methods}, for a list of alternatives for the method specification.

The second part can be subdivided again into components, so-called
hops.  In the above file name, there are two hops,
@file{rsh@value{tramp-postfix-multi-hop}out@@gate} and
@file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}.

Each hop can @emph{again} be subdivided into (three) components, the
@dfn{hop method}, the @dfn{user name} and the @dfn{host name}.  The
meaning of the second and third component should be clear, and the hop
method says what program to use to perform that hop.

The first hop, @file{rsh@value{tramp-postfix-multi-hop}out@@gate},
says to use @command{rsh} to log in as user @code{out} to the host
@code{gate}.  Starting at that host, the second hop,
@file{telnet@value{tramp-postfix-multi-hop}kai@@real.host}, says to
use @command{telnet} to log in as user @code{kai} to host
@code{real.host}.

@xref{Multi-hop Methods}, for a list of possible hop method values.
The variable @code{tramp-multi-connection-function-alist} contains the
list of possible hop methods and information on how to execute them,
should you want to add your own.


@node Filename completion
@section Filename completion
@cindex filename completion

Filename completion works with @tramp{} for both completing methods,
user names and machine names (except multi hop methods) as well as for
files on remote machines.

If you, for example, type @kbd{C-x C-f @value{tramp-prefix}t
@key{TAB}}, @tramp{} might give you as result the choice for

@example
@ifset emacs
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}				   tmp/
@value{tramp-prefix-single-hop}toto@value{tramp-postfix}
@end ifset
@ifset xemacs
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}				   @value{tramp-prefix-single-hop}toto@value{tramp-postfix}
@end ifset
@end example
     
@samp{@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}}
is a possible completion for the respective method,
@ifset emacs
@samp{tmp/} stands for the directory @file{/tmp} on your local
machine,
@end ifset
and @samp{@value{tramp-prefix-single-hop}toto@value{tramp-postfix}}
might be a host @tramp has detected in your @file{~/.ssh/known_hosts}
file (given you're using default method @option{ssh}).

If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
@samp{@value{tramp-prefix}telnet@value{tramp-postfix-single-hop}}.
Next @kbd{@key{TAB}} brings you all machine names @tramp{} detects in
your @file{/etc/hosts} file, let's say

@example
@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}
@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}
@value{tramp-prefix-single-hop}telnet@value{tramp-postfix-single-hop}melancholia@value{tramp-postfix}
@end example

Now you can choose the desired machine, and you can continue to
complete file names on that machine.

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.

If the configuration files (@pxref{Customizing Completion}), which
@tramp{} uses for analysis of completion, offer user names, those user
names will be taken into account as well.


@node Dired
@section Dired
@cindex dired

@tramp{} works transparently with dired, enabling you to use this powerful
file management tool to manage files on any machine you have access to
over the Internet.

If you need to browse a directory tree, Dired is a better choice, at
present, than filename completion.  Dired has its own cache mechanism
and will only fetch the directory listing once.

@itemize @bullet
@item
Where can I get the latest @tramp{}?

@tramp{} is available under the URL below.

@noindent
@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/tramp.tar.gz}

@noindent
There is also a Savannah project page.

@noindent
@uref{https://savannah.gnu.org/projects/tramp/}

@item
Which systems does it work on?

The package has been used successfully on Emacs 20 and Emacs 21, as well

Not all the older versions of @tramp{} supported XEmacs correctly. The
first thing to do is to make sure that you have the latest version of
@tramp{} installed.

If you do, please try and find out exactly the conditions required for
the EFS handlers to fire. If you can, putting a breakpoint on
@code{efs-ftp-path} and sending in the stack trace along with your bug
report would make it easier for the developers to work out what is
going wrong.


@item
File name completion does not work with @tramp{}

@c For the developer
@node Version Control
@chapter The inner workings of remote version control

Unlike @value{ftp-package-name}, @tramp{} has full shell access to the
remote machine. This makes it possible to provide version control for
files accessed under @tramp{}.

The actual version control binaries must be installed on the remote
machine, accessible in the directories specified in
@var{tramp-remote-path}.

@menu
* Version Controlled Files::    Determining if a file is under version control.
* Remote Commands::             Executing the version control commands on the remote machine.
* Changed workfiles::           Detecting if the working file has changed.
* Checking out files::          Bringing the workfile out of the repository.
* Miscellaneous Version Control::  Things related to Version Control that don't fit elsewhere.
@end menu


@node Version Controlled Files
@section Determining if a file is under version control

@c   host and then send commands to it.
@c * Mention that bookmarks are a cool feature to go along with Tramp.
@c * Make terminology "inline" vs "out-of-band" consistent.
@c   It seems that "external" is also used instead of "out-of-band".

@c * M. Albinus
@c ** Use `filename' resp. `file name' consistently.
@c ** Use `host' resp. `machine' consistently.
@c ** Consistent small or capitalized words especially in menues.