Merge pull request gitpython-developers#1839 from EliahKagan/refresh-doc

Document manual refresh path treatment

git/__init__.py

@@ -120,7 +120,21 @@
 
 
 def refresh(path: Optional[PathLike] = None) -> None:
-    """Convenience method for setting the git executable path."""
+    """Convenience method for setting the git executable path.
+
+    :param path: Optional path to the Git executable. If not absolute, it is resolved
+        immediately, relative to the current directory.
+
+    :note: The *path* parameter is usually omitted and cannot be used to specify a
+        custom command whose location is looked up in a path search on each call. See
+        :meth:`Git.refresh` for details on how to achieve this.
+
+    :note: This calls :meth:`Git.refresh` and sets other global configuration according
+        to the effect of doing so. As such, this function should usually be used instead
+        of using :meth:`Git.refresh` or :meth:`FetchInfo.refresh` directly.
+
+    :note: This function is called automatically, with no arguments, at import time.
+    """
     global GIT_OK
     GIT_OK = False
 

git/cmd.py

@@ -350,6 +350,7 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
     for, which is not possible under most circumstances.
 
     See:
+
     - :meth:`Git.execute` (on the ``shell`` parameter).
     - https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a
     - https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
@@ -361,15 +362,50 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
     GIT_PYTHON_GIT_EXECUTABLE = None
     """Provide the full path to the git executable. Otherwise it assumes git is in the path.
 
-    Note that the git executable is actually found during the refresh step in
-    the top level ``__init__``.
+    :note: The git executable is actually found during the refresh step in
+        the top level :mod:`__init__`. It can also be changed by explicitly calling
+        :func:`git.refresh`.
     """
 
     _refresh_token = object()  # Since None would match an initial _version_info_token.
 
     @classmethod
     def refresh(cls, path: Union[None, PathLike] = None) -> bool:
-        """This gets called by the refresh function (see the top level __init__)."""
+        """This gets called by the refresh function (see the top level __init__).
+
+        :param path: Optional path to the git executable. If not absolute, it is
+            resolved immediately, relative to the current directory. (See note below.)
+
+        :note: The top-level :func:`git.refresh` should be preferred because it calls
+            this method and may also update other state accordingly.
+
+        :note: There are three different ways to specify what command refreshing causes
+            to be uses for git:
+
+            1. Pass no *path* argument and do not set the ``GIT_PYTHON_GIT_EXECUTABLE``
+               environment variable. The command name ``git`` is used. It is looked up
+               in a path search by the system, in each command run (roughly similar to
+               how git is found when running ``git`` commands manually). This is usually
+               the desired behavior.
+
+            2. Pass no *path* argument but set the ``GIT_PYTHON_GIT_EXECUTABLE``
+               environment variable. The command given as the value of that variable is
+               used. This may be a simple command or an arbitrary path. It is looked up
+               in each command run. Setting ``GIT_PYTHON_GIT_EXECUTABLE`` to ``git`` has
+               the same effect as not setting it.
+
+            3. Pass a *path* argument. This path, if not absolute, it immediately
+               resolved, relative to the current directory. This resolution occurs at
+               the time of the refresh, and when git commands are run, they are run with
+               that actual path. If a *path* argument is passed, the
+               ``GIT_PYTHON_GIT_EXECUTABLE`` environment variable is not consulted.
+
+        :note: Refreshing always sets the :attr:`Git.GIT_PYTHON_GIT_EXECUTABLE` class
+            attribute, which can be read on the :class:`Git` class or any of its
+            instances to check what command is used to run git. This attribute should
+            not be confused with the related ``GIT_PYTHON_GIT_EXECUTABLE`` environment
+            variable. The class attribute is set no matter how refreshing is performed.
+        """
         # Discern which path to refresh with.
         if path is not None:
             new_git = os.path.expanduser(path)