|
19 | 19 | importsys |
20 | 20 | fromtextwrapimportdedent |
21 | 21 | importthreading |
| 22 | +importwarnings |
22 | 23 |
|
23 | 24 | fromgit.compatimportdefenc,force_bytes,safe_decode |
24 | 25 | fromgit.excimport ( |
|
54 | 55 | TYPE_CHECKING, |
55 | 56 | TextIO, |
56 | 57 | Tuple, |
| 58 | +Type, |
57 | 59 | Union, |
58 | 60 | cast, |
59 | 61 | overload, |
@@ -307,8 +309,45 @@ def dict_to_slots_and__excluded_are_none(self: object, d: Mapping[str, Any], exc |
307 | 309 |
|
308 | 310 | ## -- End Utilities -- @} |
309 | 311 |
|
| 312 | +_USE_SHELL_DEFAULT_MESSAGE= ( |
| 313 | +"Git.USE_SHELL is deprecated, because only its default value of False is safe. " |
| 314 | +"It will be removed in a future release." |
| 315 | +) |
| 316 | + |
| 317 | +_USE_SHELL_DANGER_MESSAGE= ( |
| 318 | +"Setting Git.USE_SHELL to True is unsafe and insecure, and should be avoided, " |
| 319 | +"because the effect of shell metacharacters and shell expansions cannot usually be " |
| 320 | +"accounted for. In addition, Git.USE_SHELL is deprecated and will be removed in a " |
| 321 | +"future release." |
| 322 | +) |
| 323 | + |
| 324 | + |
| 325 | +def_warn_use_shell(extra_danger:bool)->None: |
| 326 | +warnings.warn( |
| 327 | +_USE_SHELL_DANGER_MESSAGEifextra_dangerelse_USE_SHELL_DEFAULT_MESSAGE, |
| 328 | +DeprecationWarning, |
| 329 | +stacklevel=3, |
| 330 | + ) |
| 331 | + |
| 332 | + |
| 333 | +class_GitMeta(type): |
| 334 | +"""Metaclass for :class:`Git`. |
| 335 | +
|
| 336 | + This helps issue :class:`DeprecationWarning` if :attr:`Git.USE_SHELL` is used. |
| 337 | + """ |
310 | 338 |
|
311 | | -classGit: |
| 339 | +@property |
| 340 | +defUSE_SHELL(cls:Type[Git])->bool: |
| 341 | +_warn_use_shell(False) |
| 342 | +returncls._USE_SHELL |
| 343 | + |
| 344 | +@USE_SHELL.setter |
| 345 | +defUSE_SHELL(cls:Type[Git],value:bool)->None: |
| 346 | +_warn_use_shell(value) |
| 347 | +cls._USE_SHELL=value |
| 348 | + |
| 349 | + |
| 350 | +classGit(metaclass=_GitMeta): |
312 | 351 | """The Git class manages communication with the Git binary. |
313 | 352 |
|
314 | 353 | It provides a convenient interface to calling the Git binary, such as in:: |
@@ -358,25 +397,30 @@ def __setstate__(self, d: Dict[str, Any]) -> None: |
358 | 397 | GIT_PYTHON_TRACE=os.environ.get("GIT_PYTHON_TRACE",False) |
359 | 398 | """Enables debugging of GitPython's git commands.""" |
360 | 399 |
|
361 | | -USE_SHELL=False |
362 | | -"""Deprecated. If set to ``True``, a shell will be used when executing git commands. |
| 400 | +_USE_SHELL:bool=False |
363 | 401 |
|
364 | | - Prior to GitPython 2.0.8, this had a narrow purpose in suppressing console windows |
365 | | - in graphical Windows applications. In 2.0.8 and higher, it provides no benefit, as |
366 | | - GitPython solves that problem more robustly and safely by using the |
367 | | - ``CREATE_NO_WINDOW`` process creation flag on Windows. |
| 402 | +@property |
| 403 | +defUSE_SHELL(self)->bool: |
| 404 | +"""Deprecated. If set to ``True``, a shell will be used to execute git commands. |
368 | 405 |
|
369 | | -Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any GitPython |
370 | | -functions should be updated to use the default value of ``False`` instead. ``True`` |
371 | | -is unsafe unless the effect of shell expansions is fully consideredandaccounted |
372 | | -for, which is not possible under most circumstances. |
| 406 | + Prior to GitPython 2.0.8, this had a narrow purpose in suppressing console |
| 407 | + windows in graphical Windows applications. In 2.0.8 and higher, it provides no |
| 408 | + benefit, as GitPython solves that problem more robustlyandsafely by using the |
| 409 | + ``CREATE_NO_WINDOW`` process creation flag on Windows. |
373 | 410 |
|
374 | | - See: |
| 411 | + Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any |
| 412 | + GitPython functions should be updated to use the default value of ``False`` |
| 413 | + instead. ``True`` is unsafe unless the effect of shell expansions is fully |
| 414 | + considered and accounted for, which is not possible under most circumstances. |
375 | 415 |
|
376 | | - - :meth:`Git.execute` (on the ``shell`` parameter). |
377 | | - - https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a |
378 | | - - https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags |
379 | | - """ |
| 416 | + See: |
| 417 | +
|
| 418 | + - :meth:`Git.execute` (on the ``shell`` parameter). |
| 419 | + - https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a |
| 420 | + - https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags |
| 421 | + """ |
| 422 | +_warn_use_shell(False) |
| 423 | +returnself._USE_SHELL |
380 | 424 |
|
381 | 425 | _git_exec_env_var="GIT_PYTHON_GIT_EXECUTABLE" |
382 | 426 | _refresh_env_var="GIT_PYTHON_REFRESH" |
@@ -1138,7 +1182,7 @@ def execute( |
1138 | 1182 |
|
1139 | 1183 | stdout_sink=PIPEifwith_stdoutelsegetattr(subprocess,"DEVNULL",None)oropen(os.devnull,"wb") |
1140 | 1184 | ifshellisNone: |
1141 | | -shell=self.USE_SHELL |
| 1185 | +shell=self._USE_SHELL |
1142 | 1186 | _logger.debug( |
1143 | 1187 | "Popen(%s, cwd=%s, stdin=%s, shell=%s, universal_newlines=%s)", |
1144 | 1188 | redacted_command, |
|