/ 
Directory-Diff-0.05
River stage zero No dependents
/ Directory::Diff

NAME

Directory::Diff - recursively find differences between similar directories

SYNOPSIS

use Directory::Diff 'directory_diff';

# Do a "diff" between "old_dir" and "new_dir"

directory_diff ('old_dir', 'new_dir', 
            {diff => \& diff,
             dir1_only => \& old_only});

# User-supplied callback for differing files

sub diff
{
    my ($data, $dir1, $dir2, $file) = @_;
    print "$dir1/$file is different from $dir2/$file.\n";
}

# User-supplied callback for files only in one of the directories

sub old_only
{
    my ($data, $dir1, $file) = @_;
    print "$file is only in the old directory.\n";
}

VERSION

This document describes Directory::Diff version 0.05, corresponding to git commit 415adc953083b811ba31d2fffa0f047a3f5c2e60 at Tue Aug 23 09:16:18 2016 +0900.

DESCRIPTION

Directory::Diff finds differences between two directories and all their subdirectories, recursively. If it finds a file with the same name in both directories, it uses File::Compare to find out whether they are different. It is callback-based and takes actions only if required.

FUNCTIONS

The main function of this module is "directory_diff". The other functions are helper functions, but these can be exported on request.

ls_dir

my %ls = ls_dir ("dir");

ls_dir makes a hash containing a true value for each file and directory which is found under the directory given as the first argument.

It also has an option to print messages on what it finds, by setting a second argument to a true value, for example

my %ls = ls_dir ("dir", 1);

get_only

my %only = get_only (\%dir1, \%dir2);

Given two hashes containing true values for each file or directory under two directories, return a hash containing true values for the files and directories which are in the first directory hash but not in the second directory hash.

For example, if

%dir1 = ("file" => 1, "dir/" => 1, "dir/file" => 1);

and

%dir2 = ("dir/" => 1, "dir2/" => 1);

get_only returns

%only = ("file" => 1, "dir/file" => 1);

There is also a third option which prints messages on what is found if set to a true value, for example,

my %only = get_only (\%dir1, \%dir2, 1);

get_diff

my %diff = get_diff ("dir1", \%dir1_ls, "dir2", \%dir2_ls);

Get a list of files which are in both dir1 and dir2, but which are different. This uses File::Compare to test the files for differences. It searches subdirectories. Usually the hashes %dir1_ls and %dir2_ls are those output by "ls_dir".

directory_diff

directory_diff ("dir1", "dir2", 
                {dir1_only => \&dir1_only,
                 diff => \& diff});

Given two directories dir1 and dir2, this calls back a user-supplied routine for each of three cases:

A file is only in the first directory

In this case a callback specified by dir1_only is called once

&{$third_arg->{dir1_only}} ($third_arg->{data}, "dir1", $file);

for each file $file which is in dir1 but not in dir2, including files in subdirectories.

A file is only in the second directory

In this case a callback specified by dir2_only is called once

&{$third_arg->{dir2_only}} ($third_arg->{data}, "dir2", $file);

for each file $file which is in dir2 but not in dir1, including files in subdirectories.

A file with the same name but different contents is in both directories

In this case a callback specified by diff is called once

&{$third_arg->{diff}} ($third_arg->{data}, "dir1", "dir2", $file);

for each file name $file which is in both dir1 and in dir2, including files in subdirectories.

The first argument to each of the callback functions is specified by data. The second argument to dir1_only and dir2_only is the directory's name. The third argument is the file name, which includes the subdirectory part. The second and third arguments to diff are the two directories, and the fourth argument is the file name including the subdirectory part.

If the user does not supply a callback, no action is taken, even if a file is found.

The routine does not return a meaningful value. It does not check the return values of the callbacks. Therefore if it is necessary to stop midway, the user must use something like eval { } and die.

A fourth argument, if set to any true value, causes directory_diff to print messages about what it finds and what it does.

default_dir_only

use Directory::Diff qw/directory_diff default_dir_only/;
directory_diff ('old', 'new', {dir1_only => \&default_dir_only});

A simple routine to print out when a file is only in one of the directories. This is for testing the Directory::Diff module.

default_diff

use Directory::Diff qw/directory_diff default_diff/;
directory_diff ('old', 'new', {dir1_only => \&default_diff});

A simple routine to print out when a file is different between the directories. This is for testing the Directory::Diff module.

SEE ALSO

CPAN modules

File::DirCompare

This seemingly does a very similar thing to Directory::Diff.

File::Dircmp

DEPENDENCIES

This section lists Perl modules which this depends on, with a rationale for why they are used.

File::Compare

File::Compare is used to check whether two files are different or not.

CONTRIBUTORS

This section lists people who have contributed to the module.

Mohammad S. Anwar (MANWAR) contributed fixes for broken tests.

MOTIVATION

This section discusses why I wrote the module and what I use it for.

The reason I wrote this module is because `diff --recursive` stops when it finds a subdirectory which is in one directory and not the other, without descending into the subdirectory. For example, if one has a file like dir1/subdir/file,

diff -r dir1 dir2

will tell you "Only in dir1: subdir" but it won't tell you anything about the files under "subdir".

I needed to go down into the subdirectory and find all the files which were in all the subdirectories, so I wrote this.

I've been using this module for updating web sites with a lot of pages since 2009, to avoid repeatedly having to upload the entire site's-worth of pages for each small change. The way I use this is as follows. I keep a local copy of the uploaded web site in a directory like old-site, and then rebuild all the pages in another directory like new-site, then I use Directory::Diff::Copy to put the changed files into yet another directory, like changed-site-files. Once the changed files are copied, then I tar, gzip, and upload the directory of changed files, and untar it at the web host, replacing only files which have changed. I also delete the old-site directory and rename new-site to old-site at this point in preparation for the next upload.

I'm currently using this for almost all the static content for the following web sites: http://www.sljfaq.org, http://kanji.sljfaq.org, and http://www.lemoda.net. I put this module on github in about 2012 and on CPAN in 2016.

AUTHOR

Ben Bullock, <bkb@cpan.org>

Request

If you'd like to see this module continued, let me know that you're using it. For example, send an email, write a bug report, star the project's github repository, add a patch, add a ++ on Metacpan.org, or write a rating at CPAN ratings. It really does make a difference. Thanks.

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2009-2016 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.