From d172e541455679ebdfb55df1411836298cb47b8d Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 7 May 2026 03:20:20 -0700
Subject: [PATCH] docs(cmd): clarify Git.execute() string vs list command
 argument

Closes #2016

Users routinely hit GitCommandNotFound by passing a single string with
spaces to repo.git.execute(...). With shell=False (default) subprocess
treats the entire string as the executable name and fails. Document the
recommended list form, the string-as-single-executable behavior, and the
two ways to coerce a string into argv tokens (shlex.split or shell=True).
---
 git/cmd.py | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/git/cmd.py b/git/cmd.py
index 78a9f4c78..1ecff9318 100644
--- a/git/cmd.py
+++ b/git/cmd.py
@@ -1119,9 +1119,16 @@ def execute(
         information (stdout).
 
         :param command:
-            The command argument list to execute.
-            It should be a sequence of program arguments, or a string. The
-            program to execute is the first item in the args sequence or string.
+            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).
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.