NAME

File::Backup - Easy file backup & rotation automation

SYNOPSIS

  use File::Backup;

  backup( from => "/source/path", to => "/destination/path" );
  backup( from => "/kansas/*", to => "/oz" );

  purge_backups(
      to => "/destination/path",
      compress => 0,
      keep => 5,
      timeformat => "YYYYMMDD_hhmmss",
  );

DESCRIPTION

This legacy module implements archival and compression (A.K.A "backup") and file rotation and is an implementation of tar and gzip calls.

EXPORTED FUNCTIONS

backup %ARGUMENTS

  $backed = backup(%arguments);

In its barest form, this function takes as input a source path or glob and a destination directory, and puts an archive file of the source directory files into the destination directory.

The backup() function returns a single valued source => destination hash reference (AKA an array).

The function arguments are described below.

• debug => 0 | 1

  Turn on verbose processing. Default is off.

• from => $PATH

  The source directory or glob reference of files to backup. If not given, the current directory is used.

• to => $PATH

  The optional destination directory where the archive is placed. If not given, the current directory is used.

• keep => $NUMBER

  The maximum number of backups to keep in the directory.

  By setting this to some non-negative number n, the n most recent backups will be kept. Set this to a negative number to keep all backups. The default is the magical number 7 (a weeks worth). If keep is set to zero, no backup files will be kept.

• timeformat => $STRING

  The date-time format string to use in stamping backup files.

  This parameter can take either nothing for no timestamp, the word 'epoch' to use time as the stamp, or a string containing a combination of the following in order:

    Y => year
    M => month
    D => day
    h => hour
    m => minute
    s => second

  How about some examples:

  The default 'YYYY-MM-DD_hh-mm-ss' in printf format is '%4d-%02d-%02d_%02d-%02d-%02d'. For Janurary 2, 2003 at 3:04 and 5 seconds AM, that would be '2003-01-02_03-04-05'.

  You can leave off ending format characters. 'YYYYMMDD' would produce '20030102'. This module always uses a four digit numeral for the year, so 'Y-MMDD' would actually produce '2003-0102'.

  The "reverse date" scheme is used to unambiguously sort the backup files chronologically. You can of course produce a stamp with 'YMDhms' which would make '200312345'. Is that December 3rd or January 23rd? Who knows? Don't do that.

• archive => 0 | 1

  Flag to toggle file archiving. Default is on.

• archiver => $PATH_TO_PROGRAM

  The achiving program. The default is the local tar program.

• archive_flags => $COMMAND_SWITCHES

  The optional archive switches. Default is set to the tar program's -cf. That is, "create" and "filename". See tar of course.

• archive_prefix => $STRING

  An optional archive_prefix string to be used as the beginning of the archive filename (before the timestamp string). This is handy for identifying your backup files and defaults to nothing (i.e. '').

• archive_suffix => $STRING

  The optional, but important archive extension. This defaults to the string tar.

• compressor => $PATH_TO_PROGRAM

  The compression program. Default is the local gzip program.

• compress_flags => $COMMAND_SWITCHES

  The optional compression switches. Default is nothing.

• compress => 0 | 1

  Flag to toggle archive compression. Default is on. We like compression.

  * Currently, this only makes sense if the archive flag is turned on.

• compress_suffix => $STRING

  The optional, but important archive extension. This defaults to the string gz.

• lock => 0 | 1

  Flag to toggle file locking. Default is on.

• purge_first => 0 | 1

  Flag to toggle when file purging happens. The default is off, which means that old backup files are "rotated" after the backup process happens.

purge_backups %ARGUMENTS

This function is handy for cleaning out backup directories. It does no archival but the arguments are the same as with the backup function.

LEGACY

The following parameters are still around, but are now aliased to the corresponding names:

  tar           => archiver
  tarflags      => archive_flags
  torootname    => archive_prefix and prefix
  tarsuffix     => archive_suffix and suffix
  compress      => compressor
  compressflags => compress_flags

BUGS

You can't make two backups of the same stuff in one second, because they'll try to have the same name. Is this really a bug?

TO DO

Make the stuttering YYYYMMDDhhmmss stop. Just use YMDhms or make the string processing intelligent instead. There's an idea...

Restrict processing to a provided list of filenames and look for them with File::Find.

Support file name include and exclude regexps.

Make a friendly commandline function using a Getopt::* module.

Use Archive::Any/File/Tar/Zip/Whatever instead of Unix system calls.

Use standard ISO formats for the time2str function.

Allow various backup file naming conventions (also with a string format).

Make the keep option time sensitive as well as "numerically naive". Consider the ctime and mtime file attributes.

Make the keep option size sensitive. Duuuh.

Allow the source files to be backed up without the file system directory tree structure. That is, "flatten" the archive.

Make sure unique filenames are being used in the backup.

Make a File::Backup::Base superclass for implementing focused back-up tasks with cvs or scp, nfs or to a legacy device, for instance.

SEE ALSO

Cwd

File::Which

LockFile::Simple

Related modules:

File::Rotate::Backup is a later, apparantly orphaned module that appears to be mostly redundant.

Dir::Split seems handy.

THANK YOU

Help, insight, suggestions and comments came from Ken Williams, Joshua Keroes and John McDermott.

AUTHORS

Original: Ken Williams <kwilliams@cpan.org>

Current: Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

Copyright 1998-2004 Ken Williams and Gene Boggs. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CVS

$Id: Backup.pm,v 1.28 2004/03/23 12:17:06 gene Exp $