From d7b952e51b3d30e6cc95f322714661d8d2d8ee86 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 23 Feb 2024 01:13:45 -0500 Subject: [PATCH 1/2] Document manual refresh path treatment For #1831. --- git/__init__.py | 16 +++++++++++++++- git/cmd.py | 41 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 53 insertions(+), 4 deletions(-) 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 f58e6df5b..e7c12725d 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -355,13 +355,48 @@ 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`. """ @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) From e9da480a8cdecd28b2d5258c836f3c5aef190bde Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 23 Feb 2024 01:15:58 -0500 Subject: [PATCH 2/2] Fix USE_SHELL docstring reStructuredText list formatting --- git/cmd.py | 1 + 1 file changed, 1 insertion(+) diff --git a/git/cmd.py b/git/cmd.py index e7c12725d..e4054747b 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -344,6 +344,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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy