Refactor Git.execute() command docstring after gitpython-developers#2144

Rework :param command: as three parts:

1. Brief description: parameter type, sequence recommended, brief
   platform-dependent string note. Corrects gitpython-developers#2144's claim that with
   shell=False a string is "passed as a single executable name to
   subprocess.Popen" -- accurate on POSIX, but on Windows
   subprocess.Popen forwards the string to CreateProcessW, which
   tokenizes via Windows command-line parsing.

2. Asymmetric security paragraphs:

   * shell=True (or Git.USE_SHELL) runs the command through the
     shell, which interprets metacharacters anywhere in it; with
     untrusted input that is OS command injection. Cross-references
     USE_SHELL and the shell parameter for detail.
   * shlex.split runs no shell, but tokenizes by POSIX shell rules.
     On Windows those rules differ from both shell=False's OS argv
     parsing and shell=True's cmd.exe parsing, so untrusted
     whitespace or quoting can shift token boundaries and inject
     extra arguments into git's own option parser.

3. Conclusion: neither automatic-splitting approach is safe with
   untrusted input; build the sequence form directly, one value
   per argv slot.

Replaces gitpython-developers#2144's hedged "possible security implications" wording
with named mechanisms and keeps the asymmetry between command
injection (shell=True, catastrophic) and argument injection
(shlex.split on Windows, milder) visible. No worked examples to
keep the docstring compact; the existing USE_SHELL and shell-
parameter docstrings give the full picture for shell=True.
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,31 @@ 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 argument list to execute.
+            It should be a sequence of program arguments, or a string.
+            Passing a sequence of program arguments is recommended. With a
+            string, parsing is delegated to :class:`subprocess.Popen` and
+            is platform-dependent: on POSIX the entire string is taken as
+            the program name, while on Windows the OS splits it into argv.
+
+            ``shell=True`` (or :attr:`Git.USE_SHELL`) runs the command
+            through the platform shell rather than executing it directly.
+            The shell interprets metacharacters such as ``;``, ``|``,
+            ``&``, and ``$(...)`` anywhere in the command, so untrusted
+            input — paths, branch names, URLs, etc. — is then OS command
+            injection. See :attr:`Git.USE_SHELL` and the ``shell``
+            parameter below for further detail.
+
+            :func:`shlex.split` does not invoke a shell, but tokenizes by
+            POSIX shell rules. On Windows those rules differ from both
+            the Windows command-line parsing used under ``shell=False``
+            and the ``cmd.exe`` parsing used under ``shell=True``; its
+            tokens may match neither, so untrusted whitespace or quoting
+            can shift token boundaries and inject extra arguments that
+            git's own option parser may act on.
+
+            Neither approach is safe with untrusted input. Build the
+            sequence form directly, one value per argv slot.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.