                    Yet Another Backup Utility
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~

What does it do?
~~~~~~~~~~~~~~~~
It helps to create backups, in particular backups of only the files that
have changed since the last time you backed up.

It was designed for backing up files to large discs such as CDR, hard
discs, zip discs, etc. It won't be much use for floppy discs.

This program comes with no warranty; you use it at your own risk. Having
said that, I trust it enough to use it for my backups.
It is supplied under the GNU general public licence, see the file
Licence for more details.

Why did I write this program?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I had a CD writer, and I used it to backup my data, but it took quite a
long time to back everything up, and most of it never changed anyway. So
I didn't back up as often as I should have done.
When I accidentally wiped my hard disc, I got rather annoyed. Therefore
I decided to write this program so I would backup more frequently.

How does it work?
~~~~~~~~~~~~~~~~~
It copies files from the source directory to the destination
directory, and creates a list of all the files it has copied, including their size
and date stamps.
The next time you want to backup, do the same, but let it have the list
that was generated the first time. It will then only copy files that
aren't on the list, or that have been updated since the list was made.

Isn't this what the Newer option on the filer does?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yes. However the newer option won't work if the destination is read only
such as a CDR, or if the backups are split over several discs.


How do I use it?
~~~~~~~~~~~~~~~~
Double click on the !YABU icon in the filer window. An icon should
appear on the iconbar. Click select on this icon, and a window will
open.

To backup for the first time:

Drag the directory containing the files you want to backup to the source
directory field.
Drag the directory that will contain the backed up files to the destination
directory field.
Drag any directories and files that are in the source directory, but you
don't want backed up, to the exclude field.

Drag the icon next to the new files list to a directory somewhere where
you want to save the list of files. Inside the destination directory is
a good place.

Click on the Backup icon.

A status window will then open, showing the directory currently being
copied, and the number of files copied so far.

When it has finished, click on the close icon.

The destination directory can then be written to CD or whatever, then
deleted.

To backup subsequently:

Set up as for the first time, but drag the files list that was created
from the previous backup to the existing files list field.

Click on the Backup icon.

The status window will open, but this time only files that have changed
or are new since the last backup will be copied.


The files checked field in the status display shows how many files in
the source directory have been check to see if they need copying.
The files copied field in the status display show how many of the files
check have actually been copied.

Files are copied using the Filer Action module (which is the same as is
used when you copy files in the desktop).

Save as default:
If you click on this button then the contents of the window will be
saved and used as the default settings for the future.

Making a list of already backed up files:
If you have already backed up some files, and want to make a list of
those files so that you don't have to back them up again if they haven't
changed, then drag the directory containing the files to the source
directory field, leave the destination directory field blank, and fill in
the new files list field. Then click on the Backup icon.
This will only work if the filenames are unchanged on the backup medium.
For example if you backup to CDR, and all the filenames get translated
to upper case then it will not work as the files will be considered
different. If you write Joliet format CDs and use CDROMFS then this will
not be a problem.

Options
~~~~~~~

There are four options:

Treat image files as directories
If ticked then image files (such as PC partitions, archives if ArcFS or
SparkFS are loaded, etc.) will be treated as directories rather than
files. I recommend you leave this unticked.

Faster
This has the same effect as faster does when normally copying files in
the desktop; it makes the copying faster, but leaves the desktop
slightly less responsive whilst copying. This option will probably only
have any effect on RISC OS 4.

Verbose
This has the same effect as verbose does when normally copying files in
the desktop. If you have this turned on then you may get flickering when
copying small files, as the filer-action window opens then immediately
closes again.

MD5
When this option is selected then YABU uses MD5 checksums to determine
whether a file has changed, rather than the size and timestamp. This is
more robust, but takes a lot longer.
To use MD5, you must have Darren Salt's port of md5sum installed somewhere
suitable (copying it to !Boot.Library is sufficient).
ftp://zap.tartarus.org/pub/ds/GNU/textutils.zip

Note: If you do a backup with MD5 turned on, then later do an incremental
backup of the same files but with MD5 turned off, then all the files will
be treated as if they had changed. (And the same if MD5 is turned off for
the first and on for the second).  


Specifying files on the command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rather than entering all the directories in the main window, it is
possible to create a file containing all the options. The name of this
file can be specified on the command line, and if present YABU will use
the settings in this file and start the backup immediately. When the
backup is finished, YABU will quit.
This makes it is possible to run YABU automatically at specified times,
by setting a task alarm with !Alarm.
For example, you could set a repeating task alarm to start a backup
during each night. The command to use would be something like
<YABU$Dir> IDEFS::Toffee.$.BackupSettings

The format of the backup settings file is straightforward:
The first line is the source directory/directories
The second line is the destination directory
The third line is the list of files/directories to exclude
The forth line is the existing files list
The fifth line is the new files list
The sixth line is a number 0 or 1 indicating whether to treat image
files as directories
The seventh line is a number 0 or 1 indicating whether to enable faster
The eighth line is a number 0 or 1 indicating whether to enable verbose
The ninth line is a number 0 or 1 indicating whether to enable MD5 checksums

If any of the filenames are not needed, then just leave a blank line
in their place.

Time/Date
~~~~~~~~~

All the filenames in the main window or in a settings file are passed
through the standard C function strftime, which allows you to change the
filenames depending on the date or time. For example, if you entered the
destination directory as IDEFS::Toffee.$.Backup-%d-%m-%Y
then, if the date was the 19th of September 2001, it would be expanded to
IDEFS::Toffee.$.Backup-19-9-2001

The valid letters following a % are:
a,A,w	The weekday is output as an abbreviated name (a), full name (A), or decimal (w) with 0=Sunday, 6=Saturday.
b,B,m	The month is output as an abbreviated name (b), full name (B), ordecimal (m) with 1=January, 12=December.
c	The date and time are output in local format.
d	The day of the month is output (01-31).
H,I	The hour is output in 24 (H) or 12 (I) hour format.
j	The day of the year is output (001-366).
M	The minute is output as a decimal (00-59).
p	The 12 hour status (ie AM or PM) is output.
S	The second is output as a decimal (00-61).
U,W	The week of the year is output as a decimal (00-53), counting Sunday (U) or Monday (W) as the first day of the week.
y,Y	The year is output as a decimal, without century (y) or with century (Y).
Z	The timezone name is output (or nothing if none).


What happens when everything goes pear shaped and I need to restore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
my backed up files?
~~~~~~~~~~~~~~~~~~~
This has to be done manually. Copy all files from the first backup to
wherever you want. Then copy the subsequent backups on top of the first,
in the same order as the backups were made.



Problems
~~~~~~~~
If you rename a directory, then all the files within it are deemed to
have changed.

The exclude field only has room for about four or five entries.

If you specify more than one directory in the source field, and within
those source directories there are two files with the same pathname
relative to the directories specified in the source field then only one
of those files will end up in the destination directory (you are
effectivly merging two directories and so any file from one directory
with the same pathname as one from the second directory will get
overwritten by the one from the second directory).

Filename matching for the exclude list is done case insensitively, so
it may cause problems if used on a case sensitive filesystem.

Suggestions for improvements are welcome.
If you find a bug, please let me know, or better still fix it yourself
and send me a patch.

Any updates will be available from
http://www.alexwaugh.com/

Alex Waugh <alex@alexwaugh.com>

