findfiles

findfiles finds file system objects in UNIX-like environments. The orginal purpose was to have a very easy method of listing objects in time (of last modification and/or access) order. As of version 3.4.0, one may also list objects in size order. findfiles has been tested on on Linux, AIX and Cygwin - but it's a C program - so it'll probably run on many environments.

But we already have find for that, right? Correct, but findfiles was originally designed to have a time focus and adheres more closely to the traditional UNIX philosophy of "do one thing and do it well".

Simple findfiles Examples

findfiles is primarily used to list objects in time sorted order. Here are some common use cases:

1. List all the files in the /app directory tree that were modified less than 30 seconds ago:
   
   $ findfiles -fr -m -30s /app
2. List all the files in the Videos directory tree for files named '*.mpg' or "*.mp4' modified less than 2 weeks ago (newer) and also the files in the Photos directory tree named '*.jpg' or "*.jpeg' modified more than 1 month ago (older), all case insensitive, in verbose mode with a reverse sort order:
   
   $ findfiles -vfr -iR -p '\.mp[g4]$' -m -2W Videos -p '\.jpg$|\.jpeg$' -m +1M Photos
3. List all the files in the /dblogs and /var/log directories modified later (newer) than lastlogfile was:
   
   $findfiles -f -M lastlogfile /dblogs /var/log

findfiles classifies file system objects as one of these three types: (regular) files, directories, and "other" (e.g., pipes, block specials, symbolic links, etc.)

The findfiles Usage Message

See toward the bottom of the findfiles usage message for more examples of how to use it:

Both findfiles and find?

• Yes! Because they do different things and both are incredibly useful!
• Unlike find, findfiles' output is sorted by time in some way (except when using -S/--sort-by-size).
• GNU find is a fantastic utility - I use it all the time! It does an amazing number of things. When it comes to finding, it does nearly everything - it's like 128 Swiss Army Knives all bolted together. But for things that findfiles does, findfiles' command line syntax is (IMHO) cleaner and simpler. findfiles is especially useful in cases where time sort order is required.
  
  For example, to find files in the /tmp tree modified less than 250 weeks ago sorted in time of last modification order, one can use:
  $ findfiles -fr -m -250W /tmp
  
  Instead of something like this (that produces the same output):
  $ find /tmp -newermt '250 weeks ago' -type f -printf "%T@ %p\n" | sort -nr | awk '{ print $2; }'
• Early versions of findfiles were written in the dark times, long, long before find -newerXY.
• Download findfiles from github.

Some findfiles Examples

1. View the all the files in the /tmp tree modified in the last 10 seconds and in the /var/log tree accessed in the last 2 minutes - least recent files first:
   
   $ view $(findfiles -Rfr -m -10s /tmp -a -2m /var/log)
2. Remove all files in the /tmp and /var/tmp trees that were last modified 1 year ago or more. (Obviously you shouldn't do this if you have files that might still be required after a year!)
   
   $ rm $(findfiles -fr -m +1Y /tmp /var/tmp)
3. No access or modification times have been specified, so the default value ('-m 0s') means all possible modification times (including future times) and the default patter ('-p ".*"') meaning all patterns.
   
   $ findfiles -vf . 20160510_101641 0D_00:15:11 30 ./barfoo 20160510_101638 0D_00:15:14 30 ./foobar 20160510_101633 0D_00:15:19 30 ./bar 20160510_101630 0D_00:15:22 30 ./foo
4. Same as the above example, but with reverse sort ('-R'), times displayed in seconds ('-s'), and units (both 's' and 'B') displayed with the units option ('-u'):
   
   $ findfiles -vfRsu . 20160510_101630 922s 30B ./foo 20160510_101633 919s 30B ./bar 20160510_101638 914s 30B ./foobar 20160510_101641 911s 30B ./barfoo
5. Find all files in the current directory modified <= 6 months ago. A verbosity of >= 2 shows the start time information (i:) line:
   
   $ findfiles -vvf -m -6M . i: start time: 1640998800.000000000s ~= Sat Jan 01 12:00:00 2022 AEDT +1100 i: target time: 1625101200.000000000s ~= Thu Jul 01 11:00:00 2021 AEST +1000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1640998800.000000000s ~= Sat Jan 01 12:00:00 2022 AEDT +1100 20211130_073158 32D_04:28:01 310972 ./bar
   
   Note the hour difference (12 vs 11 hours) and the time zone change (AEDT vs AEST) when looking back 6 months. DST was in effect when findfiles was started ("now", Jan 1 2022), but DST was not in effect 6 months earlier (the target time, in July 1 2021). Note: southern hemisphere!

   A verbosity of >= 2 when using time of last modification and/or access also shows the target time(s) and the last modified/accessed time(s) newer/older than (in s.ns) information (i:) lines.

6. The same as the example above, but this time with the display nanoseconds ('-n') flag as well:
   
   $ findfiles -vvfn -m -6M . i: target time: 1621232728.280166380s ~= Mon May 17 16:25:28 2021 AEST +1000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130328.280166380s ~= Wed Nov 17 17:25:28 2021 AEDT +1100 20211117_172324.610878747 0D_00:02:03.669287633 1278 ./bar
7. The same as the previous example, but this time the timezone environment variable TZ has been set to UTC. Note that no daylight savings time (DST) time is in effect and so the hour and timezone values are unchanged:
   
   $ TZ=UTC findfiles -vvfn -m -6M . i: target time: 1621232828.669657758s ~= Mon May 17 06:27:08 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130428.669657758s ~= Wed Nov 17 06:27:08 2021 UTC +0000 20211117_062324.610878747 0D_00:03:44.058779011 1278 ./bar
8. Info line (i:) dates in other locales (languages) - French, in this case:
   
   $ TZ=UTC LANG=fr_FR.UTF-8 findfiles -vvfn -m -6M . i: target time: 1621233081.829776341s ~= lun. mai 17 06:31:21 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130681.829776341s ~= mer. nov. 17 06:31:21 2021 UTC +0000 20211117_062324.610878747 0D_00:07:57.218897594 1278 ./bar
9. As of version 3, one may specify absolute timestamps as access (-a) and modification (-m) values:
   
   In this case, find files with a last modification ('-m') timestamp before (hence '-') a particular time:
   $ findfiles -vvf -m -20211010_150000 ~ i: target time: 1633838400.000000000s ~= Sun Oct 10 15:00:00 2021 AEDT +1100 i: 42.77967D ~= 3696164.536318348s last modified before (older than) target time ('20211010_150000') i: start time: 1637534564.536318348s ~= Mon Nov 22 09:42:44 2021 AEDT +1100 20211006_200750 46D_13:34:53 77 ./foo 20200515_110242 555D_21:40:01 1284848 ./foobar 20141008_235309 2601D_09:49:35 193 ./foofoo
   
   In this case, find files with a last access ('-a') timestamp after (hence without '-') a particular time:
   
   $ findfiles -vvf -a 20210103_143000.5 ~ i: target time: 1609644600.500000000s ~= Sun Jan 03 14:30:00 2021 AEDT +1100 i: 322.80560D ~= 27890403.413378634s last accessed after (newer than) target time ('20210103_143000.5') i: start time: 1637535003.913378634s ~= Mon Nov 22 09:50:03 2021 AEDT +1100 20211122_070659 0D_02:43:04 523 ./bar 20211110_091036 12D_00:39:27 9273 ./barfoo 20211008_095333 44D_23:56:30 2795 ./barbar
10. As of version 3, -L/--symlinks: follow symbolic links - à la find and other *NIX utilities.
    
    $ findfiles -vfr -L symlink
11. As of version 3.0.1, -x/--exclude patterns. Essentially, this is (boolean) not -p/--pattern.
    
    $ findfiles -vfr -m -30s -x '^\.journal$' /var/log
12. As of version 3.1.1:

    The -h/--help command line option has been retired. However, invoking findfiles with no arguments displays the usage text (see above).

    Object sizes may now be displayed in 'human readable' format. To display object sizes in kiB, MiB, etc., use the -h|--human-1024 option:
    $ findfiles -vfh -p '.iso$' . 20221227_115311 73D_02:32:45 2.23GiB ./Fedora-KDE-Live-x86_64-37-1.7.iso
    
    To display object sizes in kB, MB, etc., use the -H|--human-1000 option:
    $ findfiles -vfH -p '.iso$' . 20221227_115311 73D_02:32:49 2.39GB ./Fedora-KDE-Live-x86_64-37-1.7.iso
    
    Each time a -p|--pattern or -x|--exclude option is invoked, the 'search buffer' is (re)initialized. In this example, find all files starting with 'passwd' in /etc, as well as all files not containing 'key' in /etc/ssh.
    $ findfiles -fp ^passwd /etc -x key /etc/ssh
    
    One may create more complicated ERE combinations by invoking '-P|--and-pattern' and/or '-X|--and-exclude'. These 'accumulate' (logical and operation) - they are parsed left to right. In this example, find all files in Dir1 starting with 'dev', except any that contain the pattern 'old', and the same for Dir2, except files containing 'nope' in Dir2 are also excluded.
    
    $ findfiles -fp ^dev -X old Dir1 -X nope Dirs
13. As of version 3.3.0, the object "type" can be displayed with the -T/--types option. The object types are: Fil, Dir, Sln, Blk, Chr, FIF, Soc, and Oth(er).
    
    $ findfiles -fdoT /mnt /etc/passwd Fil /etc/passwd Dir /mnt
    
    Verbose mode added.
    $ findfiles -vfdo --types /mnt /etc/passwd /bin 20231222_115434 19D_19:55:40 3068 Fil /etc/passwd 20230721_100000 173D_20:50:14 7 Sln /bin 20230721_100000 173D_20:50:14 4096 Dir /mnt
14. As of version 3.4.0, one may select objects by their size with -z/--size and/or sort the output by object size with -S/--sort-by-size (the default is increasing size).
    
    $ findfiles -vf -S . 20241231_132823 5D_19:59:42 58698 ./foo 20250101_125913 4D_20:28:53 60310 ./bar 20250103_130553 2D_20:22:12 60556 ./foobar 20250103_132610 2D_20:01:56 60635 ./barfoo
    
    Reverse the sort order with -R/--reverse:
    $ findfiles -vf -SR . 20250103_132610 2D_20:03:20 60635 ./barfoo 20250103_130553 2D_20:23:36 60556 ./foobar 20250101_125913 4D_20:30:17 60310 ./bar 20241231_132823 5D_20:01:06 58698 ./foo
    
    Select only files that are a specified size or larger:
    $ findfiles -vf -S -z 60400 . 20250103_130553 2D_20:26:30 60556 ./foobar 20250103_132610 2D_20:06:14 60635 ./barfoo
    
    Select only files that are a specified size or smaller, reverse sort:
    $ findfiles -vf -SR -z -60400 . 20250101_125913 4D_20:35:48 60310 ./bar 20241231_132823 5D_20:06:37 58698 ./foo
15. As of version 3.4.0, select objects owned by a particular username (e.g. root) or userID (e.g. 0).
    Select objects owned by the root user:
    $ findfiles -vf -U root . 20250101_125913 4D_20:39:55 60310 ./bar
    
    Select objects owned by the user with userID of 1234:
    $ findfiles -vf -U 1234 . 20250103_132610 2D_20:15:05 60635 ./barfoo 20250103_130553 2D_20:35:22 60556 ./foobar

More Advanced findfiles Examples

Warning: Be very careful when using the FF_ environment variables! Poor choices may elicit unfortunate results!

1. Display objects' timestamps in different formats with the FF_DATETIMEFORMAT environment variable. In this example use ISO 8601 time format (in UTC/GMT):
   
   $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' findfiles -vf -m -6M . 2017-12-15T12:01:24Z 87D_11:58:48 2675 ./bar
2. A verbosity of >= 3 also shows objects' timestamps (since 'the Epoch') and ages (since start time), both in s.ns :
   
   $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' findfiles -vvvvf -m -6M . i: target time: 1621233588.206924091s ~= Mon May 17 06:39:48 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637131188.206924091s ~= Wed Nov 17 06:39:48 2021 UTC +0000 1637017546.888209896 = 2021-11-15T23:05:46Z 113641.318714195 = 1D_07:34:01 15459 ./bar i: FF_AGEFORMAT='%7ldD_%02ld:%02ld:%02ld' # default i: FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' # default='%04d%02d%02d_%02d%02d%02d' i: FF_INFODATETIMEFORMAT='%a %b %d %H:%M:%S %Y %Z %z' # default i: FF_STARTTIME='Now' # default i: FF_TIMESTAMPFORMAT='%Y%m%d_%H%M%S' # default

   Note for the example above: a verbosity of >=4 shows the environment variables that can be configured - their current and default values. This is displayed after the file output.

3. Set the age format with environment variable FF_AGEFORMAT:
   
   $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' FF_AGEFORMAT='%7ld Days, %02ld hours, %02ld minutes, %02ld seconds' findfiles -vvf -m -6M . i: target time: 1505260813.333995833s ~= Wed 13 Sep 2017 00:00:13 UTC i: 181.00000D ~= 15638400.000000000s last modified after (newer than) target time ('6M') i: start time: 1520899213.333995833s ~= Tue 13 Mar 2018 00:00:13 UTC 2017-12-15T12:01:24Z 87 Days, 11 hours, 58 minutes, 48 seconds 2675 ./bar
4. As of version 3, all of the FF_... environment variables may also be set as command line arguments - FF_DATETIMEFORMAT and FF_AGEFORMAT, in this case:
   
   $ TZ=UTC findfiles -V FF_DATETIMEFORMAT='%04d/%02d/%02d-%02d:%02d:%02d' -V FF_AGEFORMAT='%ld days, %02ld:%02ld:%02ld' -vvvvf -m -6M . i: target time: 1621636554.017067274s ~= Fri May 21 22:35:54 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637534154.017067274s ~= Sun Nov 21 22:35:54 2021 UTC +0000 1637351057.375464374 = 2021/11/19-19:44:17 183096.641602900 = 2 days, 02:51:36 92546 ./foo i: FF_AGEFORMAT='%ld days, %02ld:%02ld:%02ld' # default='%7ldD_%02ld:%02ld:%02ld' i: FF_DATETIMEFORMAT='%04d/%02d/%02d-%02d:%02d:%02d' # default='%04d%02d%02d_%02d%02d%02d' i: FF_INFODATETIMEFORMAT='%a %b %d %H:%M:%S %Y %Z %z' # default i: FF_STARTTIME='Now' # default i: FF_TIMESTAMPFORMAT='%Y%m%d_%H%M%S' # default

Notes

1. Except when -S/--sort-by-time is used, the output of findfiles is time focused - time of last access and/or last modification. Even if there is no time specified on the command line, the output is sorted by time.
2. The default sort order is newest first (decreasing).
3. findfiles parses (and processes) command line arguments (targets and options) in left to right (L-R) order.
4. Some command line options are flags that can be toggled on/off (parsed L-R).
5. Some command line options require parameters that can be set and reset (parsed L-R).
6. Some command line options are global - they cannot be toggled on/off.
7. --long-options are supported, but getopt_long was not used because of the L-R requirement. As a result, "--" does not work (i.e., not the way getopt_long handles it).
8. As of version 2, findfiles uses the 'nanosecond' timestamp information (in addition to the seconds information) to determine objects' ages and their sort order. However, findfiles reads objects' access and modification times from the file system via OS calls. These values will almost certainly not be accurate to the nanosecond, only to the resolution the file system (and/or OS) provides.
9. findfiles calculates an object's age by subtracting that object's last modification (or access) time from the start time (normally 'now' - the time findfiles was started). Both seconds and 'nanoseconds' for both of these times are used to determine this time difference - the object's age. 'Nanoseconds' may be displayed (with the '-n' option). If they are not, only the seconds value is displayed. That is, the age values are not rounded to the nearest second.
10. If findfiles is instructed to find some objects based on last modification time and others based on last access time, the output will be sorted based whichever time (last access or last modification) was requested for each object.
11. Integer or floating point number(s) of weeks, days, hours, minutes or seconds may be specified.
12. Only integer numbers of years and months may be specified because years and months vary in length.
13. As with any command (even find), be extremely careful when calling rm or mv, e.g.: rm $(findfiles -fr -m 1Y /tmp /var/tmp) ! findfiles might not return any files, so rm would have no argument!
14. Under certain circumstances, findfiles reports negative (modification and/or access) age(s) for objects. When findfiles starts, the first thing it does is record its start time. It takes a finite amount of time to traverse the target(s). The more objects to be traversed, the longer it takes to check them all. Any target object that's modified and/or accessed after this start time will therefore be reported as having a negative age. This is very likely to occur when searching very large trees containing objects that are modified/accessed frequently. For example, running findfiles with a target of '/' (the entire file system) will likely report objects with negative ages in /proc and /sys. So don't be alarmed if you observe this.
15. Informational output lines (starting with 'i:') go to stderr, so it's a trivial matter to separate them from the file list output, which goes to stdout.
16. It's not possible to change the order of the values displayed using FF_DATETIMEFORMAT and/or FF_AGEFORMAT. For example, one may not switch the order of day and month. (See printf for further information on formatting.) Also, use all the values - do not omit any.
17. The values of FF_INFODATETIMEFORMAT may be set within the constraints of strftime. (Not all values must be used, and the order is arbitrary.)
18. The values of FF_TIMESTAMPFORMAT may be set within the constraints of strptime. (Not all values must be used, and the order is arbitrary.)
19. findfiles uses 24 hour time everywhere except in the informational ('i:') output lines - e.g., if LANG is en_US.UTF8. (YOSJ staff use 24 hour time whenever it's available!)
20. The FF_STARTTIME environment variable is intended primarily for testing and debugging. Note: FF_STARTTIME must always be entered in the format YYYYMMDD_HHMMSS[.ns]. I.e., FF_TIMESTAMPFORMAT is not used for start times.
21. As of version 3, these are the new features that break backward compatibility:
    • Long options '--acc-age' is now '--acc-info' and '--mod-age' is now '--mod-info'.
    • findfiles now treats symbolic links the same way many other *NIX commands do (e.g., find). (Before, they were always treated as symbolic links - they were never followed.)
    • The required format for FF_STARTTIME is now YYYYMMDD_HHMMSS[.ns] (FF_TIMESTAMPFORMAT is not used), and it respects the local timezone - e.g., TZ. (Before, it was s[.ns] since the Epoch using UTC.) Note: This feature is only meant for testing findfiles.
    And these are version 3 features that do not break backward compatibility:
    • Absolute target times may now be specified (i.e., with '-a' and '-m' arguments). The default format is 'YYYYMMDD_HHMMSS[.ns]'. One may enter timestamps in a different format by setting FF_TIMESTAMPFORMAT. For example, when using -V -FF_TIMESTAMPFORMAT=%H%M, one could specify absolute timestamps using only hour and minute values (e.g., '-m -2355'). All values that are not specified are populated using the values of the time findfiles' start time. Note: absolute timestamps must always end in a digit or a decimal point ('.'). Before, access (-a) and modification (-m) times were only set relatively (to the starttime), e.g., '10D' or '-30s'.
    • FF_... values can now be set on the command line (as well as set as environment variables). Note: CLI values overwrite environment variables if the same variable is set both ways.

Version 1.x.x - 1 second time resolution

Version 1.x.x info can be found here: findfiles v1.x.x.