Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Pre-deprecate setting Git.USE_SHELL #1782

Merged
merged 2 commits into from
Dec 24, 2023
Merged

Pre-deprecate setting Git.USE_SHELL #1782

merged 2 commits into from
Dec 24, 2023

Commits on Dec 22, 2023

  1. Convert constant and attribute comments to docstrings 

    These are "non-reified docstrings" as described in gitpython-developers#1734. They are
not made part of the data model, but most editors will display
them, including on symbols present in code of other projects that
use the GitPython library. A number of these have already been
added, but this adds what will probably be most of the remaining
ones.

For the most part, this doesn't create documentation where there
wasn't any, but instead converts existing comments to "docstrings."
In a handful of cases, they are expanded, reworded, or a docstring
added.

This also fixes some small style inconsistencies that were missed
in gitpython-developers#1725, and moves a comment that had become inadvertently
displaced due to autoformatting to the item it was meant for.

The major omission here is HIDE_WINDOWS_KNOWN_ERRORS and
HIDE_WINDOWS_FREEZE_ERRORS. This doesn't convert the comments above
them to "docstrings," for a few reasons. They are not specific to
either of the symbols, they are oriented toward considerations that
are not really relevant except when developing GitPython itself,
and they are out of date. Also, because HIDE_WINDOWS_KNOWN_ERRORS
is listed in __all__, increasing the level of documentation for it
might be taken as a committment to preserve some aspect of its
current behavior, which could interfere with progress on gitpython-developers#790. So
I've kept those comments as comments, and unchanged, for now.
    @EliahKagan
    EliahKagan committed Dec 22, 2023
    Configuration menu
    Copy the full SHA
    94a85d1 View commit details
    Browse the repository at this point in the history

  2. 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 gitpython-developers#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`.
    @EliahKagan
    EliahKagan committed Dec 22, 2023
    Configuration menu
    Copy the full SHA
    106bbe6 View commit details
    Browse the repository at this point in the history