findfiles

findfiles finds file system objects in UNIX-like environments. The original purpose was to have a very easy method of listing objects in time (of last modification and/or access) order. Recent versions also list objects sorted by size or name. findfiles has been tested on on Linux and (quite a while back) on AIX and Cygwin - but it's a C program - so it'll probably run on many/most POSIX 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 or -N/--sort-by-name).
• 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 pattern ('-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 -vvfnN -m -6.5W . i: target time: 1778344611.447854489s ~= Sat May 09 16:36:51 2026 UTC +0000 i: 45.50000D ~= 3931200.000000000s last modified after (newer than) target time ('6.5W') i: start time: 1782275811.447854489s ~= Wed Jun 24 04:36:51 2026 UTC +0000 20260624_035742.438909308 0D_00:39:09.008945181 3341 ./bar 20260624_035723.449676564 0D_00:39:27.998177925 30 ./eclair 20260624_035717.528603991 0D_00:39:33.919250498 30 ./éclair 20260624_040046.347163424 0D_00:36:05.100691065 30 ./foobar
8. Info line (i:) dates in other locales (languages) - French, in this case. Note that "six and a half weeks" is specified as "6,5" - with a comma as the decimal separator, as is preferred in many languages.
   
   $ LANG=fr_FR.UTF-8 TZ=UTC findfiles -vvfnN -m -6,5W . i: target time: 1778344642.936166534s ~= sam. mai 09 16:37:22 2026 UTC +0000 i: 45,50000D ~= 3931200.000000000s last modified after (newer than) target time ('6,5W') i: start time: 1782275842.936166534s ~= mer. juin 24 04:37:22 2026 UTC +0000 20260624_035742.438909308 0D_00:39:40.497257226 3341 ./bar 20260624_035723.449676564 0D_00:39:59.486489970 30 ./eclair 20260624_035717.528603991 0D_00:40:05.407562543 30 ./éclair 20260624_040046.347163424 0D_00:36:36.589003110 30 ./foobar
9. German, in this case. Note that specifying LC_COLLATE=C changes the collation sequence (sort order).
   
   $ LC_COLLATE=C LANG=de_DE.UTF-8 TZ=UTC findfiles -vvfnN -m -6,5W . i: target time: 1778344674.527471176s ~= Sa Mai 09 16:37:54 2026 UTC +0000 i: 45,50000D ~= 3931200.000000000s last modified after (newer than) target time ('6,5W') i: start time: 1782275874.527471176s ~= Mi Jun 24 04:37:54 2026 UTC +0000 20260624_035742.438909308 0D_00:40:12.088561868 3341 ./bar 20260624_035723.449676564 0D_00:40:31.077794612 30 ./eclair 20260624_040046.347163424 0D_00:37:08.180307752 30 ./foobar 20260624_035717.528603991 0D_00:40:36.998867185 30 ./éclair
10. FF_INFODATETIMEFORMAT can be used to display information timestamps using 12 hour time format. Though this makes absolutely no sense the the YOSJ staff. Using this environment variable is more versatile then using LC_TIME (which is ignored).
    
    $ FF_INFODATETIMEFORMAT='%a %b %d %I:%M:%S %p %Y %Z %z' findfiles -vvnfd -m 1m findfiles.c i: target time: 1782348915.756821721s ~= Thu Jun 25 10:55:15 AM 2026 AEST +1000 i: 0.00069D ~= 60.000000000s last modified before (older than) target time ('1m') i: start time: 1782348975.756821721s ~= Thu Jun 25 10:56:15 AM 2026 AEST +1000 i: 1 objects found 20260625_094952.361559545 0D_01:06:23.395262176 66565 findfiles.c
11. findfiles will use the following locale environment variables (when set) - in this order:
    1. LANG: All locale categories are set to use this value.
    2. LC_COLLATE: set the object name collation sequence to use this value. Overwrites LANG.
    3. LC_NUMERIC: set the numeric format (e.g., the decimal separator character) to use this value. Overwrites LANG.
    4. LC_ALL: set all locale categories to use this value. Overwrites all of the above.
    
    Invalid values for any of these environment variables result in an error and findfiles aborts.
12. 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
13. Use -L/--symlinks to follow symbolic links - à la find and other *NIX utilities.
    
    $ findfiles -vfr -L symlink
14. Use -x/--exclude to exclude patterns. Essentially, this is (boolean) not -p/--pattern.
    
    $ findfiles -vfr -m -30s -x '^\.journal$' /var/log
15. Object sizes may 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
16. 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
17. 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
18. 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
19. 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
20. Sorting by object name (-N/--sort-by-name) uses the locale specified by the LANG environment variable:
    
    $ LANG=fr_FR.UTF-8 findfiles -vvfN . i: start time: 1781935924.153808191s ~= sam. juin 20 16:12:04 2026 AEST +1000 20260620_160744 0D_00:04:20 30 ./bar 20260620_160744 0D_00:04:20 30 ./eclair 20260620_160744 0D_00:04:20 30 ./éclair 20260620_160744 0D_00:04:20 30 ./Éclair 20260620_160744 0D_00:04:20 30 ./foo 20260620_160744 0D_00:04:20 30 ./manana 20260620_160744 0D_00:04:20 30 ./mañana
    
    When LC_COLLATE environment variable is set, object names are sorted by that locale (even if LANG is also set).
    $ LANG=es_ES.UTF-8 LC_COLLATE=C findfiles -vvfN . i: start time: 1781936574.058350440s ~= sáb jun 20 16:22:54 2026 AEST +1000 20260620_160744 0D_00:15:09 30 ./bar 20260620_160744 0D_00:15:09 30 ./eclair 20260620_160744 0D_00:15:09 30 ./foo 20260620_160744 0D_00:15:09 30 ./manana 20260620_160744 0D_00:15:09 30 ./mañana 20260620_160744 0D_00:15:09 30 ./Éclair 20260620_160744 0D_00:15:09 30 ./éclair

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. 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 using -S/--sort-by-time or -N/--sort-by-name, 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) may be specified for weeks, days, hours, minutes or seconds.
12. Only integer values may be specified for years and months because these 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 (starting with 'i:'), warning (starting with 'W:'), and error (starting with 'E:') output lines 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.) If one must display 12 hour formatted time, use this environment variable.
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. 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.
20. 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. Note: This feature is only meant for testing findfiles.
21. Absolute target times may 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 separator (typically '.' or ',', depending upon the locale).
22. If a FF_... environment variable is set on both the command line and as an environment variable, the command line values take precedence.

Version 1.x.x - 1 second time resolution

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