diff --git a/git/__init__.py b/git/__init__.py index c6a52ef30..0ea7821ac 100644 --- a/git/__init__.py +++ b/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 diff --git a/git/cmd.py b/git/cmd.py index bfc885222..7625357e8 100644 --- a/git/cmd.py +++ b/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)