findfiles finds file system objects in a UNIX-like environment and lists them in time (of last modification and/or access) order. It's been tested on on Linux, AIX and Cygwin.

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

Simple findfiles Examples

findfiles always lists the 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 and also the files in the Photos directory tree named '*.jpg' or "*.jpeg' modified more than 1 month ago (all case insensitive) in verbose mode, reverse sort:
   findfiles -vfr -iRm -2W -p '\.mp[g4]$' Videos -m +1M -p '\.jpg$|\.jpeg$' Photos
3. List all the files in the /dblogs and /var/log directories modified later 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!
• GNU find is a fantastic utility! 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, find's command line syntax is rather complex and unwieldy. That's when findfiles is useful.
• findfiles' output is always sorted by time in some way.
• Download findfiles from github.

More Complicated findfiles Examples

1. View the all the files in the /tmp tree modified in the last 10 seconds and in the /var/tmp tree accessed in the last 2 minutes - least recent files first:
   
   $ view $(findfiles -Rfr -m -10s /tmp -a -2m /var/tmp)
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: target time: 1505260813.333995833s ~= Wed 13 Sep 2017 10:00:13 AEST i: 181.00000D ~= 15638400.000000000s last modified after (newer than) target time ('6M') i: start time: 1520899213.333995833s ~= Tue 13 Mar 2018 11:00:13 AEDT 20180313_104138 0D_00:18:34 2675 ./bar
   
   Note the hour difference (10 vs 11 hours) and the time zone change (AEST vs AEDT) when looking back 6 months. DST was not in effect then (Sep) and "now" (Mar) DST time is in effect (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: 1505260813.333995833s ~= Wed 13 Sep 2017 10:00:13 AEST i: 181.00000D ~= 15638400.000000000s last modified after (newer than) target time ('6M') i: start time: 1520899213.333995833s ~= Tue 13 Mar 2018 11:00:13 AEDT 20171215_230124.407596237 87D_11:58:48.926399596 2675 ./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:
   
   $ export TZ=UTC; findfiles -vvfn -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 20171215_230124.407596237 87D_11:58:48.926399596 2675 ./bar
8. Info line (i:) dates in other languages (French, in this case):
   
   $ export TZ=UTC $ export LANG=fr_FR.UTF-8 $ findfiles -vfn -m -6M . i: target time: 1505260813.333995833s ~= mer. 13 sept. 2017 00:00:13 UTC i: 181.00000D ~= 15638400.000000000s last modified after (newer than) target time ('6M') i: start time: 1520899213.333995833s ~= mar. 13 mars 2018 00:00:13 UTC 20171215_120124.407596237 87D_11:58:48.926399596 2675 ./bar

Advanced findfiles Examples

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

1. Display objects' times in ISO 8601 time format with the FF_DATETIMEFORMAT environment variable:
   
   $ export TZ=UTC $ export 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 shows objects' timestamps and age, both in s.ns:
   
   $ export TZ=UTC $ export FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' $ findfiles -vvvvf -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 1513339284.407596237 = 2017-12-15T12:01:24Z 7559928.926399596 = 87D_11:58:48 2675 ./bar i: FF_STARTTIME='1520899213.333995833' (default='Now') i: FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' (default='%04d%02d%02d_%02d%02d%02d') i: FF_AGEFORMAT='%7ldD_%02ld:%02ld:%02ld' (default)
   
   A verbosity of >=4 shows the environment variables that can be configured, and their values. This is displayed after the file output.
   
3. Set the age format with environment variable FF_AGEFORMAT:
   
   $ export TZ=UTC $ export FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' $ export 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

Notes

1. 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.)
17. 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!)
18. The FF_STARTTIME environment variable is intended primarily for testing and debugging.

Version 1.x.x - 1 second time resolution

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