MCTDH Backup

Before discussing the MCTDH Backup it is useful to explain the scripts mdircp (MCTDH directory copy) and mdiff (MCTDH directory diff) . These scripts are used in the backup system, but are useful as stand-alone scripts as well.

mdircp copies a whole MCTDH directory, while excluding those files, which were not existent before installation. These are e.g. binaries, object files, *.dvi and *~ files. The files copied can be further restricted by the -i (include only files which match pattern) and -e (exclude files which match pattern) options. The pattern are egrep regular expressions.

mdircp -i /source/ -e /analyse/ dir1 dir2
mdircp -i '(\.html$|\.F$)' dir2

The first example copies all source files except the analyse files from dir1 to dir2. If only one directory is given as argument, $MCTDH_DIR is assumed for dir1. Thus the second example copies all *.html and *.F   (but not *.f)  files from $MCTDH_DIR to dir2. Note that dir2 should not previously exist, it will be created.

With option -T mdircp will produce gzipped tar file (*.tgz), and with option -N   (-N sets -T) it will send the tar file to a remote host.

mdircp -N i77@aixterm6.urz.uni-heidelberg.de MCTDH/mctdh84.5.tgz

This command creates a tar file of the active MCTDH directory and sends it to the remote host aixterm6.urz.uni-heidelberg.de . The tar file is named mctdh84.5.tgz and copied to the directory ~/MCTDH on the remote host. Note that the directory ~/MCTDH may or may not previously exist.
Finally, the option -p prints the list of all files to be copied to screen (and does nothing else). For the full list of options see mdircp -h.



mdiff compares two MCTDH directories. It first checks if there are files which exist on one of the MCTDH directories but not on the other. On request it performs a compare (-c), a diff (-d) or a mgdiff (-m). The list of files to be compared may be restricted by the -i and -e options similar as for mdircp.

mdiff -i '/rdoper.F$' -d dir1 dir2
mdiff -c dir2

will produce a diff of the files dir1/source/mctdh/rdoper.F and dir2/source/mctdh/rdoper.F, i.e. a single file is compared. Again, if dir1 is not given, $MCTDH_DIR is assumed. The second example produces a list of all files which differ between $MCTDH_DIR and dir2.



The MCTDH Backup System
To use the backup system one must first set the environment variable MCTDH_BACKUP. This is most conveniently done in ~/.mctdhrc . E.g. one may set MCTDH_BACKUP=$HOME/MBACKUP . After that one makes a full copy of the (active) MCTDH directory to MBACKUP.

mdircp -b

The option -b is equivalent to providing the argument (i.e. dir2):   $MCTDH_BACKUP/`basename $MCTDH_DIR`  .  The command mdircp -b dir1 will perform an initial full backup of the directory dir1.

When one has modified the code and wants to backup the changes, one simply types

mbackup
or
mbackup -t 'Bug fixed in ..'
or
mbackup -t 'first line of text' \
  -t 'second line of text' \
  -t 'third line of text'

The text, which follows the -t option(s), is written to the log file. It is only for your personal book-keeping. mbackup uses rsync, thus only modified files are copied. As the unmodified files are hard liked to the previous backup, each backup looks like a full backup to the user. The log file is most conveniently inspected with the command

mdircp -s

where -s stand for show. The log file contains the name of the backup-directory, which is the base-name of the MCTDH directory augmented with date and time, e.g.: mctdh84.6_04Feb10_11.43.45 . Then all files are listed, which are backup-ed, and finally the (optional) text, provided through the -t option, is added. The content of the $MCTDH_BACKUP directory is listed when typing: lb.

To restore a backup one simply types

mbackup -rn
or
mbackup -Rn

where  -rn  restores the n-th backup and where   -Rn  restores the n-th backup by counting from the end. Hence,  -r1  will restore the initial full backup and   -R1   will restore the very last backup. Note that restore will overwrite some files on your MCTDH directory. It is thus a good habit to backup directly before restoring. For safety, the files to be overwritten are saved to file_mbk??,   where ?? stands for the day of the month, e.g. 02.
The restore process will delete all files on the current MCTDH directory which do not exist on the selected backup. More precisely, it will move those files to file_mbk??. With the option -k (keep) one may inhibit the deletion of those files.
Similarly, one may delete a backup with the commands mbackup -dn or mbackup -Dn. However, deleting backups is recommended only in rare occasions. One does not save much disk space by deleting a backup. But note that there is no information lost for the remaining backups when deleting a backup.
Finally, the option -n (no action) allows to perform a "dry run" where rsync tells you what it would do, it the -n option would not have been given.

Restoring a backup can also be done with mdircp. With the aid of the -i and -e options, this allows to select files to be restored.

mdircp -i <pattern> -rn
or
mdircp -i '/doc/.*html$' -e /filter/ -R2

The second example will restore only those files from the before-last backup which are on /doc/, end with html, and are not on doc/filter. Note that the selected files will just overwrite the files on the MCTDH directory. In contrast to mbackup -rn there is no saving of these files.
With mdircp one may in particular restore a backup to a different location. I.e.

mdircp -r2 -n mctdh84b

will create the directory mctdh84b on the current directory and copies the second backup to this directory. The option -n (new) must be given, because otherwise mdircp will try to backup to mctdh84b from an mctdh84b backup directory. The latter does not exist. The new directory may be installed by running mctdh84b/install/install_mctdh.

There is a subtle difference between restoring with mbackup or with mdircp. When restoring with mbackup only files which differ are copied from the backup directory to the MCTDH directory. The files copies are give a new time stamp, so they are newer than the files which they have replaced. When calling compile this ensures, that the restored files will be compiled again; their corresponding object files are not simply read from an archive. mdircp, on the other hand, simply copies the whole backup directory, or specified files thereof, to the MCTDH directory. It preserves the old time stamps. This may lead to problems when compiling. compile -A will solve this problem, but this way is inconvenient. One may use mdiff to touch all files on the MCTDH directory which differ from the backup. E.g.:

mdiff -t -i /source/ -R2

The include pattern /source/ is given here, because it is in general only useful to touch the source files. For all other files it seems to be more convenient to preserve their original time stamp. If one has run mdircp -r with include/exclude options, it may be useful to run mdiff -t with the same include/exclude options, because one does not want to touch other files than the updated ones.


The differences between the current version and a backup, or between two backups, may be inspected with mdiff. As mdiff is described above, we can be brief here. The command

mdiff -R1 -d

will produce a diff between the active MCTDH version and the very last backup, and the command

mdiff -R2 -R3 -c

compares -- i.e. only lists the names of the files which differ -- of the before last and the before before last backup.

Finally,

mdiff -R1 -m -i /propwf/

will use mgdiff to show the differences of all propwf files which differ in the current MCTDH directory from the last backup.