Repository navigation
Commit 830471c
authored
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1131,16 +1131,28 @@ def execute( | |||
| 1131 | 1131 | information (stdout). | |
| 1132 | 1132 | ||
| 1133 | 1133 | :param command: | |
| 1134 | - The command to execute. A sequence of program arguments is the | ||
| 1135 | - recommended form when `shell` is ``False`` (the default), e.g. | ||
| 1136 | - ``["git", "log", "-n", "1"]``. | ||
| 1137 | - | ||
| 1138 | - A string is accepted, but with `shell` set to ``False`` it is passed | ||
| 1139 | - as a single executable name to :class:`subprocess.Popen`. For example, | ||
| 1140 | - ``"git log -n 1"`` looks for an executable literally named | ||
| 1141 | - ``git log -n 1`` and will fail with :class:`GitCommandNotFound`. To | ||
| 1142 | - split a command string into argv tokens, pass ``shlex.split(...)`` as | ||
| 1143 | - a sequence or set `shell` to ``True`` (see the warning below). | ||
| 1134 | + The command to execute. A sequence of program arguments is recommended. | ||
| 1135 | + A string is also accepted, but its meaning is strongly platform-dependent. | ||
| 1136 | + | ||
| 1137 | + By default, a shell is not used. On Unix-like systems, a string is the whole | ||
| 1138 | + program name (so ``"git log -n 1"`` raises :class:`GitCommandNotFound`). On | ||
| 1139 | + Windows, the program parses the arguments itself, so multi-word strings can | ||
| 1140 | + work but are not portable. | ||
| 1141 | + | ||
| 1142 | + Avoid ``shell=True`` (and :attr:`Git.USE_SHELL`): this runs the command in | ||
| 1143 | + a shell, which is generally unsafe. The shell interprets metacharacters | ||
| 1144 | + such as ``;``, ``|``, ``&``, ``$(...)``, ``$VAR``, ``%VAR%``, and ``^`` | ||
| 1145 | + (depending on the platform) as syntax. Any untrusted text in the command | ||
| 1146 | + can then execute arbitrary OS commands. See :attr:`Git.USE_SHELL`. | ||
| 1147 | + | ||
| 1148 | + Producing a sequence automatically by :func:`shlex.split` and passing it | ||
| 1149 | + as the command is far safer than ``shell=True``. But :func:`shlex.split` | ||
| 1150 | + parses POSIX shell syntax on all systems, and the result is still unsafe | ||
| 1151 | + for anything but *fixed, fully trusted* strings. Do not use it on strings | ||
| 1152 | + built by interpolating values: whitespace or quoting in an untrusted value | ||
| 1153 | + can still inject arguments. For input derived in any way from untrusted | ||
| 1154 | + data, build the argument sequence yourself, while ensuring each argument | ||
| 1155 | + is fully sanitized. | ||
| 1144 | 1156 | ||
| 1145 | 1157 | :param istream: | |
| 1146 | 1158 | Standard input filehandle passed to :class:`subprocess.Popen`. | |
@@ -1208,6 +1220,11 @@ def execute( | |||
| 1208 | 1220 | needed (nor useful) to work around any known operating system specific | |
| 1209 | 1221 | issues. | |
| 1210 | 1222 | ||
| 1223 | + On Unix-like systems, when migrating away from passing string commands with | ||
| 1224 | + ``shell=True``, :func:`shlex.split` may serve as a transitional step in rare | ||
| 1225 | + cases, with extreme care. (Drop ``shell=True`` and pass the resulting | ||
| 1226 | + sequence as the command.) See the `command` parameter above on the risks. | ||
| 1227 | + | ||
| 1211 | 1228 | :param env: | |
| 1212 | 1229 | A dictionary of environment variables to be passed to | |
| 1213 | 1230 | :class:`subprocess.Popen`. | |
0 commit comments