Clarify Git.execute() string semantics on Windows and shlex caveat

gitpython-developers#2144 stated that with shell=False, a string command is passed as a
single executable name. That is correct on POSIX, but on Windows
subprocess.Popen forwards the string to CreateProcessW and Windows
command-line parsing rules produce the program's argv. So a
multi-word command string like "git version" actually runs on
Windows.

It also recommended shlex.split() for tokenizing a string into
argv. The shlex module is intended only for Unix shells; its
tokenization can diverge from Windows command-line conventions,
with possible security implications when the input is not fully
trusted.

Rewrite the :param command: block to keep gitpython-developers#2144's recommendation
to use the sequence form and its helpful POSIX failure-mode
example, add an explicit Windows bullet describing the OS-side
parsing, and note shlex.split's POSIX-only nature. This is
documentation only; behavior is unchanged.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: EliahKagan

git/cmd.py

@@ -1131,16 +1131,32 @@ def execute(
         information (stdout).
 
         :param command:
-            The command to execute. A sequence of program arguments is the
-            recommended form when `shell` is ``False`` (the default), e.g.
-            ``["git", "log", "-n", "1"]``.
-
-            A string is accepted, but with `shell` set to ``False`` it is passed
-            as a single executable name to :class:`subprocess.Popen`. For example,
-            ``"git log -n 1"`` looks for an executable literally named
-            ``git log -n 1`` and will fail with :class:`GitCommandNotFound`. To
-            split a command string into argv tokens, pass ``shlex.split(...)`` as
-            a sequence or set `shell` to ``True`` (see the warning below).
+            The command to execute. A sequence of program arguments, e.g.
+            ``["git", "log", "-n", "1"]``, is the recommended form: the tokens
+            are passed to the program unchanged on every platform.
+
+            A string is also accepted, but how it is interpreted depends on
+            the platform when `shell` is ``False`` (the default), because
+            :meth:`Git.execute` delegates to :class:`subprocess.Popen`:
+
+            * On POSIX, the entire string is taken as the executable name; no
+              tokenization is performed. ``"git log -n 1"`` therefore looks
+              for an executable literally named ``git log -n 1`` and fails
+              with :class:`GitCommandNotFound`.
+            * On Windows, the string is passed unchanged to the underlying
+              ``CreateProcessW`` API, and Windows command-line parsing rules
+              determine the tokens the called program receives in its argv.
+              ``"git log -n 1"`` therefore runs ``git`` with arguments
+              ``log``, ``-n``, and ``1``.
+
+            To split a command string into argv tokens portably, construct
+            the sequence form yourself. :func:`shlex.split` is a tempting
+            shortcut, but :mod:`shlex` is intended only for Unix-style
+            shells; its tokenization can diverge from Windows command-line
+            conventions, with possible security implications when the input
+            is not fully trusted. Setting `shell` to ``True`` instead causes
+            the platform's shell to tokenize the string, but see the warning
+            on the `shell` parameter below before relying on that.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.