The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


File::Set - Mange/build a set of files from a list of file/directories


  use File::Set;

  $FS = File::Set->new();

  # Add directories (and implicitly all files and sub-dirs) to file set
  $FS->add('/usr/lib', '/usr/include');
  # Add files in directory (not recursive);
  $FS->add({ recurse => 0 }, '/usr/local/bin');

  # Exclude particular files/directories
  $FS->exclude('/usr/include/linux', '/etc/shadow');

  # Add/exclude from file (see below for file format)

  # List files, calling callback for each dir/file
  $FS->list($self, \&list_callback, 0);

  # Save a list of checksums for all files/directories

  # Compare a list against a previously saved checksum db
  #  and call callback for added/deleted/changed files
  $FS->compare_checksum_db('/tmp/checksumdb', \&callback)

  sub list_callback {
    my ($self, $prefix, $path, $type, $stat) = @_;
    ... called back for each file/dir/etc found ...


This module is designed to build and manipulate a set of files from a list of input directories and files. You can specify whether directories should be recursed or not, or specific sub-directories ignored.



Create a new fileset object. Any parameters are passed straight to the add() method


Sets a path 'prefix' that's prepended to all paths before they are used.

add([ $Opts ], $path1, $Path2, ...)

Add the given paths to the file set.

$Opts is an option hash-reference of options.


Set if we should recurse into sub-folders as well. True by default


Set if we should exclude this file/path rather than add it

exclude([ $Opts ], $path1, $Path2, ...)

Exclude the given paths from the file set.

Like calling add() with the exclude option set to true


Open the given file and add the paths to the fileset

The file can have:

  • Blank lines which are ignored

  • Lines beginning with # which are ignored

  • A line with a single path to a file/directory.

Optionally each line with a path can begin with:


To exclude the path rather than add it


To add the path non-recursively


Return an array of all paths added/excluded

Each item as an array-ref of 2 items. The first item is the path and the second item is the hash-ref of options

canon_path($path1, $Path2, ...)

Cleanup the given paths to a consistent form

list($Context, $Callback, $ErrorHandler)

The main method call. Iterates through all dirs, sub-dirs and files added through add() but not excluded through exclude()

For each file/directory calls code-ref $Callback passing $Context as the first parameter. Additional parameters are:


Prefix set with the prefix() call or '' if none


Full path of this file/directory


A string describing the type of the file/dir

f - a file
d - a directory
u - other

A hash-ref of information from the lstat() system call: Dev Ino Mode NLink Uid Gid RDev Size ATime MTime CTime BlkSize Blocks

The $ErrorHandler parameter controls error handling during the recursion. This can happen for instance if files/directories are deleted during the traversal.

false (eg undef/0/"")

If not passed or false value, then any errors are ignored

true (eg 1)

If true, then any errors cause a die to occur


If a sub ref, then the sub ref is called with the file/directory name that went missing during the traversal


Uses the list() method to iterate through added paths, and outputs a checksum of information about all dirs/files to $DbFile.

For all files this includes mode, gid, uid, size. For files this also includes the md5 checksum.

Can be used for the c<compare_checksum_db()> call below

compare_checksum_db($DbFile, $Context, $Callback)

Uses the list() method to iterate through added paths, and compares to the contents of the $DbFile file. If any files or directories have changed, calls the $Callback code-ref with $Context as the first parameter. Additional parameters are:


Action that occured on the file

n - new
c - changed
d - deleted

Type of file/dir (see above)


Prefix set with the prefix() call or '' if none


Path to file


Create a tar file containing the added paths

Correctly creates .tar.gz and .tar.bz2 files



Latest news/details can also be found at:


Rob Mueller <>


Copyright (C) 2004-2008 by FastMail IP Partners

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