PR-URL: #631
Credit: @JamBalaya56562
Close: #631
Reviewed-by: @isaacs

Updated the traversal function documentation to maintain consistency in punctuation.

PR-URL: #617
Credit: @shaymolcho
Close: #617
Reviewed-by: @

PR-URL: #613
Credit: @spageektti
Close: #613
Reviewed-by: @isaacs

PR-URL: #609
Credit: @jedwards1211
Close: #609
Reviewed-by: @isaacs

PR-URL: #591
Credit: @danielbayley
Close: #591
Reviewed-by: @6555lee

This resolves GHSA-5j98-mcp5-4vw2, with a minimum of breaking changes
for as many users as possible.

First, 'shell: true' is only used on the subprocess if set explicitly by
the user in the command line, and only if it is not a shell where this
can be avoided safely without any reduction in functionality. In this
case, a deprecation warning is printed, telling them that it's unsafe,
and that it will be removed in a future version.

Second, as the only reason for such behavior was to be able to have
commands that include positional arguments in the --cmd/-c value, a new
option --cmd-arg/-g is added, so that users can pass positional
arguments ahead of the file matches, in a way that does not rely on
shell expansion.

Lastly, as a general quality of life improvement which should keep this
entire issue from even mildly inconveniencing most users, when the
command contains space or quote characters (and thus, is likely to
contain positional arguments), AND the `SHELL` environment variable
refers to a shell program with a known way to pass positional arguments
to the child process, then we use that technique, again avoiding shell
expansion of the resolved file paths (or the user command itself). This
applies to sh, ksh, bash, zsh, and fish.

This potentially WILL break workflows, and require updating, if they are
relying on the automatic shell expansion, in systems other than the
known posix shells referenced above. The only likely case that anyone
will thus encounter, is running commands on Windows. While there DOES
appear to be a way to use a similar trick on Windows, but there are so
many more edge cases, I'm not confident I can do so without introducing
more bugs (and potentially more security issues).

If users find that this breakage is too severe, the fix will be to roll
out a subsequent release that turns `--shell` on by default on Windows,
if the command contains space or quote characters.

Nevertheless, v12 of this library will *not* contain a `--shell` option,
and will not run child processes in `shell:true` mode under any
circumstances.

Note: this was simultaneously and independently reported by two
researchers. My sincerest thanks for their time and attention.

Reported-by: @Gyde04 "Babajide Emmanuel Fakile"
Reported-by: @aisle-research "Pavel Kohout (Aisle Research)"
Fix: GHSA-5j98-mcp5-4vw2
Fix: CVE-2025-64756