TheGit.USE_SHELL attribute is currently presented this way:

I believe this encourages developers writing graphical Windows applications that use GitPython to setUSE_SHELL = True, or to retain this in their code from when it may have been added in the past, at a time that it worked around a problem.

However, this is no longer necessary, even in that specific use case on Windows.The problem of console windows being created for GitPython'sgit subprocesses in graphical Windows applications was solved back in 2016, in0d93908 (#469), by passing theCREATE_NO_WINDOWprocess creation flag. How and where that is expressed has changed over time, but the current code definesPROC_CREATIONFLAGS (which it passes tocreationflags in calls toPopen):

That change to passingCREATE_NO_WINDOW was not the main motivation behind#469, and it appears to some extent to have escaped notice, not having made it into the manually written changelogs of any version of GitPython. The recommendation to setUSE_SHELL toTrue had previously been entered into the changelog in1c2dd54 for 0.3.7, when it was made no longer the default on Windows, as it had been since3f277ba (#126). In contrast, it was no longer necessary (nor useful) to do this since2.0.8, the first release after#469 was merged, but that change was never noted.

Usingshell=True as a default is undesirable at least in the typical case thatGit.execute is called indirectly through dynamic methods, because it is not typically feasible to account for the effect of shell expansions. TheGit class is used in GitPython, and documented for use, in ways that do not account for characters with special meaning to the shell being present in text supplied as paths, branch and tag names, and so forth.

For that reason, combined with the better approach to#126 that came in with#469, comments or associated documentation forGit.USE_SHELL should no longer recommend its use in any likely scenarios, and should even caution against its use in the specific scenario where it was previously recommended.

I had suspected in#1685 (see "Thepythonw use case") that callingPopen withshell=True might no longer be needed, but I did not realize that a change to GitPython, rather than Python or Windows, was responsible, and I was not sure. I now feel sure, due to a combination of the following factors:

• Official Microsoft documentation of the effect of theCREATE_NO_WINDOWprocess creation flag.
• Addition of a symbolic constant in Python 3.7documented accordingly. Note that the technique worked before this, it was just necessary to define the constant or otherwise pass the correct value manually. These days, GitPython only supports Python 3.7 and higher, so the constant can be (and is) used.
• The explanation in0d93908 (from#469) of the improvement of passing the flag.
• Manual testing, done today. I improved on the testing procedure I had used in#1685 by testing withpythonw -m idlelib on Python 3.7.9 and 3.12.1 virtual environments on Windows 10, both withgit.cmd.PROC_CREATIONFLAGS unmodified, and separately by binding it tosubprocess.CREATE_NEW_PROCESS_GROUP (i.e., it value without theCREATE_NO_WINDOW flag included). Removing theCREATE_NO_WINDOW flag, which I had not tried when working on#1685, reliably produced a console window that lasted the duration of agit command. I tested with the long-running commandgit.Repo.clone_from("https://github.com/huggingface/transformers.git", "transformers").
• Verification that the specific example in theUSE_SHELL comment, to the extent to which it may have intended other situations whereUSE_SHELL = True was needed, is out of date. That comment points totest_untracked_files as a case that requiresUSE_SHELL = True on Windows. CI reveals that test case passes with no special action and with the default ofFalse, including on Windows, on all Python versions GitPython supports:3.7,3.8,3.9,3.10,3.11,3.12.

It may make sense to deprecateGit.USE_SHELL, or to deprecate setting it toTrue. Even before that is determined, however, I think it is worthwhile to change the comment. The main reason I'm opening this as an issue, rather than detailing it in a PR, is so that if the particular wording or other aspects of my proposed change (#1782) end up needing to be rejected or deferred, the issue itself won't be lost track of.