docs(exec): clarify command ordering and output grouping for -x/--exec

This commit is contained in:
pederbe
2026-09-16 00:43:22 -06:00
committed by Thayne McCombs
parent 0e01c8ce19
commit 468cd4371a
2 changed files with 12 additions and 8 deletions
Vendored
+6 -6
View File
@@ -448,13 +448,13 @@ Note that all subsequent positional arguments are considered to be arguments to
It is therefore recommended to place the \-x/\-\-exec option last. Alternatively, you can supply
a ';' argument to end the argument list and continue with more fd options.
Most shells require ';' to be escaped: '\\;'.
This option can be specified multiple times, in which case all commands are run for each
file found, in the order they are provided. In that case, you must supply a ';' argument for
all but the last commands.
This option can be specified multiple times. Commands for the same search result run sequentially
in the order they are given. In that case, you must supply a ';' argument for all but the last command.
When running in parallel, fd buffers command output and prints it together for each search result,
without interleaving it with command output for other results.
If parallelism is enabled, the order commands will be executed in is non-deterministic. And even with
--threads=1, the order is determined by the operating system and may not be what you expect. Thus, it is
recommended that you don't rely on any ordering of the results.
The order in which different search results are processed and their output is printed is not
guaranteed, even with --threads=1.
Before executing the command, any placeholder patterns in the command are replaced with the
corresponding values for the current file. The same placeholders are used as in the "\-\-format"
+6 -2
View File
@@ -895,10 +895,14 @@ impl clap::Args for Exec {
.help("Execute a command for each search result")
.long_help(
"Execute a command for each search result in parallel (use --threads=1 for sequential command execution). \
There is no guarantee of the order commands are executed in, and the order should not be depended upon. \
The order in which different search results are processed and their output is printed is not guaranteed, even with --threads=1. \
All positional arguments following --exec are considered to be arguments to the command - not to fd. \
It is therefore recommended to place the '-x'/'--exec' option last. \
Use '\\;' to terminate the command template if you need to continue passing fd arguments afterwards.\n\
Use '\\;' to terminate the command template if you need to continue passing fd arguments afterwards.\n\n\
This option can be specified multiple times. Commands for the same search result run sequentially in the order they are given. \
Terminate each command except the last with '\\;'. \
When running in parallel, fd buffers command output and prints it together for each search result, \
without interleaving it with command output for other results.\n\n\
The following placeholders are substituted before the command is executed:\n \
'{}': path (of the current search result)\n \
'{/}': basename\n \