diff options
author | Andreas Metzler <ametzler@bebt.de> | 2022-01-31 00:44:05 +0100 |
---|---|---|
committer | Bernhard Voelker <mail@bernhard-voelker.de> | 2022-01-31 00:48:47 +0100 |
commit | 58747d778ea9387683b723520f04ec433cf7286f (patch) | |
tree | 225d78912cf4045127489b9ab419604f63bf008b | |
parent | 841aa66f1e447aa5db0b8800b121d0321dfa6ba2 (diff) | |
download | findutils-58747d778ea9387683b723520f04ec433cf7286f.tar.gz |
doc: improve description of 'find -delete'
* doc/find.texi (Action -delete): Improve and re-structure:
Mention that -delete is able to remove directories (if they are empty),
that failure to delete a file changes the exit code to nonzero, and
clarify better the relation between -delete, -depth and -prune.
* find/find.1 (-delete): Align with the above mentioned section in the
Texinfo manual.
Fixes https://savannah.gnu.org/bugs/?61774
Originally reported by Chris Davies in
https://bugs.debian.org/1003339
Co-authored-by: Bernhard Voelker <mail@bernhard-voelker.de>
-rw-r--r-- | NEWS | 3 | ||||
-rw-r--r-- | doc/find.texi | 32 | ||||
-rw-r--r-- | find/find.1 | 63 |
3 files changed, 61 insertions, 37 deletions
@@ -32,6 +32,9 @@ GNU findutils NEWS - User visible changes. -*- outline -*- (allout) Furthermore, both add the description of the -printf format directive '%B', for a file's birth time, and its limitations. [#61327] + The description of the -delete action has been improved and aligned among + the manual page and the Texinfo documentation. + The output of 'find --help' now reads better. The HTML online manual is using the official GNU stylesheet again. diff --git a/doc/find.texi b/doc/find.texi index cb738d12..0cc25504 100644 --- a/doc/find.texi +++ b/doc/find.texi @@ -2970,21 +2970,35 @@ with @samp{y} or @samp{Y}. Implies @samp{-t}. @deffn Action -delete Delete files or directories; true if removal succeeded. If the -removal failed, an error message is issued. +removal failed, an error message is issued and @code{find}'s exit status +will be nonzero (when it eventually exits). + +@quotation Warning +Don't forget that @code{find} evaluates the command line as an expression, +so putting @samp{-delete} first will make @code{find} try to delete everything +below the starting points you specified. +@end quotation The use of the @samp{-delete} action on the command line automatically -turns on the @samp{-depth} option (@pxref{find Expressions}). This -can be surprising if you were previously just testing with -@samp{-print}, so it is usually best to remember to use @samp{-depth} -explicitly. +turns on the @samp{-depth} option. +As in turn @samp{-depth} makes @samp{-prune} ineffective, the @samp{-delete} +action cannot usefully be combined with @samp{-prune}. + +Often, the user might want to test a @code{find} command line with @samp{-print} +prior to adding @samp{-delete} for the actual removal run. To avoid surprising +results, it is usually best to remember to use @samp{-depth} explicitly during +those earlier test runs. + +See @ref{Cleaning Up} for a deeper discussion about good use cases of the +@samp{-delete} action and those with surprising results. -If @samp{-delete} fails, @code{find}'s exit status will be nonzero -(when it eventually exits). +The @samp{-delete} action will fail to remove a directory unless it is empty. Together with the @samp{-ignore_readdir_race} option, @code{find} will ignore errors of the @samp{-delete} action in the case the file has disappeared -since the parent directory was read: it will not output an error diagnostic, and -the return code of the @samp{-delete} action will be true. +since the parent directory was read: it will not output an error diagnostic, not +change the exit code to nonzero, and the return code of the @samp{-delete} +action will be true. @end deffn @node Adding Tests diff --git a/find/find.1 b/find/find.1 index bda89575..6bad0096 100644 --- a/find/find.1 +++ b/find/find.1 @@ -1167,42 +1167,47 @@ does not check. .SS ACTIONS .IP "\-delete\fR" -Delete files; true if removal succeeded. If the removal failed, an -error message is issued. -If -.B \-delete -fails, +Delete files or directories; true if removal succeeded. +If the removal failed, an error message is issued and .BR find 's -exit status will be nonzero -(when it eventually exits). -Use of -.B \-delete -automatically turns on the -.RB ` \-depth ' -option. +exit status will be nonzero (when it eventually exits). -.BR Warnings : -Don't forget that the find command line is -evaluated as an expression, so putting +.BR Warning : +Don't forget that +.B find +evaluates the command line as an +expression, so putting .B \-delete first will make .B find try to delete everything below the starting points you specified. -When testing a -.B find -command line that you later intend to use with -.BR \-delete , -you should explicitly specify -.B \-depth -in order to avoid later surprises. Because + +The use of the .B \-delete -implies -.BR \-depth , -you cannot usefully use +action on the command line automatically turns on the +.B \-depth +option. +As in turn +.B \-depth +makes .B \-prune -and +ineffective, the .B \-delete -together. +action cannot usefully be combined with +.BR \-prune . + +Often, the user might want to test a find command line with +.B \-print +prior to adding +.B \-delete +for the actual removal run. +To avoid surprising results, it is usually best to remember to use +.B \-depth +explicitly during those earlier test runs. + +The +.B \-delete +action will fail to remove a directory unless it is empty. Together with the .B \-ignore_readdir_race @@ -1211,10 +1216,12 @@ option, will ignore errors of the .B \-delete action in the case the file has disappeared since the parent directory was -read: it will not output an error diagnostic, and the return code of the +read: it will not output an error diagnostic, not change the exit code to +nonzero, and the return code of the .B \-delete action will be true. + .IP "\-exec \fIcommand\fR ;" Execute .IR command ; |