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`.

Author: EliahKagan

git/cmd.py

@@ -282,10 +282,20 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
 USE_SHELL=False
 """If True, a shell will be used when executing git commands.
 
- This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
- and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
-
- Override this value using ``Git.USE_SHELL = True``.
+ This exists to avoid breaking old code that may access it, but it is no longer
+ needed and should rarely if ever be used. Prior to GitPython 2.0.8, it had a narrow
+ purpose in suppressing console windows in graphical Windows applications. In 2.0.8
+ and higher, it provides no benefit, as GitPython solves that problem more robustly
+ and safely by using the ``CREATE_NO_WINDOW`` process creation flag on Windows.
+
+ Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any GitPython
+ functions should be updated to use the default value of ``False`` instead. ``True``
+ is unsafe unless the effect of shell expansions is fully considered and accounted
+ for, which is not possible under most circumstances.
+
+ See:
+ - https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a
+ - https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
  """
 
 _git_exec_env_var="GIT_PYTHON_GIT_EXECUTABLE"