Windows Shell Commands

This repo is developed on Windows. Two shells are reachable from tools, and they do not share syntax. Mixing one shell's quoting into the other silently corrupts arguments.

Default to PowerShell

Prefer the PowerShell tool for shell commands on Windows, especially anything with quoting, multi-line text, or special characters (git commit, gh pr create, writing file content). It is the native shell here and its multi-line here-string works as documented.

Use the Bash tool for genuine POSIX work: sed/awk pipelines, curl one-liners, shell scripts, and .sh files. It runs Git Bash (POSIX sh), not cmd or PowerShell.

The trap: it is easy to type one shell's heredoc syntax into the other tool. The syntax below is not interchangeable.

Multi-line text: what works, what does not

Symptom of getting it wrong

A commit message or PR body comes out wrapped in literal characters, classically a lone @ line at the very top and bottom. That means a PowerShell here-string (@'...'@) was fed to the Bash tool, where @ is just a literal character concatenated onto the quoted string.

PowerShell tool (preferred)

Single-quoted here-string. The closing '@ MUST be at column 0 (no indentation) on its own line:

git commit -m @'
Subject line

Body paragraph with $literal dollar signs and "quotes" left intact.
'@

Use @'...'@ (literal, no expansion). Only use @"..."@ if you actually need $variable expansion. Indenting the closing '@ is a parse error.

Bash tool

A PowerShell here-string does NOT work here. Use one of these instead:

• A real POSIX heredoc into git commit -F -:

  git commit -F - <<'EOF'
  Subject line
  
  Body paragraph.
  EOF

• Multiple -m flags (each becomes a paragraph): git commit -m "Subject" -m "Body paragraph."

<<'EOF' (quoted delimiter) keeps the body literal; unquoted <<EOF expands $vars and backticks.

PR bodies and other long content: write a file

The most robust approach in either shell is to write the text to a file and point the command at it. This sidesteps all quoting and heredoc differences:

gh pr create --base master --title "..." --body-file path/to/body.md
gh pr edit <N> --body-file path/to/body.md

Write the file with the Write tool (not shell redirection), then pass --body-file / -F. Delete the temp file afterward. A scratch file under .git/ is convenient and never tracked.

Rule of thumb

Multi-line or special characters: use the PowerShell here-string, or write a file and pass it by path. Reserve the Bash tool's heredoc for when you are already in a POSIX pipeline, and never paste @'...'@ into the Bash tool.