Skip to content

Stop wrapping commands in cmd.exe on Windows - #898

Merged
sds merged 3 commits into
sds:mainfrom
bwilde-castle:fix-windows-cmd-exe-arg-corruption
Oct 15, 2026
Merged

sds merged 3 commits into
sds:mainfrom
bwilde-castle:fix-windows-cmd-exe-arg-corruption

Conversation

@bwilde-castle

Copy link
Copy Markdown
Contributor

An attempt at Issue #847. This isn't a corner case: pre-commit and commit-msg hooks both stash unstaged changes before running hooks, by default, so any Windows user doing a partial commit (staging some but not all changes) hits this — hooks fail outright with error: unknown switch '0' instead of running at all.

I commented on the issue a couple of months ago; I've since tested this fix end to end on Windows 11 / Ruby 3.3, and while the suggestion still looks right, my description of the cause back then was off. Here's what I think is actually going on.

The problem

win32_prepare_args escapes metacharacters per argument, then joins everything into one string behind cmd.exe /c:

%w[cmd.exe /c] + [args.join(' ')]

The escaping doesn't seem to be what breaks; the join is. It collapses the command into a single argv element, and childprocess 5.x on Windows is a thin shim over Process.spawn, which sees the embedded spaces, wraps the element in quotes, and backslash-escapes the quotes already inside it. cmd.exe strips the outer pair, and the child's C runtime then reads the surviving \" as a literal quote rather than a delimiter — so the argument re-splits on whitespace.

With the pre-commit stash message (Overcommit: Stash of repo state before hook run at 2024-04-10 12:34:56 -0700), git stash save receives the UTC offset as a switch of its own and aborts with error: unknown switch '0'. On a throwaway repo I get exit 129 with that message on main, and exit 0 with the message intact on this branch.

I couldn't find an escaping scheme that fixes this while keeping the wrapper: inside double quotes & | < > ( ) are already literal, %VAR% still expands and can't be caret-escaped, and carets inside quotes reach the child as literal carets.

The change

Drop the wrapper and hand the argument vector to ChildProcess.build unmodified. Process.spawn appears to do the command lookup the wrapper was standing in for — .bat, .cmd, extensionless RubyGems shims and PATHEXT names all launched fine in my testing, including the real bundle.bat — and arguments stay atomic because no shell re-parses them.

Both call sites were already gated on OS.windows?, so this is Windows-only in effect; macOS and Linux behaviour is unchanged.

That Process.spawn backend arrived in childprocess 5.0.0, which replaced the Windows FFI layer. Before that, Windows used raw CreateProcess, which does no PATHEXT resolution, so I've raised the gemspec floor from >= 0.6.3 to >= 5.0.0. I realise that's the debatable part and entirely your call — for context, the < 6 ceiling was already there, 5.0.0 is from 2022, this repo's Gemfile.lock resolves to 5.x, and 4.1.0/5.0.0/5.1.0 all declare required_ruby_version >= 2.4.0.

One wrinkle: mklink and dir (used by FileUtils for symlinks) are cmd.exe built-ins with no standalone executable, so dropping the wrapper broke FileUtils.symlink. Those two call sites now pass cmd.exe, /c, and the command as separate argv elements, which avoids reintroducing the join-based bug above.

Tests

Adds spec/overcommit/subprocess_spec.rb — there wasn't coverage for Subprocess before. It uses Gem.ruby and a NUL-joined ARGV dump so it should be platform-agnostic and pass on the current Linux CI. It covers the #847 case directly, plus results and exit status, options[:input], metacharacter and empty-string arguments, and that ChildProcess.build receives the argv verbatim from both .spawn and .spawn_detached.

On Windows locally, bundle exec overcommit --run passes and rubocop is clean. bundle exec rspec gives 1643 examples / 2 failures, the same as on main (git_repo_spec.rb:341, and utils_spec.rb:142, which needs wmic); git_repo_spec.rb:218 fails on main and passes here.

Notes

  • I also dropped the now-unused require 'overcommit/os'; happy to put it back if you'd rather keep the diff minimal.
  • No spec coverage for the mklink/dir fix — FileUtils has no existing spec file and Windows CI is disabled (Various specs fail on Windows for all Ruby versions #836).
  • Arguments containing both whitespace and a trailing backslash are still mangled, but that reproduces on bare Process.spawn, so it looks unrelated.
  • Anyone relying on cmd.exe expansion inside a hook command would lose it. The API has always been argv-based and execute_in_background already raises on |, so I don't think it'll be an issue, but the reviewer will probably know better.

`Subprocess.spawn` wrapped every command in `cmd.exe /c` and joined the
arguments into a single string before handing them to childprocess. That
collapsed the whole command into one argv element, and childprocess 5.x on
Windows is a thin shim over `Process.spawn`, which sees the embedded spaces,
wraps the element in quotes and backslash-escapes the quotes already inside
it. cmd.exe strips the outer quotes and the child's C runtime then reads the
remaining `\"` as a literal quote rather than a delimiter, so the argument
gets re-split on whitespace.

For the pre-commit stash this meant `git stash save` received the trailing
UTC offset of the stash message as a switch of its own and aborted with
`error: unknown switch '0'`, leaving hooks unable to run at all. No cmd.exe
escaping scheme fixes this properly either: quoting makes `& | < > ( )`
literal but does not prevent `%VAR%` expansion, and carets inside quotes
survive as literal carets.

The wrapper is unnecessary. `Process.spawn` performs the same command
lookup cmd.exe was being used for, so `.bat`, `.cmd`, extensionless
RubyGems shims and bare names resolved via PATHEXT all launch correctly
when passed straight to `ChildProcess.build`, and arguments stay atomic
because no shell ever re-parses them. Drop the wrapper and pass the
argument vector through untouched on every platform.

This requires the `Process.spawn`-based Windows backend that childprocess
introduced in 5.0.0, so raise the dependency floor accordingly.

Fixes sds#847
`mklink` and `dir` are cmd.exe built-ins with no standalone executable,
so removing the cmd.exe wrapper for all Subprocess calls broke
FileUtils.symlink (and left FileUtils.symlink?/readlink working only
by accident, since `dir` happens to be on MRI's hardcoded list of
legacy cmd.exe built-ins that Process.spawn falls back to).

Unlike the removed general-purpose wrapper, this passes cmd.exe, /c,
and the command as separate argv elements rather than joining them
into one pre-escaped string, so it doesn't reintroduce the argument
corruption from sds#847.
Subprocess no longer branches on Overcommit::OS.windows?, so stubbing it
to both true and false ran the same assertions twice and the comment
claiming it exercised "the Windows code path" was no longer accurate.
Collapse to one context, drop the example that duplicated an existing
assertion, and match the surrounding suite's should_receive/stub syntax.
@bwilde-castle
bwilde-castle marked this pull request as ready for review September 11, 2026 21:46
@sds
sds merged commit 55ea3fd into sds:main Oct 15, 2026
19 checks passed
@sds sds added the bug label Oct 15, 2026
sds added a commit to guillaume-d/overcommit that referenced this pull request Nov 10, 2026
* origin/main: (108 commits)
  Remember all previously approved configurations and hooks (sds#665)
  Keep deleted and renamed paths absent while stashing changes (sds#928)
  Document the case-sensitive KtLint hook name (sds#927)
  Update CI actions and pin Ubuntu to clear annotations (sds#926)
  Preserve standard input bytes when forwarding hooks (sds#925)
  Preserve Git-quoted filenames when running all hooks (sds#924)
  Fail when Git cannot enumerate tracked files (sds#923)
  Add note about disabling default hooks (sds#922)
  Close files inspected by LineEndings (sds#921)
  Use Script Host before PowerShell for Windows parent query fallback (sds#920)
  Cache Windows dependency resolution with daily refreshes (sds#919)
  Avoid PowerShell startup for Windows parent command queries (sds#918)
  Avoid repeated CLI startup when preparing integration fixtures (sds#917)
  Allocate more CI runners to Windows with asymmetric sharding (sds#916)
  Shard CI tests across runners and add one required CI check (sds#915)
  Remove EOL Ruby versions from the CI matrix (sds#914)
  Cut CI test time by 68% while preserving the full test matrix (sds#913)
  Cut version 0.75.0 (sds#912)
  Re-enable the full Windows test matrix and fix platform failures (sds#911)
  Read .overcommit.yml as UTF-8 in the hook template (sds#910)
  Update Overcommit logo (sds#907)
  Cut version 0.74.0 (sds#906)
  Keep each worktree's signatures separate (sds#903)
  Recognize amend aliases on macOS (sds#904)
  Exclude files deleted from the working tree from all_files (sds#905)
  Restore the Ruby 2.6-3.1 test checks (sds#902)
  Delete subprocess output tempfiles once they are read (sds#901)
  Stop wrapping commands in cmd.exe on Windows (sds#898)
  Allow URL-only lines to exceed TextWidth body limit (sds#900)
  Cut version 0.73.0 (sds#896)
  Add automated release flow (sds#895)
  Instruct oxfmt not to fail if no files are matched (sds#894)
  Add filetypes to oxc tools (sds#893)
  Add pre commit hook for herb-lint (sds#892)
  Cut version 0.72.0 (sds#891)
  Remove maintainability badge (sds#890)
  Require patched REXML version (sds#889)
  Fix operation state restoration in linked worktrees (sds#887)
  Fail Flay hook when flay crashes instead of silently passing (sds#885)
  Fix Solargraph regexp capture warning (sds#886)
  Cut version 0.71.0 (sds#883)
  Prepare for the new solargraph typecheck format (sds#873)
  Make hook context input reads thread-safe (sds#882)
  Cut version 0.70.0 (sds#880)
  Add oxc pre-commit hooks (sds#879)
  Add Ruby 3.4 and 4.0 to CI matrix (sds#878)
  Cut version 0.69.0 (sds#877)
  Use Etc.nprocessors and handle sandboxed environments (sds#876)
  Cut version 0.68.0 (sds#872)
  Add solargraph pre-commit hook for typechecking (sds#871)
  Update RuboCop in Gemfile to silence a deprecation warning in build (sds#870)
  Cut version 0.67.1
  adds 'set' requirements to diff hook context. (sds#866)
  Add note about unsupported YAML features in `gemfile:` line in default.yml (sds#865)
  Cut version 0.67.0 (sds#864)
  Restore ability to specify "gemfile: false" in config (sds#863)
  Cut version 0.66.0 (sds#861)
  Add `-diff` cli option for running precommit hooks against diffs (sds#860)
  Cut version 0.65.0
  Load bundled gems on expected version (sds#859)
  Update changelog
  Bump rexml to >= 3.3.9 to resolve GHSA-2rxp-v6pw-ch6m (sds#857)
  Expand tildes(~) for hooksPath (sds#853)
  Fix spec compatibility with recent git versions (sds#854)
  Update changelog
  Cut version 0.64.0 (sds#852)
  Add changelog_uri to gemspec (sds#851)
  Support stylelint 16+, which emits messages on stderr (sds#848)
  Add Ruby 3.3 to CI matrix (sds#849)
  Update README with latest requirements (sds#845)
  Fix README badges (sds#844)
  Cut version 0.63.0 (sds#843)
  Add RSpec Hook to PreCommit, Add Applicable files if set (sds#842)
  Fix RuboCop warnings (sds#841)
  [FEATURE] New pre-commit hook: Sorbet (Issue sds#825) (sds#826)
  Green CI PoC (sds#833)
  Revert "Get suite running smoothly again (sds#824)" (sds#840)
  Get suite running smoothly again (sds#824)
  Cut version 0.62.0 (sds#821)
  Allow childprocess 5 (sds#820)
  Update branch for CI from `master` to `main` (sds#819)
  Update RuboCop (sds#818)
  Adding Ruby 3.2 to test matrix (sds#816)
  Cut version 0.61.0 (sds#817)
  fix: local overcommit file merges with existing .overcommit.yml file (sds#815)
  Allow ReplaceBranch to use skip_if (sds#809)
  Cut version 0.60.0 (sds#807)
  Add non ASCII encoding schema support to RailsSchemaUpToDate hook (sds#786)
  Rescue Psych::DisallowedClass in YamlSyntax (sds#805)
  Add optional additional local configuration (sds#799)
  Add MixTest hook (sds#802)
  Add MixFormat hook (sds#801)
  support trailing space in replace_branch's 'replacement_text' config (sds#804)
  Allow overriding Gemfile.lock (sds#796)
  Cut version 0.59.1 (sds#785)
  Revert addition of `--disable-pending-cops` flag to RuboCop (sds#783)
  Revert `Fix encoding of process output under windows` (sds#784)
  Cut version 0.59.0 (sds#780)
  Partial log flushing to make long hooks intuitive (sds#777)
  Fix pronto hooks swallowing generic errors (sds#779)
  ...

# Conflicts:
#	CHANGELOG.md
#	README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants