On 4/12/19 11:02 AM, James Youngman wrote: > Sounds good, please send a patch.
What about turning the sentence around similar to how POSIX [1] does? [1] http://pubs.opengroup.org/onlinepubs/9699919799/utilities/find.html The attached proposes an improved wording. WDYT? Apart from that, the description of when -H/-L is in use with a symbolic link as reference file was wrong: find(1) always uses the mtime of the reference file (also for -anewer and -cnewer!). This is surprising to me, because I'd have expected that -anewer is comparing atime of the current file vs. atime of the reference file etc., but obviously not. This seems to be since "the beginning". Therefore, I'm 60:40 to document the current behavior than changing it. @James: WDYT? Have a nice day, Berny
>From 161b83875460da63f2d687c3277521a51d1a16ec Mon Sep 17 00:00:00 2001 From: Bernhard Voelker <m...@bernhard-voelker.de> Date: Sun, 14 Apr 2019 20:59:08 +0200 Subject: [PATCH] doc: clarify find options -newer, -anewer, -cnewer The previous description "File was modified more recently than file." was hard to understand without markup, e.g. over the phone. Furthermore, the description for symbolic links as reference file was wrong in the man page for the -anewer and -cnewer options: in fact, find(1) always uses the mtime of the reference file. * doc/find.texi (Comparing Timestamps): Improve the wording for the -anewer/-cnewer/-newer options. Use 'reference' as the argument name. Add the note from find.1 that the -H/-L options make find(1) use the data modification time of the file being referenced. * find/find.1 (-anewer,-cnewer,-newer): Improve the wording, and use 'reference' as argument name. Fix the description for -anewer/-cnewer: when -H/-L is used with a symbolic link as reference, then find always uses the mtime of that, not atime or ctime. Reported by Dan Jacobson <jida...@jidanni.org> in https://lists.gnu.org/r/bug-findutils/2019-04/msg00002.html --- doc/find.texi | 24 ++++++++++++++++-------- find/find.1 | 34 ++++++++++++++++++---------------- 2 files changed, 34 insertions(+), 24 deletions(-) diff --git a/doc/find.texi b/doc/find.texi index a573a228..262af12a 100644 --- a/doc/find.texi +++ b/doc/find.texi @@ -979,14 +979,22 @@ find /usr -newer /tmp/stamp$$ rm -f /tmp/stamp$$ @end example -@deffn Test -anewer file -@deffnx Test -cnewer file -@deffnx Test -newer file -True if the file was last accessed (or its status changed, or it was -modified) more recently than @var{file} was modified. These tests are -affected by @samp{-follow} only if @samp{-follow} comes before them on -the command line. @xref{Symbolic Links}, for more information on -@samp{-follow}. As an example, to list any files modified since +@deffn Test -anewer reference +@deffnx Test -cnewer reference +@deffnx Test -newer reference +True if the time of the last access (or status change or data modification) +of the current file is more recent than that of the last data modification +of the @var{reference} file. + +If @var{reference} is a symbolic link and the @samp{-H} option or the @samp{-L} +option is in effect, then the time of the last data modification of the file +it points to is always used. + +These tests are affected by @samp{-follow} only if @samp{-follow} comes before +them on the command line. @xref{Symbolic Links}, for more information on +@samp{-follow}. + +As an example, to list any files modified since @file{/bin/sh} was last modified: @example diff --git a/find/find.1 b/find/find.1 index abf70add..04fbbd7d 100644 --- a/find/find.1 +++ b/find/find.1 @@ -591,14 +591,15 @@ for exactly .IP "\-amin \fIn\fR" File was last accessed \fIn\fR minutes ago. -.IP "\-anewer \fIfile\fR" -File was last accessed more recently than \fIfile\fR was modified. If -\fIfile\fR is a symbolic link and the +.IP "\-anewer \fIreference\fR" +Time of the last access of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the .B \-H option or the .B \-L -option is in effect, the access time of the file it points to is -always used. +option is in effect, then the time of the last data modification of the file +it points to is always used. .IP "\-atime \fIn\fR" File was last accessed @@ -615,14 +616,15 @@ days ago. .IP "\-cmin \fIn\fR" File's status was last changed \fIn\fR minutes ago. -.IP "\-cnewer \fIfile\fR" -File's status was last changed more recently than \fIfile\fR was -modified. If \fIfile\fR is a symbolic link and the +.IP "\-cnewer \fIreference\fR" +Time of the last status change of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the .B \-H option or the .B \-L -option is in effect, the status-change time of the file it points -to is always used. +option is in effect, then the time of the last data modification of the file +it points to is always used. .IP "\-ctime \fIn\fR" File's status was last changed @@ -771,15 +773,15 @@ library function. Don't forget to enclose the pattern in quotes in order to protect it from expansion by the shell. -.IP "\-newer \fIfile\fR" -File was modified more recently than -.IR file . -If \fIfile\fR is a symbolic link and the +.IP "\-newer \fIreference\fR" +Time of the last data modification of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the .B \-H option or the .B \-L -option is in effect, the -modification time of the file it points to is always used. +option is in effect, then the time of the last data modification of the file +it points to is always used. .IP "\-newerXY \fIreference\fR" Succeeds if timestamp \fIX\fR of the file being considered is newer -- 2.21.0
