Consider .exe shims instead of .bat — the documented Git Bash setup silently loses arguments containing | & > ^

[joshdaugherty]

Suggestion: ship the bin\ shims as .exe launchers rather than .bat files. That would spare Git Bash and PowerShell users a mostly silent argument-corruption problem that the Git Bash setup in the docs leads into.

Posting this as a discussion rather than an issue for two reasons: your config.yml points feature requests here, and the root cause is not in Herd's code. I checked that carefully and want to say so up front, so nobody goes looking for it in the shims.

What users hit

The Git Bash section of the Windows docs says "If you want to use the Herd binaries in Git Bash, add these aliases to your .bash_profile:"

alias php="php.bat"
alias herd="herd.bat"
alias laravel="laravel.bat"
alias composer="composer.bat"

With that setup, an argument containing |, &, >, or ^ does not reach PHP intact. Two of the four cases stop the command before PHP runs at all; the other two change the value and give no error.

Argument	What happens	Any error?
A|B	command stops, 'B' is not recognized as an internal or external command	yes
A&B	command stops, 'B' is not recognized as an internal or external command	yes
A>B	argument arrives empty, and a file named B is created in the current folder	no
A^B	argument arrives as AB	no

Where the problem actually is

A .bat file can only be run by cmd.exe, so Git Bash starts cmd.exe /c to run it. When Git Bash builds that command line, it does not quote the arguments, so cmd reads these characters as its own syntax.

You can see the unquoted hand-off with a .bat containing echo %CMDCMDLINE%. Run from Git Bash with a plain argument — plain, because with one of the four characters the command stops before it can echo anything:

RAW: C:\WINDOWS\system32\cmd.exe /c C:\tmp\raw.bat AplainB

No quotes around AplainB. Run the same file from cmd with quotes and all four characters come through:

["A|B"]   ["A&B"]   ["A>B"]   ["A^B"]

(%1 keeps the quotes, which is normal; %~1 strips them. The point is that cmd did not treat the characters as syntax.)

I ran controls to narrow it down:

• Not %* — a .bat using %1 fails the same way.
• Not Herd's shims — a one-line .bat I wrote myself, with no connection to Herd, fails identically.
• Not cmd.exe — given a properly quoted command line, cmd passes all four through.
• Not only Git Bash — PowerShell loses all four as well, though it fails differently: A&B arrives truncated as A rather than erroring.

So this comes from how non-cmd shells build the command line they hand to cmd.exe. Herd cannot fix that part.

Why raise it here

Herd is where users run into it, because the Git Bash setup in the docs routes php through a .bat. Nothing on that page suggests arguments might be changed or dropped.

It is also slow to diagnose. In my case:

php vendor/bin/pest tests/Feature --filter='SuiteA|SuiteB' --parallel

The | ended the command line early, so the test run exited after 0 seconds with no output and no summary. My script looked for a Tests: line, found none, and that read as "nothing to report" rather than "the command never ran". It took a few hours to find. A | in a --filter is ordinary usage.

Quoting differently does not help. The argument is already correctly quoted in bash. I tried a cmd-style caret escape (A^|B), double quotes, and a backslash escape, and all still fail.

Options

1. Ship .exe launchers instead of .bat files. An .exe receives arguments directly, with no cmd.exe in between, so the problem does not arise whichever shell called it. This is the thorough fix and it covers every shim.
2. Put the active PHP version's folder on PATH, so php.exe resolves directly. This helps anyone calling a bare php, though not someone who has set up the documented alias, since that names php.bat explicitly.
3. Add a note to the Git Bash docs page. The > and ^ cases produce no error and no clue, so a short warning would save the guesswork.

The same applies to the other shims. composer.bat is php "%~dp0composer.phar" %* and laravel.bat is php "%~dp0laravel.phar" %*, so those go through php.bat too; expose.bat, forge.bat, and herd.bat are .bat files and take the same path through cmd.

Reproducing it

Windows 11 Pro build 26200, AMD64, Herd 1.29.0, PHP 8.4.20. From Git Bash (change php84 to your installed version):

# Stops with an error
"$HOME/.config/herd/bin/php.bat" -r 'echo $argv[1] ?? "(none)";' 'A|B'
# -> 'B' is not recognized as an internal or external command,

# No error, wrong value
"$HOME/.config/herd/bin/php.bat" -r 'echo $argv[1] ?? "(none)";' 'A^B'
# -> AB          (expected A^B)

"$HOME/.config/herd/bin/php.bat" -r 'echo $argv[1] ?? "(none)";' 'A>B'
# -> (none)      (expected A>B), and `ls B` now shows a new file

# Calling php.exe directly — all four come through
"$HOME/.config/herd/bin/php84/php.exe" -r 'echo $argv[1] ?? "(none)";' 'A|B'
# -> A|B

That last line is the point: a real .exe already handles all four characters today.

Workaround, for anyone who finds this

Call the real php.exe instead of the .bat. php.bat names the binary it would have run, so the path can be read out of it:

# php.bat contains:  @echo off / "C:\...\phpNN\php.exe" %*
bat="$HOME/.config/herd/bin/php.bat"
exe=""
if [ -r "$bat" ]; then
    win=$(tr -d '\r' < "$bat" | grep -F '.exe' | head -1 | cut -d'"' -f2)
    [ -n "$win" ] && exe=$(cygpath -u "$win")
fi
# Fall back to a known path if php.bat could not be read
[ -n "$exe" ] && [ -x "$exe" ] || exe="$HOME/.config/herd/bin/php84/php.exe"
"$exe" "$@"

herd use rewrites php.bat to point at the newly chosen version, so re-reading it on each call keeps this in step with version switches.

The fallback is worth keeping. herd use replaces php.bat rather than editing it in place, and I managed to make that replacement fail by reading the file at the moment of a switch, which left php.bat missing until I put it back. That was my own doing rather than something Herd does on its own, but a fallback costs nothing.