Sergey Poznyakoff


File::BackupCopy - create a backup copy of the file.


    use File::BackupCopy;

    $backup_name = backup_copy($file_name);

    $backup_name = backup_copy($file_name, BACKUP_NUMBERED);

    $backup_name = backup_copy($file_name, type => BACKUP_NUMBERED,
                          dir => $directory, error => \my $error);
    if (!$backup_name) {
        warn $error;


The File::BackupCopy module provides functions for creating backup copies of files. Normally, the name of the backup copy is created by appending a single ~ character to the original file name. This naming is called simple backup. Another naming scheme is numbered backup. In this scheme, the name of the backup is created by suffixing the original file name with .~N~, where N is a decimal number starting with 1. In this naming scheme, the backup copies of file test would be called test.~1~, test.~2~ and so on.


    $backup_name = backup_copy($orig_name);
    $backup_name = backup_copy($orig_name, $scheme);

    $backup_name = backup_copy($orig_name, %opts);

The backup_copy function is the principal interface for managing backup copies. Its first argument specifies the name of the existing file for which a backup copy is required. Optional second argument controls the backup naming scheme. Its possible values are:


Don't create backup.


Create simple backup (FILE~).


Create numbered backup (FILE.~N~).


Automatic selection of the naming scheme. Create numbered backup if the file has numbered backups already. Otherwise, make simple backup.

If the second argument is omitted, the function will consult the value of the environment variable VERSION_CONTROL. Its possible values are:

none, off

Don't create any backups (BACKUP_NONE).

simple, never

Create simple backups (BACKUP_SIMPLE).

numbered, t

Create numbered backups (BACKUP_NUMBERED).

existing, nil

Automatic selection of the naming scheme (BACKUP_AUTO).

If VERSION_CONTROL is unset or set to any other value than those listed above, BACKUP_AUTO is assumed.

The function returns the name of the backup file it created (undef if called with BACKUP_NONE). On error, it calls croak().

When used in the third form, the %opts are keyword arguments that control the function behavior. The following arguments are understood:

type => $scheme

Request a particular backup naming scheme. The following two calls are equivalent:

    backup_copy($file, type => BACKUP_SIMPLE)
    backup_copy($file, BACKUP_SIMPLE)
dir => $directory

Create backup files in $directory. The directory must exist and be writable.

By default backup files are created in the same directory as the original file.

error => $ref

This changes default error handling. Instead of croaking on error, the error message will be stored in $ref (which should be a reference to a scalar) and undef will be returned.

This can be used for an elaborate error handling and recovery, e.g.:

    $bname = backup_copy($file, \my $err);
    unless ($bname && defined($err)) {
        error("can't backup_copy file $file: $err");
        # perhaps more code follows

The following functions are available for using a specific backup naming scheme. These functions must be exported explicitly.


    use File::BackupCopy qw(backup_copy_simple);
    $backup_name = backup_copy_simple($orig_name, %opts);

Creates simple backup. Optional %opts have the same meaning as in backup_copy, except that, obviously, type keyword is not accepted.


    use File::BackupCopy qw(backup_copy_numbered);
    $backup_name = backup_copy_numbered($orig_name, %opts);

Creates numbered backup. See above for a description of %opts.


    use File::BackupCopy qw(backup_copy_auto);
    $backup_name = backup_copy_auto($orig_name, %opts);

Creates numbered backup if any numbered backup version already exists for the file. Otherwise, creates simple backup.

Optional %opts have the same meaning as in backup_copy, except that, obviously, type keyword is not accepted.


GPLv3+: GNU GPL version 3 or later, see

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


Sergey Poznyakoff <>