copyback Users Guide

copyback is a simple program for backing up files, directories or the output from programs. It is simple because the backups are just copies of the files and directories it is told to backup. If the output from a program is backup up, that is also stored in a plain file. It is simple also because it does not apply any advanced algorithms for incremental updates of existing backups. Instead, backups are updated simply by replacing modified files and adding new files.

copyback copies and updates files and directories using the program rsync. It can therefore be seen as a wrapper for rsync.

What copyback tries to be good at is organizing backups of different sources using a logical and useful directory layout. For example, by default the directory layout of files in a user's home directory is preserved: a backup of a file ~/a/b/file.txt is stored in the directory COPYBACK_ROOT/home/a/b/file.txt. Here COPYBACK_ROOT is the directory where copyback stores all backups. COPYBACK_ROOT is set either by the environment variable with the same name or using the command line option --root=COPYBACK_ROOT.

A goal in the design of copyback is that it should be flexible in the way it chooses the directory layout for storing backups. It tries to choose a good default, as well as letting the user specify it if the default is not appropriate.

copyback can manage a many backups made at different times for a single source (a source is a file, directory or the output from a program).

copyback is quite easy and straight forward to use.

Example 1. Backing up a file using copyback

Suppose the environment variable COPYBACK_ROOT is set to ~/my-backups and that you have started a shell with the current directory of ~/my-dir. In this directory there is a file my-file-txt that you want to backup.

~/my-dir$ copyback my-file.txt
~/my-backups/home/my-dir/my-file.txt/copyback-20070506-1430

The second line is the filename of the backup. This file is a copy of my-file.txt. It also has got the same mode and modification time. The string 20070506-1430 in the filename is the date and time of when the backup was created.

Some examples of when copyback may be useful.

As a backup solution for a small project that you don't want to set up a Version Control System for.
For making backups in between commits of a project that you use a Version Control System for.
While experimenting with files and directories you later want to backup using a Version Control System.
As a simple backup solution for all files you want to backup.

What copyback is NOT

copyback is not designed to replace existing common backup tools and strategies. For example, copyback is NOT ...

an advanced backup solution for systemwide incremental backups (such as "dump" and "restore"),
a Version Control System (such as "cvs" and "Subversion"),
a replacement for using a Version Control System.

Invoking copyback

General syntax

Each invocation of copyback executes one of several commands.

The general syntax is

copyback [GENERAL-OPTIONS] COMMAND [COMMAND-OPTIONS] [COMMAND-ARGUMENTS]

See "Commands" for a description of the syntax and options accepted by each command.

Most commands has a (shorter) alias.

Commands that operate on a project directory

Many commands that operate on a project directory (for example list and clean) has two forms.

1. Give the project directory explicitly:

copyback [GENERAL-OPTIONS] COMMAND [COMMAND-OPTIONS] [ --explicit | [-e]] DIRECTORY

2. Give the project directory implicitly by supplying the same SOURCE and backup options as was used when creating the backup:

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] COMMAND [COMMAND-OPTIONS] [SOURCE]

(Not all of the backup options are relevant here, only the "Naming scheme options".)

Generally, SOURCE can be specified either as an argument or using the option --source=SOURCE.

Creating and updating backups

The backup command is the default command. It can be left out as long as the other arguments don't clash with any of the other command names.

The simplest syntax for creating and updating backups:

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] SOURCE

The following syntaxes are all equivalent to the one above, and may be useful in different circumstances:

copyback [GENERAL-OPTIONS] backup [BACKUP-OPTIONS] SOURCE

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] --source=SOURCE

copyback [GENERAL-OPTIONS] --source=SOURCE backup [BACKUP-OPTIONS]

Tutorial

The following sections explains copyback using some sample sessions. Hopefully even newbies can understand it. Experienced users might find the the explications a bit too clear, though!

Note

In the output from copyback, the character ~ is used to denote the users home directory.

This is for making the output a bit clearer. In practice, the actual directory name, such as /home/scott, will be printed instead.

Note

Some blank lines are inserted into the computer output.

This is also not (usually) true in practice, but it makes the example sessions a bit clearer.

The Calculator example

Suppose we are working on a calculator program in the the directory ~/programs/Calculator. Suppose that this is the current directory in our shell so that we can use the name '.' (dot) to refer to it.

First of all, let us use list the files of the our Calculator using ls.

~/programs/Calculator$ ls
calc.c
Makefile
report.tex

Setting the backup root directory

Before we can create backups we must tell copyback in which directory it should store the backups. The easiest way to do this is to set the environment variable COPYBACK_ROOT. Suppose we want to store our backups under the directory ~/my-backups.

If we are using the bash or sh shell, we can set COPYBACK_ROOT with the following shell command:

~/programs/Calculator$ export COPYBACK_ROOT=~/my-backups

If we are using the tcsh shell, we can set COPYBACK_ROOT with the following shell command:

~/programs/Calculator$ setenv COPYBACK_ROOT ~/my-backups

To check that copyback really uses this directory we can issue the copyback command backup-root-directory:

~/programs/Calculator$ copyback backup-root-directory
~/my-backups

This directory is called the backup root directory. See "Storing all backups under a personal backup root directory" for a detailed description of how to set it.

Creating and listing a backup

Now we want to make a backup of the Calculator directory. Since it is the current directory, we can use '.' (dot) to refer to it. Create a backup using the the copyback command backup:

~/programs/Calculator$ copyback backup .
~/my-backups/home/programs/Calculator/copyback-20070205-1030

The line printed by copyback is the name of the directory that is the backup. The string 20070205-1030 is the current date and time. It will of course be different if copyback is run at a different time!

We can use ls to check that it contains all our files:

~/programs/Calculator$ ls ~/my-backups/home/programs/Calculator/copyback-20070205-1030
calc.c
Makefile
report.tex

We can also let copyback confirm that we have created a backup. Do this by listing existing backups using the copyback command list:

~/programs/Calculator$ copyback list .
copyback-20070205-1030

copyback responds by listing all existing backups of the directory . (dot), which in our example is ~/programs/Calculator. As expected, only one date is printed, since we have only made one backup yet.

copyback can also present the backup in a more formatted way:

~/programs/Calculator$ copyback --print-formatted list .
2007-02-05 10:30

Creating more backups

Suppose we work on the Calculator for a couple of hours until we reach a version we want to be sure not to loose. At 11:15, we create one more backup:

~/programs/Calculator$ copyback b --tar --gzip .
~/my-backups/home/programs/Calculator/copyback-20070205-1115.tar.gz

The copyback command used is still backup, but we use its shorter alias 'b'. Most commands and options have a shorter alias.

The options --tar and --gzip tells copyback to put all files in a tar archive, and then to compress this archive using gzip. The extension .tar.gz of the backup reflects this.

The options --tar and --gzip has the shorter aliases -T and -z, respectively

Again, we want to check the contents of our backup. This time we must use the program tar to view it since it is a tar archive:

~/programs/Calculator$ tar tzf ~/my-backups/home/programs/Calculator/copyback-20070205-1115.tar.gz
calc.c
Makefile
report.tex

Listing backups, again

We let copyback confirm that we created a new backup in the last section. Now we use the short alias 'l' for list:

~/programs/Calculator$ copyback l .
copyback-20070205-1030
copyback-20070205-1115.tar.gz

We see that both our backups are present. They are listed one per line and in creation time order. copyback list always lists backups this way.

But each backup can be presented in some different manners. Use one of the following options to decide the format: --print-filename, --print-filename-extra, --print-formatted. These are general options that apply to many commands, not only list.

--print-formatted presents each backup in a clearer format:

~/programs/Calculator$ copyback --print-formatted l .
2007-02-05 10:30
2007-02-05 11:15

Updating backups

Suppose we are satisfied with our current version of the calculator, except that we remember that it is good practice to have a README file. We wish we had written the README file before we made the last backup, so it had been included in it.

We could achieve this by creating a new backup and then deleting the backup file copyback-20070205-1115.tar.gz manually. But an easier ways is to let copyback update the last backup.

Updating a backup modifies it to be an exact copy of the source. This includes adding, modifying and removing files in the backup. The date and time of the updated backup is set to the current date and time.

Updating is done by adding the --update option to the command backup, together with specifying which backup to update:

~/programs/Calculator$ copyback backup --update --last .
copyback: Updating backup: copyback-20070205-1115.tar.gz
~/my-backups/home/programs/Calculator/copyback-20070205-1135

copyback prints a message informing us that it updating an existing backup.

The updated backup is copyback-20070205-1135. Note that this is not a gzip'ed tar archive as the original backup was. copyback only looks at the command line options to decide how it create backups, never at old backups. You would have to supply --tar and --gzip (or -Tz) to make the updated backup a gzip'ed tar archive, too.

Use ls to check that the README file is in the backup:

~/programs/Calculator$ ls ~/my-backups/home/programs/Calculator/copyback-20070205-1135
calc.c
Makefile
README
report.tex

Removing old backups

There is one copyback command to remove existing backups. It is the command clean, which removes all but the latest existing backups. If there is only one backup, no backup is removed.

The following session first uses the command list to list the existing backups, then copyback clean is run, and then the remaining backups are listed.

~/programs/Calculator$ copyback list .
copyback-20070205-1030
copyback-20070205-1135

~/programs/Calculator$ copyback clean .
copyback-20070205-1030

~/programs/Calculator$ copyback list .
copyback-20070205-1135

Preventing backups from getting updated or removed

A backup can be "locked" to prevent it from getting updated or removed.

Suppose we still have the two backups we had before we clean'ed our Calculator directory:

~/programs/Calculator$ copyback list .
copyback-20070205-1030
copyback-20070205-1135

We lock the backup copyback-20070205-1030 using the copyback command lock. We use the --date option to tell which backup to lock:

~/programs/Calculator$ copyback lock --date 20070205-1030 .

Now we run the command clean again, and then list the existing backups:

~/programs/Calculator$ copyback clean .
copyback: Skipping locked backup: copyback-20070205-1030

~/programs/Calculator$ copyback list .
copyback-20070205-1030*
copyback-20070205-1135

No backup has been removed since the command clean only removes non-locked backups and never removes the last backup.

An asterisk - '*' - is printed after the backup copyback-20070205-1030 to inform us that it is locked.

Locked backups are unlocked by the command unlock:

~/programs/Calculator$ copyback unlock --date 20070205-1030 .

~/programs/Calculator$ copyback list .
copyback-20070205-1030
copyback-20070205-1135

The last existing backup can be locked/unlocked using the option --last (or -l):

~/programs/Calculator$ copyback lock --last .
copyback-20070205-1135

~/programs/Calculator$ copyback list .
copyback-20070205-1030
copyback-20070205-1135*

Locking affects updating using `copyback backup --update', and cleaning using `copyback clean'. Both of these commands can be forced to operate even on locked backups using the --force (or -f) option.

Excluding selected files

If there are selected files in the directory that you don't want to have backups of, you can "exclude" these.

While working on our Calculator project, the files `calc' and `calc.o' are generated from `calc.c':

~/programs/Calculator$ ls
calc      calc.c  calc.o
Makefile  README  report.tex

We don't want these in our backups. We exclude them using the option --exclude (or -e):

~/programs/Calculator$ copyback backup --exclude=calc --exclude='*.o' .
~/my-backups/home/programs/Calculator/copyback-20070205-1210

~/programs/Calculator$ ls ~/my-backups/home/programs/Calculator/copyback-20070205-1210
calc.c
Makefile
README
report.tex

--exclude=calc causes the file `calc' to be excluded. --exclude='*.o' causes all files ending with `.o' to be excluded.

Since it is so common to exclude selected files copyback will by default look for a hidden file called `.copyback-exclude' and read exclude "patterns" from it. A `.copyback-exclude' file for excluding the files above looks like this:

calc
*.o

If we create this file we can use `copyback backup' without the --exclude options. But since .copyback-exclude is a hidden file, we need to use the ls option -A to see all files in the backup:

~/programs/Calculator$ copyback backup .
~/my-backups/home/programs/Calculator/copyback-20070205-1215

~/programs/Calculator$ ls -A ~/my-backups/home/programs/Calculator/copyback-20070205-1215
calc.c
Makefile
README
report.tex
.copyback-exclude

copyback uses the rsync program for creating backups, and these "patterns" are rsync "exclude patterns". See "Options forwarded to rsync" or the rsync manual for details.

Using copyback conveniently

If a SOURCE is backued up frequently it is recommended to make a shell alias that does the job.

Lets say we want an alias `cbc' for backing up the Calculator directory, and that we want each backup to be a gzip'ed tar archive.

Using the bash or sh shell, you achieve this as follows:

$ alias cbc='copyback --tar --gzip --source ~/programs/Calculator'

Using the tcsh shell use the following:

$ alias cbc 'copyback --tar --gzip --source ~/programs/Calculator'

Now we can create backups like this:

$ cbc b
~/my-backups/home/programs/Calculator/copyback-20070205-1500.tar.gz

Or even like this (because backup is the default command):

$ cbc
~/my-backups/home/programs/Calculator/copyback-20070205-1500.tar.gz

List the existing backups like this (using the sort alias 'l' for list):

$ cbc l
copyback-20070205-1135
copyback-20070205-1500.tar.gz

Update the last backup (using the short alias -u for --update, and -l for --last):

$ cbc -ul
copyback: Updating backup: copyback-20070205-1500.tar.gz
~/my-backups/home/programs/Calculator/copyback-20070205-1505.tar.gz

Lock all backups --all, and list them:

$ cbc lock --all
copyback-20070205-1135
copyback-20070205-1505.tar.gz

$ cbc l
copyback-20070205-1135*
copyback-20070205-1505.tar.gz*

Do a clean and list the backups. An "ordinary" clean will not remove any backups since they are all locked. But adding the option --force (or the short alias -f) will do:

$ cbc clean
copyback: Skipping locked backup: copyback-20070205-1135

$ cbc l
copyback-20070205-1135*
copyback-20070205-1505.tar.gz*

$ cbc clean --force
copyback-20070205-1135

Organizing backups in directories

copyback has put all the backups of the previous sections in the directory ~/my-backups/home/programs/Calculator.

You may now wonder how this directory was chosen.

The name consists of two parts: the backup root directory and the project name:

~/my-backups

This is the backup root directory we set earlier using the environment variable COPYBACK_ROOT.

See "Storing all backups under a personal backup root directory" for a detailed description of how to set it.

home/programs/Calculator

This is the project name. copyback calls each item it creates backups of for a project, and each project has a project name. In this case the project is the directory ~/programs/Calculator.

In our example, copyback has chosen the default project name since we have not specified one ourselves.

The part home is chosen since the project is a directory within the home directory ~. The part programs/Calculator is of course chosen since this is the name of the directory following the name of the home directory.

See "Project naming schemes" for a detailed description of how to set the project name.

You can ask copyback to print these parts for you:

~/programs/Calculator$ copyback backup-root-directory
~/my-backups

~/programs/Calculator$ copyback project-name .
home/programs/Calculator

The backup root directory followed by the project name is the project directory. This is where all backups for your project are stored. You can ask copyback to print this for you too:

~/programs/Calculator$ copyback project-directory .
~/my-backups/home/programs/Calculator

Description

The items copyback can backup

copyback can backups three kinds of items:

a file
a directory
program output

These items are the SOURCE argument to copyback.

The "output" from a program means the output to the standard output channel (stdout). In this case, SOURCE is the command line for running the program. A special case of program output is '-' (dash). When SOURCE is this string, the contents of the standard input channel (stdin) is backed up.

Representation of backups - backup files

A backup of a file/directory is a copy of that file/directory. A backup of program output is a file storing the output.

Files and directories are copied using rsync. See "Usage of rsync" for details.

Directories can be archived in a single tar archive (using --tar).

Backup files and directories can be compressed using gzip (using --gzip). Compressing a directory means compressing all files in it.

If a directory is both tar'ed and gzip'ed, the result is of course a gzip'ed tar archive.

Backup filenames

Each backup is stored in a file with a standard name, each matching this extended regular expression:

copyback-[[:digit:]]{8}-[[:digit:]]{4,6}(-[^/.*"]+)?($|\..+)

Warning

Source files matching this expression are not guarrantied to be backed up correctly. The behaviour of trying to backup such files is undefined.

Example 2. Example of backup filenames

copyback-20010203-1020
copyback-20010203-1130.tar
copyback-20010203-1230-version 1
copyback-20010203-123012-version 2.tar
copyback-20010203-123013.tar.gz
copyback-20010203-123012.gzs

This name encodes the following information:

datetime of the creation of the backup
a "tag" string
type of backup file

The format of the creation datetime is YYYYMMDD-hhmm or YYYYMMDD-hhmmss. The second format is used if there already is a backup for the same minute.

YYYY, MM, DD, hh and mm and ss are the current year, month, day-of-month, hour, minute and seconds, respectively.

This encoded creation time is used for sorting the backups in creation time order. This is used by some of the commands for locating backups, so it is important.

Warning

Time-zones are ignored. These are not encoded in the filename.

Warning

copyback can only create one backup of a source for each single second.

Note

The modification time is not used to store the creation time since the modification time is an attribute that should be backed up.

The "tag" string is a an optional string used for referring to backups using --tag. Each tag must be unique among the backups for a single source.

The type of backup file is encoded in the filename extension.

Backup filename extensions

The type of backup file is as usual encoded in the extension - the part following the first dot.

By default, backup names have no extension.This indicates that the backup is a plain copy of SOURCE (if it is a file or directory).

The following extensions are used by copyback to identify different types of "postprocessed" backups:

gz: A backup of a file or the output from a program. The contents has been compressed using gzip.
gzs: A backup of a directory. All files in it has been compressed using gzip.
tar: A backup of a directory. All files in the directory has been archived in a single tar archive.
tar.gz: A backup of a directory. All files in the directory has been archived in a single tar archive, which has in turn been compressed using gzip.

Warning

These extensions tell copyback how to update a backup. Don't change them!

Storing all backups under a personal backup root directory

The backup of each item is stored as a file or directory under a personal backup root directory. This directory should only be used for storing copyback backups.

The backups for each item are stored in a separate subdirectory of the backup root directory.

The backup root directory is supposed to be personal. Each user should have its own directory. (It is not impossible for several users to share it, but then special care must be taken so that the different sources are not stored in the same directory. This can lead to lost information.)

The backup root directory is most commonly set using the environment variable COPYBACK_ROOT. It can also be specified on the command line using the option --root=DIRECTORY. The --root option overrides COPYBACK_ROOT.

See Options for setting the backup root directory and Environment for details.

A system-global backup root directory

A global backup root directory can be used if copyback is used by many users on the system, and the backups for all these users should be stored under a common directory. The global backup root directory is set using the environment variable COPYBACK_ROOT_GLOBAL or the --root-global=DIRECTORY option.

The backup root directory for each user will by default be set to DIRECTORY/users/USER. USER is the name of the (effective) operating system user.

If --root-global-suffix=STRING is used, the backup root directory for each user will be set to DIRECTORY/STRING.

Note

Each user can override this using COPYBACK_ROOT or --root.

Organization of backups using projects

copyback can keep many backups from different times of each SOURCE. And of course, it can keep backups of many different SOURCE's. To do this it, organizes them into projects. Basically, each SOURCE is a project.

A project consists of three things:

a project source
a project directory
a project name

The project source is the same as SOURCE - the item to backup.

The project name is a unique name. The name is used for deriving the project directory.

The project directory is a unique directory where all backups for the project are stored. The name of this directory is the backup root directory appended by the project name. The project name can include slashes ('/') to specify subdirectories.

Usually you just have to supply the SOURCE. copyback will, by default, derive the project name from the (absolute) filename of SOURCE. This name is then used to derive the project directory. This default behaviour will organize the backups into a directory tree layout that resembles the directory tree storing the SOURCEs.

Warning

Each item must have a unique name.

Otherwise backups of different items will be stored in the same directory, and copyback will not be able to separate between them.

Warning

It is possible to backup a single item using different project names.

This will cause the backups to be stored in different directories. copyback is not able to tell if backups in different directories originate from the same source.

The project name needs only be unique among all the projects who's backups are stored under the current backup root directory. Since this directory is usually personal, you don't have to care about other people's backups.

copyback uses project naming schemes for determining project names. It has a default naming scheme, which uses part of the absolute filename of files and directories. This naming scheme is sufficient most of the time.

If the source is program output, a name has to be supplied explicitly using --constant=NAME.

See "Project naming schemes" for more information on naming projects.

Overview of the parts making the project directory

The construction of the project directory can seem a bit complicated. The purpose is of course flexibility.

For normal use of copyback, the project directory is derived automatically - you don't have to care about it at all.

Anyway, the following picture tries to give an overview:

|-----------------------------project-directory---------------------------|
|--------------bak-root-----------------||----------prj-name--------------|
                                         |-prj-name-head-||-prj-name-tail-|
|-bak-root-global-||-users/USER---------||----------prj-name--------------|
|-bak-root-global-||-global-root-suffix-||----------prj-name--------------|

Each of these parts can be set by the user.

The backups of a project are stored in a project directory.
The project directory is constructed by adding the backup root directory and the project name, separated by a slash.
The project name is constructed by adding theproject name head and the project name tail to the , separated by a slash.
The backup root directory is set by either ...
- the option --root=DIRECTORY
- the environment variable COPYBACK_ROOT
- adding the global backup root directory and users/USER, where USER is the name of the operating system user
- adding the global backup root directory and the global root suffix.
The global backup root directory is set by either ...
- the option --root-global=DIRECTORY
- the environment variable COPYBACK_ROOT_GLOBAL

Project naming schemes

The project name is constructed from the project name head and the project name tail separated by a dash ('/').

The reason for having the project name head is to reduce the risk of having the same project name for different source.

Warning

Giving two different sources the same name can cause copyback to overwrite backups of one source with backups of the other source.

Default naming schemes for files and directories

copyback uses a default naming scheme for sources that are files or directories:

If the file/directory is a file in a (a subdirectory of) the users home directory. The --suffix-home naming scheme will be used.
The name will be
home / absolute-name-of-source-file-with-name-of-home-directory-removed
- home is the project name head
- absolute-name-of-source-file-with-name-of-home-directory-removed is taken from the absolute filename of the source file. This is the project name tail.
If the file/directory is a file in a (a subdirectory of) outside the users home directory. The --absolute naming scheme will be used.
The name will be
root / absolute-name-of-source-file
- root is the project name head
- absolute-name-of-source-file is the absolute filename of the source file. This is the project name tail.

No default naming scheme for program output

A project name tail must be supplied using --constant=NAME.

By default, the project name head is set to other.

Custom naming schemes

For any project, the name can be set by the user.

The project name head can be set using --project-name-head=NAME or --pnh=NAME. It can also be discarded by using these options without an argument.

See "Naming scheme options" for different ways to set the project name tail.

Usage of rsync

Files and directories are copied using rsync.

rsync is always given at least the option --archive. This copies directories recursively and preserves most attributes. Symbolic links are copies as symbolic links.

"Options forwarded to rsync" describes options that are forwarded from copyback to rsync without modification.

If the source is a directory and this directory contains a file called .copyback-exclude, then rsync exclude patterns will be read from it. This is equivalently to using --exclude-from=FILE. Files matching any of the patterns will be excluded from the backup. The patterns are like shell patterns. See the rsync manual for details.

If --update is used, rsync is also given the option --delete-excluded. This means that both files without counterpart under SOURCE and excluded files are removed from the updated backup.

Commands

`backup` - Creating and updating backups

Creates a new backup or updates an existing one.

Synopsis of `backup`

copyback [GENERAL-OPTIONS] backup [BACKUP-OPTIONS] SOURCE

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] backup SOURCE

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] SOURCE

copyback [GENERAL-OPTIONS] backup --source=SOURCE [BACKUP-OPTIONS]

copyback [GENERAL-OPTIONS] [BACKUP-OPTIONS] --source=SOURCE backup

Short alias: b

BACKUP-OPTIONS can appear both before and after the command name.

The backup command is the default command. This means that the command name can be left out if the string SOURCE doesn't clash with any of the command names or aliases.

Description of `backup`

Creates a new backup or updates an existing backup of the source and puts it in the project directory.

The date and time of the backup filename is set to the current date and time. This also applies to updated backups.

If SOURCE is a file or directory (--file or --directory), the backup is a copy of it created with rsync. See "Usage of rsync" and "Options forwarded to rsync" for information about how rsync is used.

If SOURCE is a program (--program), the backup is a file with the contents of what the program outputs to the standard output channel (stdout). SOURCE is expected to be a command line that can be executed. If executed the program results in a non-zero exit status, no backup is created. If SOURCE is '-' (dash), the contents of standard input channel (stdin) is backed up.

By default, the filename of the backup file is printed (to stdout) followed by asterisks if the backup is locked. This is the output format specified by the general option --print-filename-extra. To be sure that the filename only is printed, the general option --print-filename should be used.

Existing backups can be updated using --

"Default options" describes which default values for some options.

Default options

If the source type is not specified (using one of --file, --directory and --program) it is assumed to be either file or directory. SOURCE will be checked to determine which of these it is.

If a project naming scheme is not specified, one will be derived from the absolute filename of SOURCE. This requires the source type to be either file or directory. copyback will not try to derive one automatically if the source type is program. If the files absolute filename begins with the name of the current user's home directory (as given by the shell environment variable HOME), --suffix-home will be used. Otherwise --absolute will be used.

Options for `backup`

Naming scheme options

These options set the project name (directly or indirectly). This project name has the form of a directory and is appended to the backup root directory to form the project directory. All backups for a source (the project source) are stored in this project directory.

When the project source is the output from a program, --constant must be used.

--absolute | -a

The project name is the same as the absolute filename of SOURCE.

The project name head will be defaulted to root (equivalent to --project-name-head=root).

--basename | -b

The project name is the basename of the (absolute filename of) SOURCE. (This is the string following the last slash ('/').)

The project name head will be defaulted to other (equivalent to --project-name-head=other).

--constant=NAME | -c NAME

A constant project name (used just as it is, not derived from any other information). name can't begin with a "/" or use the relative path components "." or "..".

The project name head will be defaulted to other (equivalent to --project-name-head=other).

--suffix=PREFIX-DIRECTORY | -s PREFIX-DIRECTORY

The project name is the absolute file name of the source file with this prefix removed. PREFIX-DIRECTORY must really be a prefix of the absolute source file name. PREFIX-DIRECTORY must also be an existing directory. It is the absolute path of PREFIX-DIRECTORY that is used, not PREFIX-DIRECTORY itself.

The project name head will be defaulted to other (equivalent to --project-name-head=other) if the given prefix is not the users home directory. If it is, it will be defaulted to home.

--suffix-home | -h

Special case of --suffix. The prefix is automatically set to the home directory of the current (effective) user.

This is the default naming scheme for files and directories in the current users home directory.

The project name head will be defaulted to home (equivalent to --project-name-head=home).

The current users home directory is read from the shell environment variable HOME.

--project-name-head[=STRING] | --pnh[=STRING]

With argument: sets the project name head to STRING.

Without argument: removes the project name head. The project name will consist of only the project name tail.

If --project-name-head is not used, the default value will be used. This default value depends on the naming scheme used.

Options forwarded to rsync

The following options are rsync options that copyback accept. copyback forwards them to rsync without modification. A short description is included here. Consult the rsync manual for more information.

--chmod=MODE

Apply one or more comma-separated "chmod" strings to the permission of the source files. This is a way to modify the permission of backed up files. For example, it is useful if the source files are on a file system that don't handle permissions well.

--exclude=PATTERN

Exclude files matching the shell pattern PATTERN.

--exclude-from=FILE

Read rsync exclude patterns from the file FILE.

--include=PATTERN

Include files matching the shell pattern PATTERN.

--include-from=FILE

Read rsync include patterns from the file FILE.

--cvs-exclude

Use the same exclusion mechanism as cvs does (The "Concurrent Versions System"). Consult the cvs manual for more information.

--filter=RULE

This requires a version of rsync that supports the option --filter.

Add the rsync filtering rule RULE. Filter rules are a more advanced way of specifying files to include and exclude.

Example 3. Examples of filter rules

To exclude all files that matches the shell pattern "*.o":
```
- *.o
```
This excludes all files that matches "*.o", in the current (where the .rsync-filter files is found) directory and all its subdirectories!
To exclude the file program, only from the current directory:
```
- /program
```

-F

Causes rsync (the program that copies files and directories to backups) to read "filter rules" from a file called .rsync-filter.

rsync looks for this file in the SOURCE directory, and each of its subdirectories. If there is one such file, rsync include/exclude filters are read from it and applies them to the files in the directory itself and its subdirectories.

See the option --filter (or the rsync manual, of course) for a description of rsync filter rules.

Only meaningful when SOURCE is a directory.

This runs rsync with the -F option.

Note

This requires a version of rsync that supports the option --filter.

Other options

--directory

Says that the source is a directory. With this options, copyback fails if the source is not a directory.

If none of the options --file, --directory and --program are given, the source must be a file or directory. copyback will look at the source to see what it is.

--extension=EXTENSION | -E EXTENSION

Only available when the source is the output from a program (--program).

EXTENSION is appended, together with a separating dot, to the backup file.

--file

Says that the source is a file (not a directory). With this options, copyback fails if the source is not a file.

If none of the options --file, --directory and --program are given, the source must be a file or directory. copyback will look at the source to see what it is.

--force | --f

Force. Makes copyback update locked backups.

Updates (--update) will be able to operate on locked backups. If a locked backup is updated, the resulting backup will also be locked.

Backups locked by write protected lock files are never updated, not even using --force.

--gzip | -z

Compress all backup files using gzip.

If the project is a directory, and --tar is not also used, all files in the directory will be compressed individually! If --tar is also used, the directory will first be archived using tar, and then this file will be compressed using gzip.

--lock | -L

Lock the backup, preventing some of the copyback commands to operate on it (unless --force'd). But even if --force is used, backups with a write-protected lock file will note be operated upon.

A backup is locked if there exists a corresponding lock file. A lock file is an ordinary file in the same directory as the backup. The name is the name of the backup, excluding any extension, and with the new extension ".lock" added.

Lock files are created with a permission that allows writing.

A locked backup can be unlocked using `copyback unlock', or by removing its corresponding lock file manually.

--no-delete | -n

Only applicable together with --update and when the source is a directory.

Prevent files of the updated backup from being deleted. This affects both files that are excluded from the backup using rsync filters and files in the backup without any counter part in SOURCE.

--program

Says that the source is the output from a program. SOURCE is the program to run. The output from it (to stdout) is backed up.

No backup is created if the program exits with non-zero status.

The constant (--constant) naming scheme must be used.

If SOURCE is '-' (dash), the contents of stdin is backed up.

--rsync-filter

This requires a version of rsync that supports the option --filter.

Same as -F. (See "Options forwarded to rsync".)

--source=SOURCE

Sets the source file, directory or program to SOURCE.

This is an alternative to giving the source as the first non-option argument.

The reason for having this option is to make shell aliases more usefull.

For example, if a source X is often backed up, a shell alias cbx could be defined as

copyback GENERAL-OPTIONS BACKUP-OPTIONS --source=X

where GENERAL-OPTIONS BACKUP-OPTIONS are options used for backing up X.

Now, executing cbx without arguments will create a backup.

Listing backups of X using list will be as easy as `cbx list', because list uses the backup options to figure out the "project directory". This applies to all commands that accesses the project directory and can derive it from the backup options. These include list, clean, find, lock and unlock.

--update | -u

Updates an existing backup with the current contents of the project.

Specify which backup to update using --last, --date or --tag.

Locked backups will not be updated unless --force is given.

The backup to update is specified using --last, --date or --tag.

The date and time is updated to the current date and time.

Locked backups can be forced to be updated using --force. Then, if a locked backup is updated, the resulting backup will also be locked (regardless of wether --lock is used or not).

The option --delete-excluded is passed to rsync if --no-delete is not used.

--update-or-create | -U

Like --update, but also creates a new backup if no existing is found.

Specify which backup to update using --last, --date or --tag.

--assign-tag=TAG | -g TAG

Marks the new or updated backup with this tag.

If a updated backup has a tag, it is replaced by this new tag.

--last | -l

Used together with --update. Updates the last backup.

--date=DATE | -d DATE

Used together with --update. Updates the backup for the given datetime.

DATE can be in either the format YYYYMMDD-hhmm[ss] or YYYY-MM-DD hh:mm[:ss].

--tag=TAG | -t TAG

Used together with --update. Updates the backup with the given tag TAG.

--tar | -T

Only available when the source is a directory.

Store the backup in a tar archive file.

`clean` - Removing old backups

Removes all but the latest, non-locked, backups for a project.

Synopsis of `clean`

copyback [GENERAL-OPTIONS] clean [CLEAN-OPTIONS] [ --explicit | -e ] DIRECTORY

copyback [GENERAL-AND-BACKUP-OPTIONS] clean [CLEAN-OPTIONS] SOURCE

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE clean [CLEAN-OPTIONS]

The project directory can be given either explicitly (the first syntax) or implicitly (the last two syntaxes). When giving it implicitly, the same source and naming options used for creating backups should be used. Other backup options are ignored.

Description of `clean`

The basename of each backup removed is printed to standard output (one per line).

The latest backup is never removed, regardless of whether it is locked or not.

Locked backups can be cleaned using --force. But even using --force, if the backup cannot be unlocked (see unlock), the backup will not be removed.

To clean the given project directory and also all subdirectories of it, use --recursive.

Options for `clean`

--force | -f

Also remove locked backups who's lock file is not write-protected and can be removed successfully.

--recursive | -r

Also clean all subdirectories of the given project directory that contain backups.

Directories that are copyback backups themselves are not cleaned.

`find` - Finding project directories

Look for directories that store copyback backups, under a given directory, and print the name of these.

Synopsis of `find`

Too look under the backup root directory:

copyback [GENERAL-OPTIONS] find

Too look under an explicit directory or a project directory:

copyback [GENERAL-OPTIONS] find [ --explicit | -e ] DIRECTORY

copyback [GENERAL-AND-BACKUP-OPTIONS] find SOURCE

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE find

When giving the directory implicitly, use the same source and naming options as for creating backups. Options other than those for setting the backup root directory and project naming scheme are ignored.

Description of `find`

copyback looks in all subdirectories of the given DIRECTORY, or the backup root directory if no argument is given, for directories that contain copyback backups. The names of these, relative DIRECTORY, are printed. If DIRECTORY stores backups itself, a dot ('.') is printed.

The output is not sorted to any particular order.

`list` - Listing backups of a project

List the exisisting backups for a project in creation time order.

Synopsis of `list`

copyback [GENERAL-OPTIONS] list [ --explicit | -e ] DIRECTORY

copyback [GENERAL-AND-BACKUP-OPTIONS] list SOURCE

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE list

Short alias: l

Short alias: lf: Adds --print-formatted.

Description of `list`

List the existing backups for a project in creation time order.

An asterisks ('*') is appended to the name of locked backups: One asterisk if the lock file is writable, two if it is not.

Each backup is presented with its filename, or in a formatted manner, depending on --print-filename and --print-formatted. --print-formatted is the default.

`lock` - Preventing backups from getting updated

Locks backups so that later copyback invocations can not update them (unless --force is used).

Synopsis of `lock`

Locking a single backup by giving the backup file name:

copyback [GENERAL-OPTIONS] lock BACKUP-FILE

Locking by giving the project directory, together with options that tell which backups to lock:

copyback [GENERAL-OPTIONS] lock {LOCK-OPTIONS} [ --explicit | -e ] DIRECTORY

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE lock {LOCK-OPTIONS}

copyback [GENERAL-AND-BACKUP-OPTIONS] lock {LOCK-OPTIONS} SOURCE

Description of `lock`

Locking backups prevents later invocations of copyback to operate on them (unless forced to, using --force). But even if --force is used, backups with a write-protected lock file will note be operated upon.

Whether the lock files created by copyback is write-protected or not depends on the current "umask" - "the file creation mask". This is usually set to give the user write-access to files. In this case lock files will not be write-protected. In most shells, you can type umask to see the current "umask".

The name of all backup files that are locked are printed, including names of backups that are already locked.

Nothing is printed to stdout if the project does not contain any backups.

A lock is represented as a file in the same directory as the backup file. The lock has the same filename as the backup file except for the extension. Lock files have the the extension ".lock".

The contents of a lock file is irrelevant. If there exists a directory with the same name as a lock file would have, the behaviour of copyback is undefined.

A lock can be removed using the unlock command.

Options for `lock`

--last | -l

Lock the last backup of a project.

The name of the last backup is printed, even if it was already locked.

--date=DATE | -d DATE

Lock the backup for the given date.

--tag=TAG | -t TAG

Lock the backup with the given tag.

--all

Lock all backups of a project.

The name of all backups are printed, even backups already locked.

`backup-root-directory` - Printing the backup root directory

Prints the backup root directory.

Synopsis of `backup-root-directory`

copyback [GENERAL-OPTIONS] backup-root-directory

Short alias: 'brd'.

Description of `print-backup-root-directory`

Prints the backup root directory that would be used if the same options and environment variables were used together with a different command.

`project-directory` - Printing the project directory

Print the project directory.

Synopsis of `project-directory`

The syntax is the same as for the command backup, except that any BACKUP-OPTIONS must precede the command name.

Short alias: 'pd'.

Description of `project-directory`

Prints the project directory that would be used if the same options and environment variables were used together with a different command.

`project-name` - Printing the project name

Prints the project name.

Synopsis of `project-name`

The syntax is the same as for the command backup, except that any BACKUP-OPTIONS must precede the command name.

Short alias: 'pn'.

Description of `project-name`

Prints the project name that would be used if the same options and environment variables were used together with a different command.

`tag` - Marking a backup with a tag string

Marks a backup with a unique string so that it can later be referred to by this string.

Synopsis of `tag`

copyback [GENERAL-OPTIONS] tag [ --explicit | -e ] [TAG-OPTIONS] STRING FILE

copyback [GENERAL-AND-BACKUP-OPTIONS] tag [TAG-OPTIONS] STRING SOURCE

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE tag [TAG-OPTIONS] STRING

Description of `tag`

The backup can later be referred to using --tag=STRING, for example, when updating a backup. The string is also shown by when listing backups with list.

The tag string must be unique among all backups for each project.

Options for `tag`

--last: Tags the last backup (of a project's backups).
--date=DATE: Tags the backup with the given date (of a project's backups).
--tag=STRING: Tags the backup with the given tag (of a project's backups).

`untag` - Removing a tag from a backup

Removes a tag from a backup.

Synopsis of `untag`

copyback [GENERAL-OPTIONS] untag [ --explicit | -e ] [TAG-OPTIONS] FILE

copyback [GENERAL-AND-BACKUP-OPTIONS] untag [TAG-OPTIONS] SOURCE

copyback [GENERAL-AND-BACKUP-OPTIONS] --source=SOURCE untag [TAG-OPTIONS]

The options are the same as Options for tag.

`unlock` - Unlocking backups

Unlocks a backup so that later copyback invocations can operate on it. A backup will not be unlocked if its lock file is write-protected. A write-protected lock file must be removed manually.

The unlock command is the reverse of to the lock command. It is used in the same way, so see "lock - Preventing existing backups from updating" for details.

General options

These general options are applicable to all commands.

Options for setting the backup root directory

If --root or --root-global is not used, the environment variables COPYBACK_ROOT and COPYBACK_ROOT_GLOBAL are used, if they exist.

--root=DIRECTORY

Sets the "backup root directory" to DIRECTORY.

Overrides the environment variables COPYBACK_ROOT and COPYBACK_ROOT_GLOBAL.

--root-global=DIRECTORY

Sets the "global backup root directory" to DIRECTORY.

If --root-global-suffix is not given, the "backup root directory" is set to DIRECTORY/users/USER. USER is the name of the current (effective) operating system user.

If --root-global-suffix=SUFFIX is given, the backup root directory is set to DIRECTORY/SUFFIX.

Overrides the environment variables COPYBACK_ROOT and COPYBACK_ROOT_GLOBAL.

--root-global-suffix=SUFFIX

Only valid together with --root-global or the environment variable COPYBACK_ROOT_GLOBAL.

Replaces the default string appended to the "global backup root directory" to SUFFIX. See the option --global-root for more information.

Other general options

--print-filename | --prfn

Present backups by printing their filename.

--print-filename-extra | --prfne

Present backups by printing their filename followed by asterisks indicating lock status.

This is the default.

One asterisk indicates a locked backup. Two asterisks indicates that the lock file is write protected. (This means that copyback won't modify or remove the backup, not even using --force).

--print-formatted | --prft

Present backups by printing formatted information.

One asterisk indicates a locked backup. Two asterisks indicates that the lock file is write protected. (This means that copyback won't modify or remove the backup, not even using --force).

--version | -V

Print program version and exit successfully.

--help

Print help and exit successfully.

--debug

Run the program in a special mode suitable for testing and debugging.

Warning

This options modifies the command line syntax and the behaviour of the commands.

Don't use it unless you are programming the copyback program!

Exit status

0

Success.

1

Syntax or usage error.

Can be a syntax error reported by rsync. Then it is one of the options forwarded to rsync that causes the error (Options forwarded to rsync).

2

Error creating the backup. No backup has been created.

There are several reasons for this failure. The most common is probably that SOURCE is not an existing file/directory. Another reason is If SOURCE should be a program (--program) and running it results in a non-zero exit status.

100

Feature not implemented.

101

Internal error.

Files

.rsync-filter

If the backup option -F or --rsync-filter is given, rsync will look for a file with this name in each directory and read include/exclude filters from it if it is found.

Requires a version of rsync that supports the option -F.

.copyback-exclude

If the source is a directory and this directory contains a file by this name, then rsync exclude patterns are read from it.

This is equivalent to using --exclude-from=SOURCE/.copyback-exclude (where SOURCE is the source directory).

See the rsync manual for information about include and exclude patterns.

Environment

copyback can use either of two environment variables for setting the backup root directory.

COPYBACK_ROOT

If none of the options --root or --root-global are used and COPYBACK_ROOT is set, the effect is the same as using --root with the value of COPYBACK_ROOT.

COPYBACK_ROOT overrides COPYBACK_ROOT_GLOBAL.

COPYBACK_ROOT_GLOBAL

If none of the options --root or --root-global are used and COPYBACK_ROOT is not set, and COPYBACK_ROOT_GLOBAL is set, the effect is the same as using --root-global with the value of COPYBACK_ROOT_GLOBAL.

Author

Written by Emil Karlén.

Bugs

The behaviour is undefined for backups of files who's filename contains non-printable characters or newlines.

Reporting bugs

Report bugs to <emilkarlen@aim.com>.

Copyright

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

Glossary

Definition and explanation of terms

global backup root directory

Set by the environment variable COPYBACK_ROOT_GLOBAL or the command line option --root-global. The command line option overrides the environment variable.