cmd.exe and batch script pitfalls: %ERRORLEVEL% timing, delayed expansion and caret escaping

What it is

cmd.exe's scripting model predates PowerShell and keeps its own rules for conditionals, variable expansion and escaping, documented in Microsoft's Windows Commands reference for if and setlocal.

Why it matters

• %ERRORLEVEL% versus if errorlevel: %ERRORLEVEL% is a normal environment-style expansion, substituted once when the line is parsed. Inside a multi-line if/for block (parsed as one unit) it can show the value from before the block ran, not after an inner command. if errorlevel N (documented on the same if reference page) instead tests "is the ERRORLEVEL variable equal to or greater than N", evaluated at the point the if runs, and is the safer check for "did the previous external command fail".
• Delayed expansion: setlocal EnableDelayedExpansion enables the !var! syntax, evaluated when each line actually executes rather than when the block was parsed (%var% stays parse-time); without it, a loop that sets and reads the same variable in one block sees only the pre-loop value. The Windows Commands setlocal page documents this switch. While it is enabled, a literal ! in data (a password, a file name) is consumed as expansion syntax.
• Quoting and the caret: cmd.exe has no single quoting; the caret (^) is the escape character for the characters cmd treats specially (& | < > ^, and ( ) inside blocks); % is escaped by doubling it (%%) in a batch file, not with a caret. Inside "..." those characters lose their special meaning (a caret there is literal); a URL or path containing & concatenated into an unquoted line is the classic failure.
• Calling cmd.exe/batch tools from PowerShell: PowerShell re-parses arguments, so a cmd.exe /c line with embedded quotes or &/| often needs the stop-parsing token --%, which about_Parsing documents as changing "the interpretation of all remaining arguments": PowerShell passes the rest of the line literally, still expands %NAME% environment variables, allows no PowerShell variables, and stops at the next newline or pipe character. It is intended for native commands on Windows.

How to apply

• Prefer if errorlevel 1 (...) or if %ERRORLEVEL% neq 0 (...) placed immediately after the command it checks, not inside a block that also changes the value (there, use !ERRORLEVEL!). if errorlevel 1 means "1 or higher" and misses negative exit codes such as crash codes; neq 0 catches every failure.
• Use setlocal EnableDelayedExpansion and !var! wherever a variable is set and read again within one parenthesized block.
• Wrap any value that may contain &, |, <, >, ^ or spaces in double quotes; when quoting is not possible, escape the character with a caret.
• From PowerShell, use cmd.exe /c --% <literal command> for command lines with characters PowerShell would otherwise reinterpret.

Pitfalls

• Checking %ERRORLEVEL% later than immediately after the command: another external program overwrites it, while many internal commands such as echo leave it unchanged, so a stale value from an earlier command can survive. Never set ERRORLEVEL=..., which shadows the dynamic value.
• Mixing delayed and non-delayed expansion for the same variable in one script, so %var% and !var! disagree about which value is current.
• Assuming batch supports here-strings or arrays; complex logic is a sign to move to PowerShell instead of nesting more for /f tricks.