Rewrite Git.execute() command parameter docstring

gitpython-developers#2146 identifies two issues with gitpython-developers#2144's :param command: rewrite,
which this fixes by reworking the block as four paragraphs:

1. Description: a sequence of program arguments is recommended; a
   string is also accepted, but its meaning is strongly
   platform-dependent.

2. Platform-specific string handling. By default, a shell is not
   used. On Unix-like systems the whole string is the program name
   (so multi-word strings raise GitCommandNotFound); on Windows the
   OS parses the string itself, so multi-word strings can work but
   are not portable. This corrects gitpython-developers#2144's claim that with
   shell=False the string "is passed as a single executable name to
   subprocess.Popen" -- accurate on Unix-like systems, but on
   Windows subprocess.Popen forwards the string to CreateProcessW
   and Windows command-line parsing produces argv.

3. shell=True / Git.USE_SHELL warning. The shell interprets
   metacharacters such as ;, |, &, $(...) (on POSIX), and ^ (on
   Windows) as syntax; untrusted text in the command can then
   execute arbitrary OS commands. Cross-references USE_SHELL for
   the long-form discussion (which has the attack examples and
   history).

4. shlex.split caveat. Producing a sequence automatically via
   shlex.split is far safer than shell=True (so gitpython-developers#2144's
   harm-reduction note is preserved), but qualified: shlex.split
   parses POSIX shell syntax on all systems and the result is
   still unsafe for anything but fixed, fully trusted strings.
   Calls out the f-string-then-shlex.split anti-pattern explicitly
   -- whitespace or quoting in an untrusted interpolated value can
   still inject arguments. For input derived in any way from
   untrusted data, build the argument sequence yourself, while
   ensuring each argument is fully sanitized.

Add a related paragraph to :param shell: noting that, on Unix-like
systems, shlex.split may serve in rare cases as a transitional
step when migrating existing string-command shell=True calls, with
extreme care, and cross-referencing :param command: for the risks.

Removes gitpython-developers#2144's hedged "possible security implications" wording
and its implicit recommendation of shlex.split as a general
string-to-argv splitter, in favor of named mechanisms and a
narrow, qualified mention. Documentation only; behavior is
unchanged.

For gitpython-developers#2146.

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

Author: EliahKagan

git/cmd.py

@@ -1131,16 +1131,28 @@ 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 is recommended.
+            A string is also accepted, but its meaning is strongly platform-dependent.
+
+            By default, a shell is not used. On Unix-like systems, a string is the
+            whole program name (so ``"git log -n 1"`` raises
+            :class:`GitCommandNotFound`). On Windows, the OS parses the string itself,
+            so multi-word strings can work but are not portable.
+
+            Avoid ``shell=True`` (and :attr:`Git.USE_SHELL`): this runs the command in
+            a shell, which is generally unsafe. The shell interprets metacharacters such
+            as ``;``, ``|``, ``&``, ``$(...)`` (on POSIX), and ``^`` (on Windows), as
+            syntax. Any untrusted text in the command can then execute arbitrary OS
+            commands. See :attr:`Git.USE_SHELL`.
+
+            Producing a sequence automatically by :func:`shlex.split` and passing it
+            as the command is far safer than ``shell=True``. But :func:`shlex.split`
+            parses POSIX shell syntax on all systems, and the result is still unsafe
+            for anything but *fixed, fully trusted* strings. Do not use it on strings
+            built by interpolating values: whitespace or quoting in an untrusted value
+            can still inject arguments. For input derived in any way from untrusted
+            data, build the argument sequence yourself, while ensuring each argument
+            is fully sanitized.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.
@@ -1208,6 +1220,11 @@ def execute(
             needed (nor useful) to work around any known operating system specific
             issues.
 
+            On Unix-like systems, when migrating away from passing string commands with
+            ``shell=True``, :func:`shlex.split` may serve as a transitional step in rare
+            cases, but this should be undertaken with extreme care. See the `command`
+            parameter above on the risks.
+
         :param env:
             A dictionary of environment variables to be passed to
             :class:`subprocess.Popen`.