Clarify Git.execute() string semantics and shell/shlex risks

Update the rewritten :param command: block from gitpython-developers#2144 in two
ways:

* Add a Windows bullet. gitpython-developers#2144 said the string is "passed as a
  single executable name to subprocess.Popen" with shell=False.
  That is accurate on POSIX, but on Windows subprocess.Popen
  forwards the string to CreateProcessW and Windows command-line
  parsing produces the program's argv. So e.g. "git version"
  actually runs.

* Name the tokenization risks specifically. gitpython-developers#2144 hedged with
  "possible security implications" for shlex.split and pointed at
  the existing shell-parameter warning for shell=True. Be
  concrete: under shell=True the shell interprets ;, |, &, $(...),
  etc. as syntax, so metacharacters in interpolated values can
  execute arbitrary commands; shlex.split is preferable on POSIX
  but follows POSIX rules on Windows that may diverge from
  Windows command-line conventions; and embedded whitespace or
  quotes can shift tokenization either way. Neither is safe with
  untrusted input (branch names, URLs, filenames, etc.); the
  sequence form is, because each interpolated value occupies a
  single argv slot.

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,34 @@ 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``.
+
+            ``shell=True`` is rarely safe because the platform shell
+            interprets metacharacters such as ``;``, ``|``, ``&``, and
+            ``$(...)`` as syntax. Use :func:`shlex.split` instead on
+            POSIX; on Windows it follows POSIX rules that may diverge
+            from Windows command-line conventions. Neither is safe
+            with untrusted input (branch names, URLs, filenames, etc.):
+            whitespace or quotes can shift tokenization, and under
+            ``shell=True`` metacharacters can run arbitrary commands.
+            Build the sequence form when interpolating such values,
+            keeping each in a single argv slot.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.