docs: clarify exec shell override guidance

Maintainer edit: make the shell parameter description explain defaults and when to override instead of only listing shell names.
2026-07-06 12:11:25 +08:00
parent 8222f3c85f
commit 4ec111c1a9
2 changed files with 10 additions and 2 deletions
@@ -90,9 +90,13 @@ class _PreparedCommand:
        ),
        shell=StringSchema(
            (
-                "Optional shell binary to launch. Windows: powershell, pwsh, cmd."
+                "Override the Windows shell only when needed. Omit to use "
+                "PowerShell by default (pwsh when available, else powershell). "
+                "Pass 'cmd' only for cmd.exe syntax or cmd built-ins."
                if _IS_WINDOWS
-                else "Optional shell binary to launch. Unix: sh, bash, zsh."
+                else "Override the Unix shell only when needed. Omit to use "
+                "bash by default. Pass 'sh' for POSIX sh or 'zsh' for "
+                "zsh-specific syntax."
            ),
            nullable=True,
        ),