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

Rework :param command: as four parts:

1. Brief parameter description, with a recommendation to pass a
   sequence and a platform-dependent note on string handling: on
   POSIX a string is the program name, on Windows the OS splits it
   into argv. Corrects gitpython-developers#2144's claim that with shell=False the
   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. shell=True (or Git.USE_SHELL) explanation: it sends the command
   to the platform shell rather than executing it directly, and
   the shell interprets ;, |, &, $(...), etc. as syntax. With
   untrusted text in the command -- paths, branch names, URLs,
   etc. -- this is arbitrary OS command execution. Cross-references
   Git.USE_SHELL for the long-form discussion.

3. shlex.split explanation: runs no shell, so the
   command-injection risk does not apply, but its POSIX shell
   rules on Windows match neither the shell=False OS argv parsing
   nor the shell=True cmd.exe parsing. Untrusted whitespace or
   quoting can therefore shift token boundaries, injecting extra
   arguments into git's option parser.

4. Asymmetric conclusion: build the sequence form directly;
   shell=True is the more dangerous route (arbitrary command
   execution), but no automatic-splitting route is safe with
   untrusted input.

Replaces gitpython-developers#2144's hedged "possible security implications" wording
with named mechanisms; preserves the asymmetry between command
injection (shell=True) and argument injection (shlex.split on
Windows). No worked examples (verbosity); the existing USE_SHELL
docstring carries the full attack discussion. 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,30 @@ 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.
+            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`) sends the command to
+            the platform shell rather than executing it directly. The shell
+            interprets characters such as ``;``, ``|``, ``&``, and
+            ``$(...)`` as syntax, so any untrusted text in the command
+            (paths, branch names, URLs, etc.) can execute arbitrary OS
+            commands. See :attr:`Git.USE_SHELL` for further detail.
+
+            :func:`shlex.split` runs no shell, so command injection is
+            not a concern, but its POSIX shell rules on Windows match
+            neither the OS argv parsing under ``shell=False`` nor the
+            ``cmd.exe`` parsing under ``shell=True``. Untrusted
+            whitespace or quoting can shift token boundaries, injecting
+            extra arguments into git's option parser.
+
+            Build the sequence form directly. With untrusted input,
+            ``shell=True`` is the more dangerous (arbitrary command
+            execution); no automatic-splitting route is safe.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.