TOPNFILES(8)

NAME
topnfiles - Find top-n files based on file metadata such as modification time

SYNOPSIS
topnfiles [options ...] <startpath>...

DESCRIPTION
topnfiles Purpose: In a large directory structure, identify those files which
 - have least/most recently been used, or
 - are smallest/largest

For each directory entry in the result set, a line is printed to stdout.

The order of output lines follows requested search order:
 - If using "-r youngest", youngest qualifying files are printed last.
 - If using "-r oldest", oldest qualifying files are printed last.
 - If using "-r largest", largest qualifying files are printed last.
 - If using "-r smallest ", smallest qualifying files are printed last.

The elements of the line are controlled by the --output parameter. Element order is as follows (to the extent the elements are requested in the --output argument):
 - Size (in bytes)
 - ISO timestamp
 - Unix timestamp
 - File path

OPTIONS

-a, --attribute
    Which time-like file attribute to sort on, when time based sorting is asked for: accessed, created, or modified. A combination of "--attribute accessed" and "--directories" is refused (unless --weird is used). No matter what, a combination of an attribute argument and "--return largest/smallest" is refused.

-d, --directories
    Include directories, not only files.

-e, --exclude FILTER
    Only consider files where the path does NOT match the specified regular expression. See FILTERING for more on this.

-i, --include FILTER
    Only consider files where the path matches the specified regular expression. See FILTERING for more on this.

-n, --number integer
    The number of files to return; defaults to 10.

-o, --output FLAGS
    Which file metadata to include in output. Options: 0=print0, b=size(bytes), i=ISO time, j=JSON, p=human readable path, u=unixtime. Defaults to "ip". The default output format may change between versions. If you depend on the output being in a particular format, stick to the JSON or print0 formats.
    In the "p" case, a line is printed per path. Paths are made print-friendly: Problematic characters like newlines and the bell character are replaced with the Unicode control pictures or caret escaped charaters, depending on the capabilities of the environment. This guarantees, that the one-path-per-line rule is upheld.
    "0" means that instead of separating with newlines, the NULL character will separate each printed path, like the "find" tool's -print0 option. "0" may not be combined with other output modifiers.

-r, --return
    Return oldest, youngest (default), largest, or smallest.

-x, --xdev
    Within each start directory: Stay within one mountpoint, i.e. do not descend into other filesystems.

-h, --help
    Display help and exit.

-v, --version
    Display version information and exit.

FILTERING
If a path is match with both the --include and the --exclude pattern, it will not be considered.

For the --exclude and --include arguments, the regular expresion dialect is that of the 'regex' Rust crate: https://docs.rs/regex/latest/regex/#syntax
If you want the patterns to match case insensitively, use the (?i) prefix to the pattern, e.g.:
--include '(:i)\./my/pattern'

NOTES
topnfiles will (unless you use the --weird argument) refuse to work, if you pass start directories which are the same (after path canonicalization). But it does not try to detect, if you pass directories where one is a sub-directory of the other; in this case, a directory entry may appear more than one time in output.

BUGS
No known bugs.