/ 
File-Backup-0.04
River stage zero No dependents
/ File::Backup

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.

* 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.

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 or the files that were backed-up individually as the keys and the new, timestamped path names as their values, respectively.

The function arguments are described below.

  • 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 September 11, 2003 at 8:23 and 47 seconds AM, that would be '2003-09-11_08-23-47'.

    'YYMMDDhhmmss' would be '%02d%02d%02d%02d%02d%02d' producing '030911082347'.

    You can leave off format ending format characters to. So 'YYMMDD' would be '%02d%02d%02d' producing '20030911'.

    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 producing an ambiguous stamp with 'YMD-hms', which would be '%01d%01d%01d-%01d%01d%01d' producing '2003911-82347'.

  • archive => 0 | 1

    Flag to archive (with tar/gz/zip) the backed-up files. Default 1.

  • archiver => $PATH_TO_PROGRAM

    The achiving program. Default '/usr/bin/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 '/usr/bin/gzip'.

  • compress_flags => $COMMAND_SWITCHES

    The optional compression switches.

  • compress => 0 | 1

    Flag to turn archive compression off or 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.

EXAMPLES

# On the commandline:
back -s -x "^\." -i ".*"

That is, show the number and names of files to be backed, include all "dot files", but exclude files of one character.

BUGS

You can't make two backups of the same stuff in one second, because they'll try to have the same name.

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).

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

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.