summaryrefslogtreecommitdiff
path: root/doc/find.texi
Commit message (Collapse)AuthorAgeFilesLines
* doc: describe history of find, xargs and locate.HEADmasterJames Youngman2023-03-181-12/+85
|
* doc: use "end-of-file" with hyphenation consistentlyBernhard Voelker2023-02-131-6/+6
| | | | | | | * cfg.mk (sc_prohibit_unhyphenated_eof): Add syntax-check rule. * doc/find.texi: Change "end of file" to "end-of-file" in several places. * xargs/xargs.1: Likewise. * xargs/xargs.c (eof_str): Change comment to adhere to the new rule.
* doc: improve description about when xargs stops processingBernhard Voelker2023-02-131-5/+7
| | | | | | | | | * doc/find.texi (Multiple Files): Clarify better that xargs will stop when reading the EOF marker string specified with the --eof option, or when a launched command exists with status 255. Switch the two termination conditions to reflect the behavior. Fixes RT #1912852.
* maint: update copyright year number rangesBernhard Voelker2023-01-011-1/+1
| | | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. * tests/sample-test: Adjust to use the single most recent year. * All other files: Update copyright years via the above make run.
* maint: avoid unportable 'grep -q'Bernhard Voelker2023-01-011-1/+1
| | | | | | | | | | | | | | | The upcoming gnulib update comes with the new syntax-check named 'sc_unportable_grep_q': maint.mk: unportable 'grep -q', use >/dev/null instead make: *** [maint.mk:1377: sc_unportable_grep_q] Error 1 Fix offending places. * cfg.mk (sc_prohibit_test_calls_print_ver_with_irrelevant_argument): Replace unportable '-q' by redirecting grep output to /dev/null. * doc/find.texi (node Adding Tests): Likewise. * init.cfg (find_emits_warnings_): Likewise.
* doc: remove redundant @deffnx for option -files0-from from manualAntonio Diaz Diaz2022-11-161-1/+0
| | | | | | | * doc/find.texi (section Starting points): Remove @deffnx; the @deffn above it is sufficient. Copyright-paperwork-exempt: Yes
* doc: fix formatting typo in Texinfo manualBernhard Voelker2022-04-241-1/+1
| | | | * doc/find.texi (LC_COLLATE): Change man-style `\-name' to @samp{-name}.
* doc: improve description of 'find -delete'Andreas Metzler2022-01-311-9/+23
| | | | | | | | | | | | | | | * 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>
* maint: update copyright year number rangesBernhard Voelker2022-01-021-1/+1
| | | | | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. The format of the copyright year number range in Texinfo files is "YEAR1--YEAR2" now, i.e., with 2x '-'. * tests/sample-test: Adjust to use the single most recent year. * All other files: Update copyright years via the above make run.
* doc: fix 'xargs --open-tty' exampleBernhard Voelker2021-12-311-1/+1
| | | | | | | | | doc/find.texi (xargs options): Change 'grep -lz' to 'grep -lZ' as input for 'xargs -0o' as only the latter will write a NUL after each file name. Add -n1 to the xargs call. Reported by Robin A. Meade in https://savannah.gnu.org/bugs/?61341
* doc: add description for birth time in 'find -printf' formatBernhard Voelker2021-11-281-2/+14
| | | | | | | | | | | | | | find(1) supports both searching for and printing of the birth time of a file since 2007, but the documenation lacked the description for the latter. * doc/find.texi (node Time Directives): Add item for %B. (node Time Formats): Mention that the described formats also apply to the %B directive. * find/find.1 (-printf format): Add description of %B. * NEWS (Documentation Changes): Mention the change. Fixes https://savannah.gnu.org/bugs/?61327
* find: allow -files0-from input file to be emptyBernhard Voelker2021-11-271-2/+6
| | | | | | | | | | | | | Do no longer output an error diagnostic when the input file of the -files0-from option is empty. * find/ftsfind.c (process_all_startpoints): Remove error diagnostic. * doc/find.texi (node Starting points): Adjust documentation. * find/find.1: Likewise. * tests/find/files0-from.sh: Adjust test. Suggested by Stephane Chazelas in https://savannah.gnu.org/bugs/?60383#comment11
* doc: fix typo in "Full Name Patterns"Renaud Pacalet2021-10-101-1/+1
| | | | | | | | * doc/find.texi (subsection Full Name Patterns): Change 2nd '-wholename' to '-iwholename' to complete the enumeration of related options. Fixes https://savannah.gnu.org/bugs/?61303 Copyright-paperwork-exempt: Yes
* Fix Savannah bug 60823: unescaped `@' in find.texi code example.James Youngman2021-06-251-1/+1
|
* find: add -files0-from optionBernhard Voelker2021-05-081-0/+89
| | | | | | | | | | | | | | | | | | | | | | | | * bootstrap.conf (gnulib_modules): Add argv-iter and same-inode. * find/defs.h (struct options): Add files0_from and ok_prompt_stdin members. * find/ftsfind.c (argv-iter.h, same-inode.h, xalloc.h): Add #include for gnulib headers. (process_all_startpoints): Change loop over starting point arguments to a loop using the argv_iter gnulib module. * find/parser.c (parse_table): Add option. (parse_files0_from): Declare and define function. (insert_exec_ok): Set options flag ok_prompt_stdin to true for the -ok and -okdir action. * find/util.c (usage): Add new option. (set_option_defaults): Initialize new struct members. * doc/find.texi (node Starting points): Add new section describing the regular processing of starting points, and that with the new option. Also mention in the description of -ok and -okdir that they conflict with the new option. * find/find.1: Document the new option here as well. * tests/find/files0-from.sh: Add test. * tests/local.mk (all_tests): Reference it. * NEWS (New features in find): Mention the new option.
* doc: show environment variables in a consistent styleBernhard Voelker2021-01-311-31/+31
| | | | | | | | | | | | | In manual pages, set environment variables in bold; in the texinfo manual, use the @env{} macro consistently. Additionally, talk about PATH instead of $PATH in all manuals. * doc/find.texi: Do the above. * find/find.1: Likewise. * NEWS (Documentation Changes): Mention the fix. Reported by Helge Kreutzmann in https://savannah.gnu.org/bugs/?59963
* xargs: warn on conflicting options -L, -I, -nAndreas Metzler2021-01-071-0/+28
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * xargs/xargs.c (warn_mutually_exclusive): Add function to output the new warning diagnostic. (main): Call the above new function in order to show a warning message if conflicting options (-L -l -I -i -n) are specified. * xargs/xargs.1: Explicitly document the fact that -L -l -I -i -n options are mutually exclusive and how xargs behaves when more than one of these options are specified. * doc/find.texi (node Conflicting xargs options): Likewise, add this section with examples. * xargs/testsuite/config/unix.exp (xargs_start): Replace the full path of the xargs executable in the stderr output file by its basename. * xargs/testsuite/xargs.gnu/P3-n1-IARG.xe: Add file containing the expected output with the new warning diagnostic. * xargs/testsuite/xargs.posix/L2-n2.xe: Likewise. * xargs/testsuite/xargs.posix/rc-123.xe: Likewise. * xargs/testsuite/xargs.sysv/l1n4.xe: Likewise. * xargs/testsuite/xargs/testsuite/xargs.gnu/P3-n1-IARG.exp: Ensure the error diagnostic is in C locale to avoid false positives in other locales. * xargs/testsuite/xargs.posix/L2-n2.exp: Likewise. * xargs/testsuite/xargs.posix/rc-123.exp: Likewise. * xargs/testsuite/xargs.sysv/l1n4.exp: Likewise. * tests/xargs/conflicting_opts.sh: Add test coverage for combinations of the mutually exclusive options -I -L and -n. * xargs/testsuite/Makefile.am (EXTRA_DIST_EXP): Reference the new tests. (EXTRA_DIST_XO): Reference the new *.xo files. (EXTRA_DIST_XE): Reference the new *.xe files. * NEWS (Improvements): Mention the change. Co-authored-by: Bernhard Voelker <mail@bernhard-voelker.de> Discussed at https://savannah.gnu.org/bugs/?52137 Duplicate of https://savannah.gnu.org/bugs/?58156
* doc: avoid overfull \hbox issues in find.texiBernhard Voelker2021-01-071-4/+6
| | | | | | | | | | "Overfull \hbox" results lines exceeding the page width, and therefore may not even be readable. At least they are ugly. * doc/find.texi (node O_NOFOLLOW): Break long example lines into the next lines. While at it, update the version in that example to 4.8.0 (in good faith we'll have it in 2021), because we shouldn't have a "*-git" version there.
* maint: update copyright year number rangesBernhard Voelker2021-01-021-1/+1
| | | | | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. The format of the copyright year number range in Texinfo files is "YEAR1--YEAR2" now, i.e., with 2x '-'. * tests/sample-test: Likewise, here to avoid starting a year number range. * All other files: Update copyright years via the above make run.
* doc: minor grammar change about a change in the pastBernhard Voelker2020-12-301-2/+2
| | | | | | | | | | | In the description of -name patterns matching "hidden" files, i.e., those beginning with a dot, avoid talking in the future. The change was back in version 4.2.2. Maybe we should drop this hint about historic behavior at all. * doc/find.texi (Base Name Patterns): Remove the word "will". * find/find.1 (.SH STANDARDS CONFORMANCE): Likewise. (.SH HISTORY): Likewise.
* doc: avoid starting sentences with an optionBernhard Voelker2020-12-301-2/+2
| | | | | | | | | | | | | | A sentence starting with an option looks odd: "... starting-points. -maxdepth 0 means only apply ..." * doc/find.texi (-maxdepth): Add "Using " to avoid having an option at the start of the sentence. (-mindepth): Likewise. * find/find.1: Likewise. While at it, mark the whitespace as non-breakable via '\ '. Reported by Helge Kreutzmann in https://savannah.gnu.org/bugs/?59745
* doc: relate -anewer, -cnewer, and -newer to their -newerXY equivalentsBernhard Voelker2020-11-221-0/+2
| | | | | | | * doc/find.texi (Comparing Timestamps): Clarify that the above options are equivalent to the options -neweram, -newercm and -newermm. Suggested by Reuben Thomas.
* doc: avoid misunderstanding of '-printf %Ak' descriptionKamil Dudka2020-10-071-4/+7
| | | | | | | | | | | * find/find.1 (-printf): Make it clear that the list of conversion specification characters of '%Ak' is incomplete; refer to the strftime() documentation. While at it, document the F conversion character which yields 'yyyy-mm-dd'. * doc/find.texi (Time Formats): Likewise. * NEWS: Mention the improvement. Suggested in https://bugzilla.redhat.com/1882695
* doc: add examples for -maxdepth, -mindepthBernhard Voelker2020-08-141-0/+19
| | | | | | | | * doc/find.texi (-maxdepth): Add examples. (-mindepth): Reference them. Suggested by 積丹尼 Dan Jacobson <jidanni@jidanni.org> in https://lists.gnu.org/r/bug-findutils/2020-07/msg00006.html
* doc: clarify that 'find -perm +MODE' is unrelated to umaskBernhard Voelker2020-08-141-0/+4
| | | | | | | | * doc/find.texi (Test -perm pmode): Do the above. * NEWS: Mention the change. Reported by Mohamed Akram in https://sv.gnu.org/bugs/?58654
* doc: enhance description of tests accepting numeric arguments in find.1Bernhard Voelker2020-08-141-22/+23
| | | | | | | | | | | | | * find/find.1 (TESTS): Improve the description of tests accepting a numeric argument that they match "less than, more than or exactly" the given 'n', thus helping the user to remind to use '-n', '+n' or a bare 'n' (as decribed at the top). * doc/find.texi (section find Expressions): Move section from chapter "Introduction" to "Finding Files". The description about the general syntax of a find expression fits more naturally there, including the already existing part about numeric arguments. * NEWS: Mention the change. Suggested in https://sv.gnu.org/bugs/?57025 .
* doc: display version of the GNU findutils on the title pageBernhard Voelker2020-08-141-13/+9
| | | | | | | | | | | | | The first page of the Texinfo documentation should display the package version the documentation corresponds to. Also change the title from "Finding Files" to "GNU Findutils ..." to better reflect the package name. These changes align the documentation better with that of other GNU packages like e.g. grep. * doc/find.texi: Do the above. Furthermore, display the VERSION also in the first sentence after the @direntry list. While at it, enclose the FDL licence text in a @quotation block. * doc/find-maint.texi: Likewise.
* doc: change "allows to <verb>" to "allows <verb>ing"Bernhard Voelker2020-08-131-13/+13
| | | | | | * doc/find.texi: Use gerund after "allows". As a side effect, this also avoids passive voice in some cases; active voice is usually clearer.
* doc: modernize example list of filesystem types for -fstypeBernhard Voelker2020-08-131-1/+1
| | | | * doc/find.texi (-fstype): Mention more common types.
* doc: remove fts from configuration chapterBernhard Voelker2020-07-201-16/+0
| | | | | | The corresponding configure option was removed with commit 42a28b0dfb. * doc/find.texi (node fts): Remove section.
* doc: improve section 'Hard links' and fix 'find -L -samefile' descriptionBernhard Voelker2020-06-211-39/+54
| | | | | | | | | | | | | | * doc/find.texi (Hard links): Clarify that 'find -L -samefile FILE' returns both hard links and symbolic links to FILE, and why. Further attempt to improve the wording of the whole section by avoiding wording like "you can ...", and instead describing more how find works and behaves for the -samefile, -inum and -links options. Especially mention that -inum potentially returns files with the given inode number but yet are no hard links per definition: this happens if they are on a different file system, i.e., if they have a different device number. Fixes https://sv.gnu.org/bugs/?58458
* doc: prefer https:// over http:// in more placesBernhard Voelker2020-03-151-1/+1
| | | | | | | | | Use HTTPS for GNU, FSF, OpenGroup and Google URLs. * build-aux/update-online-manual.sh: Switch to HTTPS. * doc/find.texi (node Further Reading on Security): Likewise. * lib/buildcmd.c: Likewise in a comment. * NEWS: Likewise, and shorten a debbugs URL.
* doc: fix typoPeter Frost2020-02-141-1/+1
| | | | | | | | | * doc/find.texi (Name Directives): s/eample/example/ * find/find.1 (EXAMPLES): Likewise. Fixes https://sv.gnu.org/bugs/?57807 Copyright-paperwork-exempt: Yes
* maint: update copyright year number rangesBernhard Voelker2020-01-011-1/+1
| | | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. * tests/sample-test: Likewise, here to avoid starting a year number range. * All other files: Update copyright years via the above make run.
* doc: use "symbolic link" instead of "symlink" consistentlyBernhard Voelker2019-11-131-7/+7
| | | | | | | | | | | * doc/find.texi (-printf): Change the shorter term "symlink" to "symbolic link" for consistency with the rest of the Texinfo manual and the man page. (%Y): Likewise. * find/find.1 (%Y): Likewise. Suggested by 積丹尼 Dan Jacobson <jidanni@jidanni.org> in: https://lists.gnu.org/r/bug-findutils/2019-11/msg00003.html
* find: Clarify description of %f and %h.James Youngman2019-09-011-6/+23
| | | | | | | Fix https://savannah.gnu.org/bugs/index.php?35253 * doc/find.texi (Name Directives): Clarify description of %f and %h. * find/find.1 (-printf): Likewise. * NEWS: mention this change.
* Fix Savannah bug 54730: additional examples for -quit.James Youngman2019-09-011-5/+12
| | | | | | | | | * doc/find.texi (-quit): add another example. * find/find.1 (-quit): add another example. (-exec): Point out that -exec my-command {} + -quit may not result in my-command being run. (EXAMPLES): add an example for -quit. * NEWS: mention this change.
* doc: fix bug #56142 by specifying which actions inhibit the default -printJames Youngman2019-05-041-4/+9
| | | | | | * find/find.1: specify which actions inhibit the default -print action. * doc/find.texi (find Expressions): Likewise.
* doc: clarify find options -newer, -anewer, -cnewerBernhard Voelker2019-04-141-8/+16
| | | | | | | | | | | | | | | | | | | | | | 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 <jidanni@jidanni.org> in https://lists.gnu.org/r/bug-findutils/2019-04/msg00002.html
* maint: update copyright year number rangesBernhard Voelker2019-01-041-1/+1
| | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. * All other files: Update copyright years via the above make run.
* doc: fix grammar issue in texinfo manualBernhard Voelker2018-11-141-1/+1
| | | | | | * doc/find.texi (Systems without O_NOFOLLOW): Remove superfluous 'the'. Reported by Martin Castillo in https://sv.gnu.org/bugs/?55022
* find: add '-D all' to enable all debug flagsBernhard Voelker2018-11-021-3/+7
| | | | | | | | | | * find/defs.h (DebugOption): Add DebugAll, which includes all other debug options but DebugHelp. * find/util.c (debugassoc): Add an entry for DebugAll, and move DebugHelp to the end. * doc/find.texi (node Debug Options): Document the new option. * find/find.1: Likewise. * NEWS (Improvements): Likewise.
* doc: use portable 'tail' call in texinfo exampleBernhard Voelker2018-11-021-1/+1
| | | | | * doc/find.texi (node Updating A Timestamp File): Use more portable 'tail -n1' instead of the deprecated form 'tail -1'.
* doc: fix typo in 'xargs -l' examples in texinfo manualBernhard Voelker2018-10-181-3/+3
| | | | | | | | * doc/find.texi (node Controlling Parallelism): Change from 'xargs -1' (minus one) to 'xargs -l' (minus El) in three places. Reported by Ahmad ElKomey in https://sv.gnu.org/bugs/index.php?54859
* doc: fix the examples of the -perm option in the texinfo documentationBernhard Voelker2018-10-151-3/+3
| | | | | | | | | | * doc/find.texi (Mode Bits): Move the misplaced '-perm -g+w,o+w' example up to the '-perm -022' example to where it belongs. The former got accidentally separated from the latter in commit 7ade936bc2c4: the patch proposed in https://sv.gnu.org/bugs/?14619 was applied in the wrong place. * NEWS (Bug fixes): Mention the fix. Reported by Ahmad ElKomey in https://sv.gnu.org/bugs/?54838
* doc: don't mention indirect blocks. Clarify how -size is measured.James Youngman2018-09-231-3/+3
| | | | This fixes Savannah bug 36763.
* doc: document -printf %Y output consistentlyBernhard Voelker2018-07-241-0/+3
| | | | | | * doc/find.texi (node Location Directives): Mention 'L' and '?' as well. * find/find.1 (%Y): Mention '?'. * NEWS (Documentation Changes): Mention the fix.
* find: make -delete honour the -ignore_readdir_race optionBernhard Voelker2018-03-141-1/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | * find/pred.c (pred_delete): Return true when the -ignore_readdir_race option is active and unlinkat() came back with ENOENT. * doc/find.texi (Option -ignore_readdir_race): Document the change. (Action -delete): Likewise. * find/find.1: Likewise. * NEWS (Bug Fixes): Mention the fix. For now, it seems a bit hard to add a proper test for this, so the following shell snippet demonstrates the race: $ seq 10 | xargs touch $ env time -f 'find exit status: %x\nfind time: %e' \ find -ignore_readdir_race -type f \ -delete \ -exec sh -c 'sleep $(basename {})' \; \ -printf 'find deleted: %p\n' \ & \ sleep 20; \ seq 10 | xargs rm -fv; \ wait $! Reported by Alexander Golubev in https://savannah.gnu.org/bugs/?52981
* maint: update copyright year number rangesBernhard Voelker2018-01-011-1/+1
| | | | | | | Run 'make update-copyright'. * lib/regexprops.c (copying): Update the year number manually. * All other files: Update copyright years via the above make run.
* regexprops: fix dangling reference to the `ed' regular expression dialect.James Youngman2017-11-141-2/+5
| | | | | | | | | | | | | | * lib/regextype.c (regex_map): Permute the entries to list POSIX dialects before other ones, so that we don't end up with a dangling reference to `ed' regular expressions when context=findutils. Remove trailing white space from the output. * doc/regexprops.texi: Regenerate this file, so that we no longer have a dangling reference to the `ed' dialect. * doc/find.texi (Regular Expressions): Point out the difference between Emacs regular expressions and findutils regular expressions: in findutils "." will match newline. * find/find.1: Likewise. * locate/locate.1: Likewise. Also document the --regextype option.
View Lorry Controller Status