The K Desktop Environment

Next Previous Table of Contents

2. Usage

The first step in using kftpupdater is to create a new project. Choose New project from the File menu. You will be prompted for a name for a project and then fill in a tabbed dialogue with all the information for the project.

2.1 Main tab

On the first tab, you have to specify a hostname for the remote ftp site as well as a username and password. (If you are using kftpupdater to mirror an anonymous ftp site to a local directory then choose "anonymous" for the username and your email address for the password.) Next you have to specify a local directory.

Important There is a check box to specify whether you want to put files in the local directory on to a remote site or get files from the remote site and place them in the local directory. By default, the box is checked (so file transfers are local to remote). Make sure this check box is right for your purpose.

There is another checkbox to delete unnecessary files and directories. If this box is checked then files in the target directory (the one we are transferring files to) that don't occur in the source directory (where we are transferring from) will be deleted. By default this box is unchecked. You should check this if you want to make a perfect mirror of the source directory in the target directory. (Caveat: if you choose to ignore some directories in the source directory by regular expression (see below) then files and directories in (subdirectories of) the corresponding directory on the target will not be deleted by this option.)

Next you should specify the remote directory. If this is left blank then the remote directory will be taken to be the current directory after logging into the ftp site. If you are uploading files to your ISP's server this is likely to be the right choice.

2.2 Regular Expressions

The next tab allows you to ignore some files and directories according to (python) regular expressions. If a file is ignored then this means that even if it has been modified it will not be transferred. If a directory is ignored then this means that files in it and its subdirectories will not be transferred even if they have been modified.

If you leave this tab blank, no files or directories will be ignored.

There are four ways to do this. You can specify that all files which match a regular expression will be ignored, or that all files that don't match a regular expression will be ignored. Likewise for directories.

First we must explain which part of the filename (or directory name) has to match the regular expression. Let's look at an example. Suppose that the source directory (i.e. where we are transferring files from) is /foo and we have a file or directory called /foo/bar/baz. Then when we consider whether this filename matches a regular expression we first strip away /foo/ so that it is actually bar/baz that is tested against the regular expression.

After the source directory has been stripped like this there are two parts to the file or directory name, the prefix and the base. In this example, the prefix is bar/ and the base is baz.

We use a special escape sequence to specify the prefix in regular expressions: \p. So in our example, \p is expanded to become bar/ in a regular expression.

Files (or directories) must make a complete match to be ignored. For example the reg exp \pa will only match files called a in subdirectories of the source directory it won't match a filenames starting with a, for which \pa.* would be the correct regular expression exp.

This option can be very useful. For example, suppose you are uploading the local copy of your homepage to your ISP's server. Perhaps your editor creates backup files. Or perhaps your file manager creates some "invisible" dotfiles you don't want to upload. If you use the regular expression

(\p\..*)|(.*~)
in the "ignore files matching reg exp" box this will stop files called something~ or files called .something being uploaded.

Here's another use. You might be working on /foo/bar/baz but you don't want it to be uploaded yet because it's not finished. Just put bar/baz in the "ignore directories matching regular expressions" box.

Another example. Say you are watching a particular directory on an ftp server for the latest version of some favourite sofware. All you want is the .tar.gz file and none of the other junk in the directory. You also don't want to recurse into any subdirectories. Then you should choose .*\.tar\.gz for the "ignore files which don't match reg exp" box and ".*" for the "ignore directories which match reg exp" box, to stop recursion.

You can read more about python regular expressions in your python documentation. They are similar to perl regular expressions.

Finally on the "Reg Exp" tab you will see a check box. If you check this then if a file or directory in the source directory is ignored (according to one of the regular expression rules you specify) then the corresponding file or directory in the target directory will be deleted.

2.3 Miscellaneous

The remaining options on the final "Misc" tab will not be used by most people. You can specify an alternate log file to save details of transfers for this project. If you leave this entry blank you will get the default: $HOME/update.project-name.log You can also specify a different time stamps database file from the default choice of $HOME/update.project-name.mod.

Finally, If you have to ftp to a gateway before you login to the actual ftp site then use the next two options to specify a second username of the form bar@real.ftp.site and password.

2.4 Starting a project

The next stage is to either choose Init database or Force transfer from the Project menu. The first is used if remote and local files are currently in sync (useful for an existing project). Whereas the second is used if you want to force a transfer of all files (for a new project).

Thereafter you just choose Open project from the File menu and then Transfer from the Project menu, periodically, to update files that have been modfied since the last time.

A good tip if you are trying out some complicated regular expression is to use the Dry Run option from the menu bar. This shows you what will happen if you choose Transfer but no file transfers or deletions actually take place.

You can terminate a running transfer with CTRL S. But note that a file that is interrupted in mid-transfer may destroy the target file. Next time you run a transfer the interrupted file will be transferred.

kftpupdater can be run from the command line.

kftpupdater -h
gives the usage. Included in the kftpupdater distribution is ftpupdater. This is a command line program (doesn't use X) that does the same things as kftpupdater. It uses the same configuration files etc. For details man ftpupdater. ftpupdater is useful, for instance, for scripts that run automatically on connection to the internet. You might find it useful to create a new project using the kftpupdater GUI and then use ftpupdater in a script.

2.5 Keys

CTRL TTransfer modifed files for current project
CTRL DDry run of the current project
CTRL IInitialise the time stamps database for the current project
CTRL FForce a transfer of all files for the current project
CTRL NCreate a new project
CTRL EEdit the current project
CTRL CSpecify a new configuration file
CTRL SStop the current transfer
CTRL Q Quit the utility

On the File menu there are also options to open, edit, or delete an existing project.

Next Previous Table of Contents