diff --git a/doc/fd.1 b/doc/fd.1 index c964377..3c8b072 100644 --- a/doc/fd.1 +++ b/doc/fd.1 @@ -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" diff --git a/src/cli.rs b/src/cli.rs index 4feb4be..e9dd8f8 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -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 \