Merge pull request #1924 from liruiluo/docs/clarify-exec-arg-boundary

docs: clarify how --exec consumes positional arguments

Author: tmccombs

README.md

@@ -189,6 +189,12 @@ fd -e h -e cpp -x clang-format -i
 Note how the `-i` option to `clang-format` can be passed as a separate argument. This is why
 we put the `-x` option last.
 
+Any positional arguments after `-x` belong to the command template, not to `fd` itself. If you
+also want to pass a pattern or search path, put `-x` last:
+``` bash
+fd pattern path -x echo
+```
+
 Find all `test_*.py` files and open them in your favorite editor:
 ``` bash
 fd -g 'test_*.py' -X vim
@@ -228,6 +234,9 @@ fd -tf -x md5sum > file_checksums.txt
 The `-x` and `-X` options take a *command template* as a series of arguments (instead of a single string).
 If you want to add additional options to `fd` after the command template, you can terminate it with a `\;`.
 
+For example, `fd -x echo \; pattern path` treats `pattern path` as `fd` arguments instead of
+passing them to `echo`. In practice, it is often clearer to write `fd pattern path -x echo`.
+
 The syntax for generating commands is similar to that of [GNU Parallel](https://www.gnu.org/software/parallel/):
 
 - `{}`: A placeholder token that will be replaced with the path of the search result

src/cli.rs

@@ -872,7 +872,8 @@ impl clap::Args for Exec {
                     "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. \
                      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.\n\
+                     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\
                      The following placeholders are substituted before the command is executed:\n  \
                        '{}':   path (of the current search result)\n  \
                        '{/}':  basename\n  \
@@ -887,6 +888,8 @@ impl clap::Args for Exec {
                            fd -e zip -x unzip\n\n  \
                        - find *.h and *.cpp files and run \"clang-format -i ..\" for each of them:\n\n      \
                            fd -e h -e cpp -x clang-format -i\n\n  \
+                       - search within `src/` and echo each match (place `-x` last):\n\n      \
+                           fd . src -x echo\n\n  \
                        - Convert all *.jpg files to *.png files:\n\n      \
                            fd -e jpg -x convert {} {.}.png\
                     ",