Skip to content

Commit d172e54

Browse files
committed
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).
1 parent ddca0b3 commit d172e54

1 file changed

Lines changed: 10 additions & 3 deletions

File tree

git/cmd.py

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1119,9 +1119,16 @@ def execute(
11191119
information (stdout).
11201120
11211121
:param command:
1122-
The command argument list to execute.
1123-
It should be a sequence of program arguments, or a string. The
1124-
program to execute is the first item in the args sequence or string.
1122+
The command to execute. A sequence of program arguments is the
1123+
recommended form when `shell` is ``False`` (the default), e.g.
1124+
``["git", "log", "-n", "1"]``.
1125+
1126+
A string is accepted, but with `shell` set to ``False`` it is passed
1127+
as a single executable name to :class:`subprocess.Popen`. For example,
1128+
``"git log -n 1"`` looks for an executable literally named
1129+
``git log -n 1`` and will fail with :class:`GitCommandNotFound`. To
1130+
split a command string into argv tokens, pass ``shlex.split(...)`` as
1131+
a sequence or set `shell` to ``True`` (see the warning below).
11251132
11261133
:param istream:
11271134
Standard input filehandle passed to :class:`subprocess.Popen`.

0 commit comments

Comments
 (0)