Once you have ange-ftp installed, you never need worry about using FTP
again. The interface is completely transparent, and you may now use
Emacs commands such as C-x C-f (find-file)
on any
file that your local host (or, if you are using one) your gateway can
access. That file may be a regular file (for editing, viewing etc.), a
directory (for invoking Dired) or even a symbolic link
(pointing to a
directory or a regular file). All it takes is an extended filename
syntax. For example, if you give the filename
/ange@anorman:/tmp/notes
to find-file, then ange-ftp will spawn an FTP process, connect to
the host anorman as user ange, get the file
`/tmp/notes' and pop up a buffer containing the contents of that
file as if it were on the local filesystem. If ange-ftp needed a
password to connect then it would prompt the user in the minibuffer.
From then on you can edit that file as if it were any other file: saving
is with C-x C-s as usual -- in fact, everything is as usual.
Ange-ftp is also extremely useful for regular "file-transfer" FTP jobs. Since Dired also works on remote directories when using ange-ftp, you will be able to browse the filesystem on your favourite archive site with consummate ease.
The general form of the extended filename syntax is
/user@host:path
which refers to the file pointed to by path on machine
host when logging in as user user. When path is
supplied as a relative file-name (that is, without a leading `/')
it is relative to user's home directory (although such relative
filenames are ultimately converted to absolute ange-ftp pathnames). You
may even refer to home directories
of users on remote Unix sites using the
standard tilde `~' notation.
host needs to be
the fully qualified pathname if the local or gateway machine requires it
to be (however hostname completion is available if it is included in
your `.netrc' -- See section Using a .netrc file), or it may be an IP
number if your nameserver can't find the site. The user@ part
may be omitted, in which case the username is chosen on the basis of the
variable ange-ftp-default-user
(See section Other user options) and your
`.netrc'. If a password is requested by the FTP process, ange-ftp
will either prompt you for it, or generate one on the basis of the
variables ange-ftp-default-password,
and your `.netrc'.
Thus the following are all valid ange-ftp filenames:
/anonymous@waldo.uranium.com:pub/games/wumpus /root@127.44.3.1:/etc/passwd /jbrown@freddie.ucla.edu:~mblack/ /alpha.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.Z
This feature of ange-ftp is particularly useful when file-transfers, as
opposed to file-editing, are the order of the day. Simply run
find-file on a directory to
get a listing of the files in that directory. For example, you might
run find-file on
/anonymous@archive.site.com:pub
to see what's in the `pub' directory of your favourite archive site. This brings up a Dired buffer of all the files in that directory. The f command is useful for looking at `README' files -- if you then decide to save it C-x C-w is useful. You can also use this method to copy files, but the c command is easier. The f command can also be used to descend the directory tree by applying it to directories.
You can also use Dired to refresh ange-ftp's internal cache. If you
(or anybody else) has changed a remote directory since you first accessed it
with ange-ftp, completion is not provided on any new files that ange-ftp
does not know about. If you have
(or create) a Dired buffer which contains the modified directory,
executing revert-buffer
with a prefix argument (C-u g in the Dired buffer)
will force a refresh of both the the buffer and also ange-ftp's
internal cache. If you find that filename completion isn't working on a
file that you know is there, this is how to fix the problem.
The version of Dired supplied with Emacs version 18.58 (and earlier versions) does not include a capability for multiple file transfers. The Tree Dired package (See section How to get the ange-ftp source code), however, is ideal for this application. Tree Dired provides facilities for maintaining an entire directory tree in a Dired buffer, for marking files which match a certain regexp (or you can select files interactively) and then copying all those files to your local host (or even a different remote host). Another useful feature is Virtual Dired, which allows you to save Dired buffers of remote hosts, allowing you to browse them at a later date without actually needing to connect to the host. See the documentation for Tree Dired for more details.
Since ange-ftp is mostly transparent, modifying Dired or Tree Dired by means of hooks or keybindings should still work.
Being prompted for passwords all the time can get rather annoying, but
there is a way to fix the problem -- a `.netrc' (but See section Other user options and ange-ftp-netrc-filename
if you want another
filename) file in your home directory. Basically, this is a file (in the
format of Unix netrc(5)) which
contains the names of all the machines you regularly login to, as well
as the username and password you use for that machine. You can also
supply an account password, if required.
Your `.netrc' file consists of lines of the form
machine <machine-name> login <user-name> password <password>
It doesn't all have to be on the one line, though: any login or
password commands in the file refer to the previous
machine command. You can also have account
<account-passwd> commands if you need special account passwords.
For example, you might have the following line in your `.netrc':
machine Y.local.lan.edu login myname password secret
Then if you run find-file on the file `/Y.local.lan.edu:somefile'
you will automatically be logged in as user myname with password
secret. You can still login under another name and password, if
you so desire: just include the user@ part of the filename.
You may also include a default option, as follows:
default login <user-name> password <password>
which applies to any other machines not mentioned elsewhere in your `.netrc'. A particularly useful application of this is with anonymous logins:
default login myname password myname@myhost.edu
so that accessing `/anyhost:anyfile' will automatically log you in
anonymously, provided the host is not mentioned in the `.netrc'.
Note also that if the value of ange-ftp-default-user is
non-nil, its value will have precedence over the username
supplied in the default option of the `.netrc'.
The `.netrc' file is also useful in another regard: machines included in it are provided with hostname completion. That is, for any machine in the `.netrc', you need only type a slash and the first few characters of its name and then press TAB to be logged in automatically with a username and password from the `.netrc' file. So it's a good idea to put hosts you use regularly in your `.netrc' as well:
machine archive.site.com login anonymous password myname@X.local.lan.edu
Ange-ftp supplies a few interactive commands to make connecting with hosts a little easier.
Command ange-ftp-set-user: Prompts for a hostname and a username.
Next time access to the host is attempted, ange-ftp will attempt to log
in again with the new username.
Command ange-ftp-set-passwd: Prompts for a hostname, user and
password. Future logins to that host as that user will use the given
password.
Command ange-ftp-set-account: Prompts for a hostname, user and
account. Future logins to that host as that user will use the given
account.
Note that the effects of the above three commands only last the duration of the current Emacs session. To make their effects permanent, you may include them as lisp code in your `.emacs':
(ange-ftp-set-user HOST USER) (ange-ftp-set-password HOST USER PASSWORD) (ange-ftp-set-account HOST USER ACCOUNT)
This is an alternative to using a `.netrc'; See section Using a .netrc file.
Command ange-ftp-kill-ftp-process: kill the FTP process
associated with a given buffer's filename (by default the current
buffer). This is an easy way to achieve a resynch: any future accesses
to the remote host will cause the FTP process to be recreated.
Some hosts (such as cs.uwp.edu) now use descriptive directory
listings
(which in fact contain less information than the
standard listing!) when issued the ls command, and ange-ftp has
been modified to cope with this. Ange-ftp can detect such listings, but
if you regularly use a remote host which uses this extended listing
format you should set the variable ange-ftp-dl-dir-regexp to a
regular expression which matches directories using the extended listing
format. You shouldn't anchor the regexp with `$' -- that way the
regexp will match subdirectories as well. Alternatively, you can use
the interactive command ange-ftp-add-dl-dir to temporarily add a
remote directory for this Emacs session only.
Tree Dired has been modified to work with such descriptive listings.
Ange-ftp also works with some non-Unix hosts, although not necessarily with all the features available with Unix hosts. VMS, CMS, and MTS systems will all now work with ange-ftp and Tree Dired (although Classical Dired may well be broken on such systems.) Filename completion also now works on these hosts.
Ange-ftp should be able to automatically detect which type of host you
are using (VMS, CMS or MTS), but if it is unable to do so you can fix
the problem by setting the appropriate
ange-ftp-TYPE-host-regexp variable (where TYPE is one of
`vms', `cms' or `mts') -- see below. If ange-ftp is unable
to automatically detect any VMS, CMS or MTS host, please report this as
a bug: See section Bugs and Wish List.
In all cases the file-name conventions of the remote host are converted to a UNIX-ish format, and this is the format you should use to find files on such hosts.
VMS filenames are of the form FILE.TYPE;##, where both
FILE and TYPE can be up to 39 characters long, and
## is an integer version number between 1 and 32,767. Valid
characters in filenames are `A'-`Z', `0'-`9',
`_', `-' and `$', however `$' cannot begin a
filename and `-' cannot be used as the first or last character.
Directories in VMS are converted to the standard UNIX `/' notation. For example, the VMS filename
PUB$:[ANONYMOUS.SDSCPUB.NEXT]README.TXT;1
would be entered as
/PUB$$:/ANONYMOUS/SDSCPUB/NEXT/README.TXT;1
(The double `$' is required to prevent Emacs from attempting to
expand an environment variable.) Similarly, to anonymously FTP the file
`[.CSV.POLICY]RULES.MEM;1' from ymir.claremont.edu you would
type C-x C-f
/anonymous@ymir.claremont.edu:CSV/POLICY/RULES.MEM;1. You can always
drop off the `;##' part at the end of the filename to get the
latest version.
Sandy Rutherford provides some tips for using VMS hosts:
C-x C-f /ymir.claremont.edu:FILE.TXT;3you will find that VMS will not allow you to save the file because it will refuse to overwrite `FILE.TXT;3', but instead will want to create `FILE.TXT;4', and attach the buffer to this file. To get out of this situation, M-x write-file /ymir.claremont.edu:FILE.TXT will attach the buffer to latest version of the file. For this reason, in Tree Dired f (
dired-find-file),
always loads the file sans version, whereas v,
(dired-view-file),
always loads the explicit version number. The
reasoning being that it reasonable to view old versions of a file, but
not to edit them.
Ange-ftp should automatically detect that you are using a VMS host. If
it fails to do so (which should be reported as a bug) you can use the
command ange-ftp-add-vms-host
to inform ange-ftp manually. For a more permanent effect, or
if you use a VMS host regularly, it's a good idea to set
ange-ftp-vms-host-regexp to a regular expression matching that
host's name. For instance, if use use ymir.claremont.edu a lot,
place the following in your .emacs:
(setq ange-ftp-vms-host-regexp "^ymir.claremont.edu$")
Ange-ftp has full support, including Tree Dired support, for hosts running CMS.
CMS filenames are entered in a UNIX-y way. Minidisks are treated as UNIX directories; for example to access the file `READ.ME' in minidisk `*.311' on `cuvmb.cc.columbia.edu', you would enter
/anonymous@cuvmb.cc.columbia.edu:/*.311/READ.ME
If `*.301' is the default minidisk for this account, you could access `FOO.BAR' on this minidisk as
/anonymous@cuvmb.cc.columbia.edu:FOO.BAR
CMS filenames are of the form `FILE.TYPE', where both `FILE' and `TYPE' can be up to 8 characters. Again, beware that CMS filenames are always upper case, and hence must be entered as such.
Sandy Rutherford provides some tips on using CMS hosts:
ange-ftp-set-account.
Ange-ftp should automatically detect that you are using a CMS host. If
it fails to do so (which should be reported as a bug) you can use the
command ange-ftp-add-cms-host
to inform ange-ftp manually. For a more permanent effect, or
if you use a CMS host regularly, it's a good idea to set
ange-ftp-cms-host-regexp to a regular expression matching that
host's name.
Ange-ftp has full support, including Tree Dired support, for hosts running the Michigan terminal system, and should be able to automatically recognise any MTS machine.
MTS filenames are entered in a UNIX-y way. For example, if your account was `YYYY', the file `FILE' in the account `XXXX:' on `mtsg.ubc.ca' would be entered as
/YYYY@mtsg.ubc.ca:/XXXX:/FILE
In other words, MTS accounts are treated as UNIX directories. Of course, to access a file in another account, you must have access permission for it. If `FILE' were in your own account, then you could enter it in a relative path fashion as
/YYYY@mtsg.ubc.ca:FILE
MTS filenames can be up to 12 characters. Like UNIX, the structure of the filename does not contain a type (i.e. it can have as many `.''s as you like.) MTS filenames are always in upper case, and hence be sure to enter them as such! MTS is not case sensitive, but an EMACS running under UNIX is.
Ange-ftp should automatically detect that you are using an MTS host. If
it fails to do so (which should be reported as a bug) you can use the
command ange-ftp-add-mts-host
to inform ange-ftp manually. For a more permanent effect, or
if you use an MTS host regularly, it's a good idea to set
ange-ftp-mts-host-regexp to a regular expression matching that
host's name.
Full filename completion is supported on all remote UNIX hosts and some non-Unix hosts. Hostnames also have completion if they are mentioned in the `.netrc' and no username is specified. However using the filename completion feature can be a bit of a two edged sword.
To understand why, we need to discuss how ange-ftp works. Whenever
ange-ftp is asked to find a remote file (or directory) an ls
command is sent to the FTP process to list all the files in the
directory. This list is maintained in an internal cache, to provide
filename completion for later requests on that directory. Ange-ftp keeps
this cache up-to-date by monitoring Emacs commands which affect files
and directories, but if a process outside Emacs (such as another user)
changes a directory (e.g. a new file is added)
completion won't work on
that file since ange-ftp doesn't know about it yet. The solution if to
force ange-ftp to reread the directory and update it's cache, and the
easiest way to do that is with Dired -- See section Using Dired to see how.
Another problem is that the ls command can take a long time,
especially when dealing with distant hosts over slow links. So if you're
after a file in the `pub/images' directory but nothing else, it's a
better idea to type pub/images/file TAB than pub/im TAB
which will force a read of the `pub' directory (since
ange-ftp needs to know how to complete im). A little extra typing
can often save a lot of waiting. Don't be afraid to use the TAB
key once the directory is cached, though.
The FTP process used to access the remote files is available for access if you wish. It will be in a buffer called `"*ftp remote-file-name*"', i.e. if you found the file
/anonymous@archive.site.com:pub/README
there will be a buffer
*ftp anonymous@archive.site.com*
where all the transfers are taking place. You can have a look at the buffer
using C-x b as usual, and even type in commands to the FTP process
under an interface very much like `shell-mode'. There are two
instances when doing this can be very useful: one is accessing non-UNIX
hosts, where Dired and filename completion may not work (if ange-ftp
even works at all). The other is multiple (i.e. wildcard) file transfers
which the standard version of Dired does not handle (but Tree Dired
does, and is worth installing for this feature alone.) If you
are going to use mget or mput, make sure you type
glob first: ange-ftp turns globbing off by default. Don't be
afraid of changing directories, either -- ange-ftp always uses absolute
pathnames when communicating with the FTP process.
You can kill the FTP process at any time simply by killing this buffer. This won't cause ange-ftp any grief whatsoever -- if you later make another request to that host, ange-ftp will simply fire up another process and create a new buffer to hold it.