DirCompare(3pm)

🎀 NAME 🎀

hiii bestie, welcome to DirCompare(3pm) — the manual page for a little Perl gem called File::DirCompare: a Perl module that compares two directories using callbacks. yes, callbacks, we love a callback 💅

---

✨ SYNOPSIS ✨

okay so here's how you actually use it, copy-paste energy, no cap:

  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\n", dirname($a), basename($a);
    } elsif (! $a) {
      printf "Only in %s: %s\n", dirname($b), basename($b);
    } else {
      print "Files $a and $b differ\n";
    }
  });

  # 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";
      }
    }
  });

like, that's it. that's the whole vibe 🌈

---

💖 DESCRIPTION 💖

File::DirCompare is a perl module to compare two directories using a callback. that callback gets invoked for all files that are 'different' between the two directories, AND for any files that exist only in one or the other directory — the so-called 'unique' files. she's thorough, she's giving attention to detail 🫶

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, periodt:

• $dir1 and $dir2 are paths to the two directories to be compared.
• $sub is the subroutine reference called for all unique or different files.

$opts is an optional hashref of options — see OPTIONS below, bestie 👇

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 one indicates $file1 exists only in the first directory given ($dir1) 👈
• and the second indicates $file2 exists only in the second directory given ($dir2) 👉

iykyk. it's literally just "who's here and who isn't" 😌

---

🌸 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_cmp      => 1,
    ignore_unique   => 1,
    matches         => $matches_sub,
  });

and here's the tea on each one 🍓

• 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 });

• matches — Subroutine to be called for file pairs that match, with the following signature:

  $sub->($file1, $file2)

These pairs are ordinarily ignored (unless "ignore_cmp" is set).

okay important: those matching pairs get ignored by default unless "ignore_cmp" is set, so don't come crying to me when your matches callback is sitting there in silence 🙈

---

🔥 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. so like, if you want the chill low-effort version, she's right there 👑

---

👑 AUTHOR AND CREDITS 👑

Gavin Carr <gavin@openfusion.com.au>

Thanks to Robin Barker for a bug report and fix for glob problems with whitespace. shoutout Robin, doing the lord's work 🫡

---

💜 COPYRIGHT AND LICENSE 💜

Copyright 2006-2012 by Gavin Carr <gavin@openfusion.com.au>.

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

---

and that's the whole page bestie, no notes 💅 this was DirCompare(3pm) from perl v5.26.1, dated 2018-03-31 — go forth and diff those directories, you absolute icon 🦋✨