Fixes #1831
I've proposed some expansions of the git.refresh and git.cmd.Git.refresh docstrings to explain how they set the git command to be used, including how they set paths and how this differs between the different ways they are called. A small amount of information about other aspects is also added.
This may reasonable to merge, but it may alternatively need editing. I am unsure if the most important points are clear enough. I also wonder if this can be made shorter. I'd be pleased to make further changes.
Some of the information is duplicated across those two refresh functions' docstrings. I did this because, while as argued in #1831 I don't think this is fixing a security bug in GitPython, there are security implications of an application (or other library) using GitPython getting this wrong.
Because the text is already longer than I'd like, and because I think it's more important to describe the behavior than to comment on its relevance to security, I have not mentioned security (or safety, etc.) in added text in the docstrings. I am unsure if this is the best choice. It can be contrasted to the more explicitly cautionary tone taken in the USE_SHELL docstring.
I put more information in the git.cmd.Git.refresh docstring. leaving the git.refresh docstring less detailed. This is for two reasons. First, it is about the behavior that is part of git.cmd.Git.refresh specifically. Second, when I generate the documentation locally, the API reference doesn't seem to contain anything for the top-level git.refresh function that is what people should actually call (if they call any refresh functions). Putting the details in the git.cmd.Git.refresh docstring should make it available, assuming a documentation build that is overall working for generating the API reference (see #1840).
While working on this, I noticed that, in the docstring for USE_SHELL, I had written broken reStructuredText for the unordered list. In my locally generated documentation, the list was run on as a continuous paragraph. The second commit here fixes that.
%5D(https%3A%2F%2Frenovatebot.com){kind=link}