histbackup - backup a directory using an incremental technique


histbackup [options...] [host:]source backupdir [otherbackupdirs...] [rsyncopts...]

histbackup [options...] --no-rsync parent


histbackup makes incremental backups of a directory tree in a set of directories named by dates, or date-time if the date already exists. The new backup is prepopulated by hardlinks of each file from the previous backup and then updated with rsync(1). This arranges that the only new content of each new backup is fresh copies of the changed files. In this way each backup directory is a full copy of the source directory but the disc space cost is that of an incremental backup. Because it uses rsync, it is possible efficiently to backup remote directories in this manner. The companion script histbackup-prune keeps the growth under control.


Before deployment, decide who will own and do the backups. Do all the local (backup end) setup as that user. If you're not a sysadmin then that user is probably yourself.

Generally, setup is as follows:

Create the backup area.

Decide where the backup data will be. Make an empty directory to hold it:

        mkdir /path/to/backup/area
Arrange access to the source data

If the data to backup are local to this machine you merely need read access to it. If the data are remote you will need ssh(1) access to the remote host as a user with read access to the data there. Test it:

        ssh user@remote ls -l /path/to/source/directory
Perform a test backup

Histbackup does the right thing when the backup area is empty so just:

        histbackup -x user@remote:/path/to/source/directory /path/to/backup/area
Schedule your backups

If these backups are to happen regularly a crontab(5) entry should be made to do so. Use "crontab -e" to make this. Example:

        0 * * * * histbackup -x user@remote:/path/to/source/directory /path/to/backup/area

That will run a histbackup every day at midnight, delivering the output of the run by email to backup-admin@yoursite.

Note that cron's environment is very spartan (it does not source /etc/profile or ~/.profile) and so you may need to arrange that the CSS package's environment is present. Also, because cron is a batch situation, your ssh access will almost certainly require a special purpose passphraseless key to access the remote host.



Suppress passing the --delete or --delete-excluded option to rsync.


Skip the rsync step; just create the new link tree.


Proceed even if the linktree step fails, presumably due to reaching the filesystem hard link limit. Does a repair rsync from the previous to new backup before proceeding.


Passed to rsync.


Passed to rsync. Also implies --delete.


Do not honour the .hbfiles file in the backup directory.


Do not honour the .hbinclude file in the backup directory.

--rsync-path rrsync

Passed to rsync. Specifies the pathname to the remote rsync executable.

--symlink name

After the backup is done, make a symbolic link named name pointing at the latest backup directory. This is useful so that other programs may trivially reference the latest backup without having to figure out its name. Eg: --symlink LATEST.

-i, --itemize-changes

Itemise changes. Passed to rsync, but histbackup strips a few noisy outputs.

-v, --verbose

Turn on verbose mode; also passes -v to rsync.


Trace execution of important commands (rsync, linktree etc).

Post Option Arguments

If the --no-rsync option has been used, only the destination directory appears after the options. It will be initialised for use.

Otherwise, the source and destination appear. These may be followed by otherbackupdirs, the full paths of other directories like the one histbackup is copying; these will be handed to rsync(1) as --link-dest options. After the otherbackupdirs, other rsync(1) options may be supplied; these will be passed to rsync.


If the file backupdir/.hfiles is present the options "-r --files-from=backupdir/.hbinclude will be added to the rsync command invocation. In this way specific contents may be backed up. See rsync(1).


Cameron Simpson <> 03apr2000


histbackup-prune(1cs), linktree(1cs), rsync(1), ssh(1), cp(1), cpdir(1cs)