Author image Jens Rehsack
and 1 contributors


File::Find::Rule::Age - rule to match on file age


    # Legacy API
    use File::Find::Rule::Age;
    my @old_files = find( file   => age => [ older => '1M' ], in => '.' );
    my @today     = find( exists => age => [ newer => '1D' ], in => '.' );


File::Find::Rule::Age makes it easy to search for files based on their age. DateTime and File::stat are used to do the behind the scenes work, with File::Find::Rule doing the Heavy Lifting.


Legacy Interface

    age( [ $criterion => $age ] )

must be one of "older" or "newer", respectively.


must match /^(\d+)([DWMYhms])$/ where D, W, M, Y, h, m and s are "day(s)", "week(s)", "month(s)", "year(s)", "hour(s)", "minute(s)" and "second(s)", respectively - I bet you weren't expecting that.

The given interval is subtracted from now for every file which is checked to ensure search rules instantiated once and executed several times in process lifetime.

By 'age' I mean 'time elapsed after mtime' (the last time the file was modified) - without the equal timestamp.

    # now is 2014-05-01T00:00:00, start of this years workers day
    # let's see what has been worked last week
    my @old_files = find( file => age => [ older => "1W" ], in => $ENV{HOME} );
    # @old_files will now contain all files changed 2014-04-24T00:00:01 or later,
    # 2014-04-24T00:00:00 is ignored

Modern API

The modern API provides 12 functions to match timestamps:

             | before  | until    | since    | after
    modfied  | mtime < | mtime <= | mtime >= | mtime >
    accessed | atime < | atime <= | atime >= | atime >
    created  | ctime < | ctime <= | ctime >= | ctime >

Each function takes one argument - the referring timestamp. Following representations are supported (in order of check):

File name

The corresponding mtime, atime or ctime or the specified file is used to do the appropriate equation, respectively.

If a relative path name is specified and the current working directory is changed since rule instantiation, the result is undefined.

seconds since epoch

Each's file mtime, atime or ctime is compared as requested to given number.

DateTime object

Each's file mtime, atime or ctime is compared as requested to given DateTime.

DateTime::Duration object

Each's file mtime, atime or ctime is compared as requested to given now - $duration. now is determined at each check again, for same reasons as in legacy API.


    use File::Find::Rule;
    use File::Fine::Rule::Age;

    my $today = DateTime->now->truncate( to => "today" );
    my @today = find( owned => modified_since => $today, in => $ENV{PROJECT_ROOT} );

    my @updated = find( file => mofified_after => $self->get_cache_timestamp,
                        in => $self->inbox );


Pedro Figueiredo, <pedro period figueiredo at sns dot bskyb dotty com>

Jens Rehsack, C << rehsack at cpan dot org


Please report any bugs or feature requests to bug-find-find-rule-age at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Find::Find::Rule::Age

You can also look for information at:


Richard Clamp, the author of File::Find::Rule, for putting up with me.


Copyright (C) 2008 Sky Network Services. All Rights Reserved.

Copyright (C) 2013-2014 Jens Rehsack. All Rights Reserved.

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


File::Find::Rule, DateTime, File::stat