I'm sending this as an email because I'm new to this, and
https://www.gnu.org/software/findutils/ says "there will be occasions
where you're not sure whether the problem you have is actually a bug, or
you just want to talk about ideas for improving findutils. Using the
mailing list is a good way to do that." (Also because I can't find a
place/button on https://savannah.gnu.org/bugs/ to actually submit anything.)
I am not sure what the most recent documentation page for 'find' is, in
particular for the documentation on the -newerXY argument. I've found
half a dozen versions, most of which I find hard to understand or even
misleading. First I'll explain what I find confusing, then what I'm
suggesting as better wording.
Here's the relevant part of the documentation (some lines removed), as
found in the man page for v 4.9.0 (on Linux Mint, but I assume the same
elsewhere):
---------
-newerXY reference
Succeeds if timestamp X of the file being considered is newer
than timestamp Y of the file reference. ...
a The access time of the file reference
B The birth time of the file reference
c The inode status change time of reference
m The modification time of the file reference
t reference is interpreted directly as a time
--------
When I read this, I (mis-)understand "timestamp Y of the file reference"
to mean that 'reference' is a filename, and that's the only way to use
this arg. Given that misunderstanding I don't understand what
"reference is interpreted directly as a time" means, i.e. I'm left
confused by the man page. Furthermore, the letters all (except t) talk
about the times "of the file reference", whereas actually they pertain
to the times of BOTH the file being considered and the reference file.
Here's a different version of the man page on
https://www.gnu.org/savannah-checkouts/gnu/findutils/manual/html_node/find_html/Comparing-Timestamps.html,
also hard to understand:
--------
Test: -newerXY reference
Succeeds if timestamp ‘X’ of the file being considered is newer
than timestamp ‘Y’ of the file reference.
...
‘t’
The reference argument is interpreted as a literal time,
rather than the name of a file.
--------
This version again uses the confusing "timestamp ‘Y’ of the file
reference", but the 't' part (particularly the "rather than") helps to
clarify that. There is also an example, but the example doesn't
illustrate the use of 't'.
Finally, there's the documentation as show on
https://unix.stackexchange.com/questions/169798/what-does-newermt-mean-in-find-command:
---------
-newerXY reference
Compares the timestamp of the current file with reference.
The reference argument is normally the name of a file
(and one of its timestamps is used for the comparison)
but it may also be a string describing an absolute time.
...
t reference is interpreted directly as a time
----------
IMO, this one comes the closest to being understandable, because the
'but' is right there in the first paragraph, not (just) down in the
description of the possible replacements for X and Y.
Putting this all together, here's how I'd suggest this part of the man
page could read:
---------
-newerXY reference
Compares the timestamp X of the current file with the
timestamp Y of the reference. The reference argument is
normally the name of a file (and one of its timestamps
is used for the comparison), but it may also be a string
describing an absolute time (see description of 't' below).
The letters X and Y must be replaced with any of the
following letters:
a The access time of the file
B The birth time of the file
c The inode status change time
m The modification time
t 'reference' is interpreted as a time (rather than as
a file name); used for letter Y only
----------
An example would be a nice addition, like the two near the top of
https://collectingwisdom.com/bash-find-files-newer-than/.
--
Mike Maxwell
