NAME

File::Backup - Easy file backup & rotation automation

SYNOPSIS

  use File::Backup;

  backup(
      from => '/source/path/to/backup/from',
      to   => '/destination/path/to/backup/to',
      keep => 5,
      timeformat => 'YYMMDD_hhmmss',
  );

DESCRIPTION

This module implements archival and compression (A.K.A "backup") schemes with automatic source file locking.

* Currently, this is only tar and gzip with Unix path strings. Maybe your computer is okay with that... Cross platform file backing is going to be implemented soon.

A really nice feature of this new version is the use of File::Which to find your local version of tar and gzip. Additionally, automatic file locking ala LockFile::Simple is implemented now.

One very cool thing is that you can now supply the backup function with an arbitrary timestamp format string.

Also, you can specify whether to apply compression to your tar.

All these options are detailed in the arguments section of the backup function documentation, below.

EXPORTED FUNCTIONS

backup %ARGUMENTS

  $backed_files = backup(%arguments);

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

Return a hash reference with the path of the source as key and the name of the archive file as the value.

* When the list of files to back is implemented (see TO DO), these files will be the keys and the new, timestamped path names of the backed as their values.

The function arguments are described below.

• debug => 0 | 1

  Turn on verbose processing. Defaults to zero (off).

• from => $PATH

  The source directory 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 set to the magical number 7 (a weeks worth of backups).

• 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:

  'YYYY-MM-DD_hh-mm-ss' is seen by sprintf as '%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 be '%04d%02d%02d' producing '20030102'.

  Note that this module always uses a four digit numeral for the year, so 'Y-MMDD' will produce '2003-0102'.

  This "reverse date" scheme is used to unambiguously sort the backup files chronologially. That is, the stamp must be in order of largest timescale maginitude. Of course, you can produce an ambiguous stamp with 'YMDhms' which would produce '200312345'. Is this December 3rd, 2003? Who knows?

• archive => 0 | 1

  Flag to archive the backed-up files. Default 1.

  * This is not useful yet, but in a future version files will be able to be stamped and copied to a backup directory without any bundled archiving.

• archiver => $PATH_TO_PROGRAM

  The achiving program. Default is your local tar.

• archive_flags => $COMMAND_SWITCHES

  The optional archive switches. Default '-cf'.

• prefix => $STRING

  An optional prefix string to be used as the beginning of the archive filename (before the timestamp string).

  This is useful if backups of several different things are being kept in the same directory.

• suffix => $STRING

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

• compressor => $PATH_TO_PROGRAM

  The compression program. Default is your local gzip.

• compress_flags => $COMMAND_SWITCHES

  The optional compression switches. Default is off (i.e. set to nothing).

• compress => 0 | 1

  Flag to turn archive compression off or on.

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

• files => \@FILENAMES

  The optional list of files to backup.

  XXX Not yet implemented

• include => $REGEXP

  An optional regular expression of filenames to match for inclusion.

  XXX Not yet implemented

• exclude => $REGEXP

  An optional regular expression of filenames to match for exclusion.

  XXX Not yet implemented

• flatten => 0 | 1

  Flag to preserve the source directory tree structure or not. Default set to 0.

  XXX Not yet implemented

• unique_names => 0 | 1

  Flag to force source files to have unique names in the archive. Default 0.

  XXX Not yet implemented

The following legacy parameters are still around, but are now aliases to the corresponding parameters:

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

PRIVATE FUNCTIONS

_time2str [%ARGUMENTS]

  $timestamp = _time2str(
      format     => $YMDhms_format,
      use_gmtime => $boolean,
  );

Return a date-time string to use in a file name.

See the documentation for the timeformat parameter for a description of what a YMDhms format string is.

The system localtime is used unless the use_gmtime flag is set in the backup function call.

If a format string is not provided, an empty string will be returned for the stamp. If it is set to the string, 'epoch', then the perl time function will be used for the returned stamp. Otherwise, the YMDhms format string is used.

_format_to_regexp $FORMAT

  $re = _format_to_regexp($YMDhms_format);

Convert a 'YMDhms format string' into a simple regular expression.

This function simply replaces the format characters with a \d (digit metacharacter).

_format_to_printf $FORMAT

  $printf_format = _format_to_printf($YMDhms_format);

This function replaces the YMDhms format characters with a %0nd printf format string, where n is the number of identical, contiguous YMDhms format characters.

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

Test every edge case parameter permutation!

Restrict processing to a provided list of filenames and wildcards.

Support file include and exclude regexps.

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

Use File::Spec or Class::Path to build OS aware backup strings.

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

Use other archivers and compressiors not covered by perl modules.

Do the same for compression, of course (e.g. Compress::Zlib, etc).

Backup to database with record locking.

Descend into directories with File::Find.

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.

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

Allow the user to 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.)

Okay. Support scp with Net::SCP. Should this be File::Backup::SCP or File::Backup qw(scp). Hmmm.

Make the code magically look for system archival programs, if asked nicely.

SEE ALSO

Cwd

File::Which

LockFile::Simple

THANK YOU

Help, insight, suggestions and comments came from Ken Williams (A.K.A. DrMath) and Joshua Keroes (A.K.A. ua).

AUTHORS

Original: Ken Williams, <kwilliams@cpan.org>

Current: Gene Boggs, <gene@cpan.org>

COPYRIGHT

Copyright 1998-2003 Ken Williams. All rights reserved.

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

cpanm File::Backup

perl -MCPAN -e shell
install File::Backup