Refactor Git.execute() command docstring per gitpython-developers#2146

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

1. Description and platform handling. A sequence is recommended.
   For strings: 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 there 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. The portability problem is the user-visible one,
   so the docstring leads with that framing.

2. shell=True / Git.USE_SHELL warning. The shell interprets
   metacharacters such as ;, |, &, and $(...) 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).

3. shlex.split caveat. Far safer than shell=True (so gitpython-developers#2144's
   harm-reduction note is preserved), but qualified: it parses
   POSIX shell syntax and 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, so shlex.split
   should not be recommended as a default tokenization tool. For
   untrusted input, build the sequence yourself.

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.

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 handling is
+            platform-dependent.
+
+            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`): the platform
+            shell interprets metacharacters such as ``;``, ``|``, ``&``,
+            and ``$(...)`` as syntax. Any untrusted text in the command
+            can then execute arbitrary OS commands. See :attr:`Git.USE_SHELL`.
+
+            :func:`shlex.split` is far safer than ``shell=True``. But it
+            parses POSIX shell syntax on all systems, and it 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,10 @@ 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.
+
         :param env:
             A dictionary of environment variables to be passed to
             :class:`subprocess.Popen`.