.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DirCompare 3pm"
.TH DirCompare 3pm "2018-03-31" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::DirCompare \- Perl module to compare two directories using
callbacks.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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\en", dirname($a), basename($a);
\&    } elsif (! $a) {
\&      printf "Only in %s: %s\en", dirname($b), basename($b);
\&    } else {
\&      print "Files $a and $b differ\en";
\&    }
\&  });
\&
\&  # Version\-control like Deleted/Added/Modified listing
\&  my (@listing, @modified);     # use closure to collect results
\&  File::DirCompare\->compare(\*(Aqold_tree\*(Aq, \*(Aqnew_tree\*(Aq, 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";
\&      }
\&    }
\&  });
.Ve
.SH "DESCRIPTION"
.IX Header "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).
.PP
File::DirCompare has a single public \fIcompare()\fR method, with the
following signature:
.PP
.Vb 1
\&  File::DirCompare\->compare($dir1, $dir2, $sub, $opts);
.Ve
.PP
The first three arguments are required \- \f(CW$dir1\fR and \f(CW$dir2\fR are paths
to the two directories to be compared, and \f(CW$sub\fR is the subroutine
reference called for all unique or different files. \f(CW$opts\fR is an 
optional hashref of options \- see \s-1OPTIONS\s0 below.
.PP
The provided subroutine is called for all unique files, and for 
every pair of 'different' files encountered, with the following 
signature:
.PP
.Vb 1
\&  $sub\->($file1, $file2)
.Ve
.PP
where \f(CW$file1\fR and \f(CW$file2\fR 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:
.PP
.Vb 2
\&  $sub\->($file1, undef)
\&  $sub\->(undef, $file2)
.Ve
.PP
the first indicates \f(CW$file1\fR exists only in the first directory given
($dir1), and the second indicates \f(CW$file2\fR exists only in the second 
directory given ($dir2).
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
The following optional arguments are supported, passed in using a 
hash reference after the three required arguments to \fIcompare()\fR e.g.
.PP
.Vb 6
\&  File::DirCompare\->compare($dir1, $dir2, $sub, {
\&    cmp             => $cmp_sub,
\&    ignore_cmp      => 1,
\&    ignore_unique   => 1,
\&    matches         => $matches_sub,
\&  });
.Ve
.IP "cmp" 4
.IX Item "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.
.Sp
E.g. to compare using modification times instead of file contents:
.Sp
.Vb 3
\&  File::DirCompare\->compare($dir1, $dir2, $sub, { 
\&    cmp => sub { \-M $_[0] <=> \-M $_[1] },
\&  });
.Ve
.IP "ignore_cmp" 4
.IX Item "ignore_cmp"
If you want to see \fIall\fR corresponding files, not just 'different'
ones, set the 'ignore_cmp' flag to tell File::DirCompare to skip its 
file comparison checks i.e.
.Sp
.Vb 2
\&  File::DirCompare\->compare($dir1, $dir2, $sub, 
\&    { ignore_cmp => 1 });
.Ve
.IP "ignore_unique" 4
.IX Item "ignore_unique"
If you want to ignore files that only exist in one of the two 
directories, set the 'ignore_unique' flag i.e.
.Sp
.Vb 2
\&  File::DirCompare\->compare($dir1, $dir2, $sub, 
\&    { ignore_unique => 1 });
.Ve
.IP "matches" 4
.IX Item "matches"
Subroutine to be called for file pairs that \fImatch\fR, with the
following signature:
.Sp
.Vb 1
\&  $sub\->($file1, $file2)
.Ve
.Sp
These pairs are ordinarily ignored (unless \f(CW\*(C`ignore_cmp\*(C'\fR is set).
.SH "SEE ALSO"
.IX Header "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 
\&\s-1SYNOPSIS\s0 above.
.SH "AUTHOR AND CREDITS"
.IX Header "AUTHOR AND CREDITS"
Gavin Carr <gavin@openfusion.com.au>
.PP
Thanks to Robin Barker for a bug report and fix for glob problems
with whitespace.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2006\-2012 by Gavin Carr <gavin@openfusion.com.au>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.