Commit 106bbe6
committed
Update USE_SHELL docstring on why not to use it anymore
This expands the "docstring" associated with the Git.USE_SHELL
attribute to mention the dangers of setting it to True and explain
the old purpose it once served for graphical Windows applications
and why it is no longer required for that since 2.0.8. (See #1781.)
Although setting `Git.USE_SHELL = True` or passing `shell=True`
should rarely if ever be done and is no longer necessary even in
the specific scenario for which it was once recommended, I have
deliberately avoided claiming USE_SHELL is deprecated at this time.
Whether GitPython should formally deprecate it (documenting it as
such and issuing DeprecationWarning on some or all uses) may hinge
on whether it is possible for GitPython to incorporate enhancements
that account for and suppress at least some unintended shell
expansions when shell=True is passed through dynamic methods that
indirectly call Git.execute. The decision may also benefit from
examination of existing common uses, if any, of `USE_SHELL = True`.1 parent 94a85d1 commit 106bbe6
1 file changed
Lines changed: 14 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -282,10 +282,20 @@ def __setstate__(self, d: Dict[str, Any]) -> None: | |||
| 282 | 282 | USE_SHELL = False | |
| 283 | 283 | """If True, a shell will be used when executing git commands. | |
| 284 | 284 | ||
| 285 | - This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126 | ||
| 286 | - and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required. | ||
| 287 | - | ||
| 288 | - Override this value using ``Git.USE_SHELL = True``. | ||
| 285 | + This exists to avoid breaking old code that may access it, but it is no longer | ||
| 286 | + needed and should rarely if ever be used. Prior to GitPython 2.0.8, it had a narrow | ||
| 287 | + purpose in suppressing console windows in graphical Windows applications. In 2.0.8 | ||
| 288 | + and higher, it provides no benefit, as GitPython solves that problem more robustly | ||
| 289 | + and safely by using the ``CREATE_NO_WINDOW`` process creation flag on Windows. | ||
| 290 | + | ||
| 291 | + Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any GitPython | ||
| 292 | + functions should be updated to use the default value of ``False`` instead. ``True`` | ||
| 293 | + is unsafe unless the effect of shell expansions is fully considered and accounted | ||
| 294 | + for, which is not possible under most circumstances. | ||
| 295 | + | ||
| 296 | + See: | ||
| 297 | + - https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a | ||
| 298 | + - https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags | ||
| 289 | 299 | """ | |
| 290 | 300 | ||
| 291 | 301 | _git_exec_env_var = "GIT_PYTHON_GIT_EXECUTABLE" | |
0 commit comments