NAME
    File::DirSync - Syncronize two directories rapidly

    $Id: DirSync.pm,v 1.11 2001/12/11 16:42:38 rob Exp $

SYNOPSIS
      use File::DirSync;

      my $dirsync = new File::DirSync {
        verbose => 1,
        nocache => 1,
        localmode => 1,
      };

      $dirsync->ignore("CVS");

      $dirsync->rebuild( $from );

      #  and / or

      $dirsync->dirsync( $from, $to );

DESCRIPTION
    File::DirSync will make two directories exactly the same. The goal is to
    perform this syncronization process as quickly as possible with as few
    stats and reads and writes as possible. It usually can perform the
    syncronization process within a few milliseconds - even for gigabytes or
    more of information.

    Much like File::Copy::copy, one is designated as the source and the
    other as the destination, but this works for directories too. It will
    ensure the entire file structure within the descent of the destination
    matches that of the source. It will copy files, update time stamps,
    adjust symlinks, and remove files and directories as required to force
    consistency.

    The algorithm used to keep the directory structures consistent is a
    dirsync cache stored within the source structure. This cache is stored
    within the timestamp information of the directory nodes. No additional
    checksum files or separate status configurations are required nor
    created. So it will not affect any files or symlinks within the
    source_directory nor its descent.

METHODS
  new( [ { properties... } ] )

    Instantiate a new object to prepare for the rebuild and/or dirsync
    mirroring process.

      $dirsync = new File::DirSync;

    Key/value pairs in a property hash may optionally be specified as well
    if desired as demonstrated in the SYNOPSIS above. The default property
    hash is as follows:

      $dirsync = new File::DirSync {
        verbose => 0,
        nocache => 0,
        localmode => 0,
      };

  rebuild( <source_directory> )

    In order to run most efficiently, a source cache should be built prior
    to the dirsync process. That is what this method does. Write access to
    <source_directory> is required.

      $dirsync->rebuild( $from );

    This may take from a few seconds to a few minutes depending on the
    number of nodes within its directory descent. For best performance, it
    is recommended to execute this rebuild on the computer actually storing
    the files on its local drive. If it must be across NFS or other remote
    protocol, try to avoid rebuilding on a machine with much latency from
    the machine with the actual files, or it may take an unusually long
    time.

  dirsync( <source_directory>, <destination_directory> )

    Copy everything from <source_directory> to <destination_directory>.
    Files and directories within <destination_directory> that do not exist
    in <source_directory> will be removed. New nodes put within
    <source_directory> since the last dirsycn() will be mirrored to
    <destination_directory> retaining permission modes and timestamps. Write
    access to <destination_directory> is required. Read-only access to
    <source_directory> is sufficient.

      $dirsync->dirsync( $from, $to );

    The rebuild() method should have been run on <source_directory> prior to
    using dirsync() for maximum efficiency. If not, then use the nocache()
    setting to force dirsync() to mirror the entire <source_directory>
    regardless of the dirsync source cache.

  only( <source> )

    If you are sure nothing has changed within source_directory except for
    <source>, you can specify a file or directory using this method.

      $dirsync->only( "$from/htdocs" );

    However, the cache will still be built all the way up to the
    source_directory. This only node must always be a subdirectory or a file
    within source_dir. This option only applies to the rebuild() method and
    is ignored for the dirsync() method. This method may be used multiple
    times to rebuild several nodes. If this method is not called before
    rebuild() is, then the entire directory structure of source_directory
    and its descent will be rebuilt.

  ignore( <node> )

    Avoid recursing into directories named <node> within source_directory.
    It may be called multiple times to ignore several directory names.

      $dirsync->ignore("CVS");

    This method applies to both the rebuild() process and the dirsync()
    process.

  lockfile( <lockfile> )

    If this option is used, <lockfile> will be used to ensure that only one
    dirsync process is running at a time. If another process is concurrently
    running, this process will immediately abort without doing anything. If
    <lockfile> does not exist, it will be created. This might be useful say
    for a cron that runs dirsync every minute, but just in case it takes
    longer than a minute to finish the dirsync process. It would be a waste
    of resources to have multiple simultaneous dirsync processes all
    attempting to dirsync the same files. The default is to always dirsync.

  verbose( [ <0_or_1> ] )

      $dirsync->verbose( 1 );

    Read verbose setting or turn verbose off or on. Default is off.

  localmode( [ <0_or_1> ] )

    Read or set local directory only mode to avoid recursing into the
    directory descent.

      $dirsync->localmode( 1 );

    Default is to perform the action recursively by descending into all
    subdirectories of source_directory.

  nocache( [ <0_or_1> ] )

    When mirroring from source_directory to destination_directory, do not
    assume the rebuild() method has been run on the source already to
    rebuild the dirsync cache. All files will be mirrored.

      $dirsync->nocache( 1 );

    If enabled, it will significantly degrade the performance of the
    mirroring process. The default is 0 - assume that rebuild() has already
    rebuilt the source cache.

TODO
    Generalized file manipulation routines to allow for easier integration
    with third-party file management systems.

    Support for FTP dirsync (both source and destination).

    Support for Samba style sharing dirsync.

    Support for VFS, HTTP/DAV, and other more standard remote third-party
    file management.

BUGS
    If the source or destination directory permission settings do not
    provide write access, there may be problems trying to update nodes
    within that directory.

    If a source file is modified after, but within the same second, that it
    is dirsynced to the destination and is exactly the same size, the new
    version may not be updated to the destination. The source will need to
    be modified again or at least the timestamp changed after the entire
    second has passed by. A quick touch should do the trick.

    It does not update timestamps on symlinks, because I could not figure
    out how to do it without dinking with the system clock. :-/ If anyone
    knows a better way, just let the author know.

    Only plain files, directories, and symlinks are supported at this time.
    Special files, (including mknod), pipe files, and socket files will be
    ignored.

AUTHOR
    Rob Brown, rob@roobik.com

COPYRIGHT
    Copyright (C) 2001, Rob Brown, rob@roobik.com

    All rights reserved.

    This may be copied, modified, and distributed under the same terms as
    Perl itself.

SEE ALSO
    the File::Copy manpage, the perl manpage