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( ) 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 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( , ) Copy everything from to . Files and directories within that do not exist in will be removed. New nodes put within since the last dirsycn() will be mirrored to retaining permission modes and timestamps. Write access to is required. Read-only access to is sufficient. $dirsync->dirsync( $from, $to ); The rebuild() method should have been run on prior to using dirsync() for maximum efficiency. If not, then use the nocache() setting to force dirsync() to mirror the entire regardless of the dirsync source cache. only( ) If you are sure nothing has changed within source_directory except for , 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( ) Avoid recursing into directories named 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( ) If this option is used, 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 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