From d7b952e51b3d30e6cc95f322714661d8d2d8ee86 Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
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 <degeneracypressure@gmail.com>
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