debian man page for file::dircompare

DirCompare(3pm) 					User Contributed Perl Documentation					   DirCompare(3pm)

NAME
       File::DirCompare - Perl module to compare two directories using callbacks.

SYNOPSIS
	 use File::DirCompare;

	 # Simple diff -r --brief replacement
	 use File::Basename;
	 File::DirCompare->compare($dir1, $dir2, sub {
	   my ($a, $b) = @_;
	   if (! $b) {
	     printf "Only in %s: %s
", dirname($a), basename($a);
	   } elsif (! $a) {
	     printf "Only in %s: %s
", dirname($b), basename($b);
	   } else {
	     print "Files $a and $b differ
";
	   }
	 });

	 # Version-control like Deleted/Added/Modified listing
	 my (@listing, @modified);     # use closure to collect results
	 File::DirCompare->compare('old_tree', 'new_tree', sub {
	   my ($a, $b) = @_;
	   if (! $b) {
	     push @listing, "D	 $a";
	   } elsif (! $a) {
	     push @listing, "A	 $b";
	   } else {
	     if (-f $a && -f $b) {
	       push @listing, "M   $b";
	       push @modified, $b;
	     } else {
	       # One file, one directory - treat as delete + add
	       push @listing, "D   $a";
	       push @listing, "A   $b";
	     }
	   }
	 });

DESCRIPTION
       File::DirCompare is a perl module to compare two directories using a callback, invoked for all files that are 'different' between the two
       directories, and for any files that exist only in one or other directory ('unique' files).

       File::DirCompare has a single public compare() method, with the following signature:

	 File::DirCompare->compare($dir1, $dir2, $sub, $opts);

       The first three arguments are required - $dir1 and $dir2 are paths to the two directories to be compared, and $sub is the subroutine
       reference called for all unique or different files. $opts is an optional hashref of options - see OPTIONS below.

       The provided subroutine is called for all unique files, and for every pair of 'different' files encountered, with the following signature:

	 $sub->($file1, $file2)

       where $file1 and $file2 are the paths to the two files. For 'unique' files i.e. where a file exists in only one directory, the subroutine
       is called with the other argument 'undef' i.e. for:

	 $sub->($file1, undef)
	 $sub->(undef, $file2)

       the first indicates $file1 exists only in the first directory given ($dir1), and the second indicates $file2 exists only in the second
       directory given ($dir2).

   OPTIONS
       The following optional arguments are supported, passed in using a hash reference after the three required arguments to compare() e.g.

	 File::DirCompare->compare($dir1, $dir2, $sub, {
	   cmp => $cmp_sub,
	   ignore_unique => 1,
	 });

       cmp By default, two files are regarded as different if their contents do not match (tested with File::Compare::compare). That default
	   behaviour can be overridden by providing a 'cmp' subroutine to do the file comparison, returning zero if the two files are equal, and
	   non-zero if not.

	   E.g. to compare using modification times instead of file contents:

	     File::DirCompare->compare($dir1, $dir2, $sub, {
	       cmp => sub { -M $_[0] <=> -M $_[1] },
	     });

       ignore_cmp
	   If you want to see all corresponding files, not just 'different' ones, set the 'ignore_cmp' flag to tell File::DirCompare to skip its
	   file comparison checks i.e.

	     File::DirCompare->compare($dir1, $dir2, $sub,
	       { ignore_cmp => 1 });

       ignore_unique
	   If you want to ignore files that only exist in one of the two directories, set the 'ignore_unique' flag i.e.

	     File::DirCompare->compare($dir1, $dir2, $sub,
	       { ignore_unique => 1 });

SEE ALSO
       File::Dircmp, which provides similar functionality (and whose directory walking code I've adapted for this module), but a simpler
       reporting-only interface, something like the first example in the SYNOPSIS above.

AUTHOR AND CREDITS
       Gavin Carr <gavin@openfusion.com.au>

       Thanks to Robin Barker for a bug report and fix for glob problems with whitespace.

COPYRIGHT AND LICENSE
       Copyright 2006-2007 by Gavin Carr.

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

perl v5.10.1							    2010-03-02							   DirCompare(3pm)