GitPython 3.1.41__py3-none-any.whl → 3.1.43__py3-none-any.whl

{GitPython-3.1.41.dist-info → GitPython-3.1.43.dist-info}/AUTHORS

@@ -53,5 +53,6 @@ Contributors are:
 -Santos Gallegos <stsewd _at_ proton.me>
 -Wenhan Zhu <wzhu.cosmos _at_ gmail.com>
 -Eliah Kagan <eliah.kagan _at_ gmail.com>
+-Ethan Lin <et.repositories _at_ gmail.com>
 
 Portions derived from other open source works and are clearly marked.

{GitPython-3.1.41.dist-info → GitPython-3.1.43.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: GitPython
-Version: 3.1.41
+Version: 3.1.43
 Summary: GitPython is a Python library used to interact with Git repositories
 Home-page: https://github.com/gitpython-developers/GitPython
 Author: Sebastian Thiel, Michael Trier
@@ -29,8 +29,16 @@ License-File: LICENSE
 License-File: AUTHORS
 Requires-Dist: gitdb <5,>=4.0.1
 Requires-Dist: typing-extensions >=3.7.4.3 ; python_version < "3.8"
+Provides-Extra: doc
+Requires-Dist: sphinx ==4.3.2 ; extra == 'doc'
+Requires-Dist: sphinx-rtd-theme ; extra == 'doc'
+Requires-Dist: sphinxcontrib-applehelp <=1.0.4,>=1.0.2 ; extra == 'doc'
+Requires-Dist: sphinxcontrib-devhelp ==1.0.2 ; extra == 'doc'
+Requires-Dist: sphinxcontrib-htmlhelp <=2.0.1,>=2.0.0 ; extra == 'doc'
+Requires-Dist: sphinxcontrib-qthelp ==1.0.3 ; extra == 'doc'
+Requires-Dist: sphinxcontrib-serializinghtml ==1.1.5 ; extra == 'doc'
+Requires-Dist: sphinx-autodoc-typehints ; extra == 'doc'
 Provides-Extra: test
-Requires-Dist: black ; extra == 'test'
 Requires-Dist: coverage[toml] ; extra == 'test'
 Requires-Dist: ddt !=1.4.3,>=1.1.1 ; extra == 'test'
 Requires-Dist: mypy ; extra == 'test'
@@ -40,7 +48,7 @@ Requires-Dist: pytest-cov ; extra == 'test'
 Requires-Dist: pytest-instafail ; extra == 'test'
 Requires-Dist: pytest-mock ; extra == 'test'
 Requires-Dist: pytest-sugar ; extra == 'test'
-Requires-Dist: sumtypes ; extra == 'test'
+Requires-Dist: typing-extensions ; (python_version < "3.11") and extra == 'test'
 Requires-Dist: mock ; (python_version < "3.8") and extra == 'test'
 
 ![Python package](https://github.com/gitpython-developers/GitPython/workflows/Python%20package/badge.svg)
@@ -62,6 +70,8 @@ probably the skills to scratch that itch of mine: implement `git` in a way that
 If you like the idea and want to learn more, please head over to [gitoxide](https://github.com/Byron/gitoxide), an
 implementation of 'git' in [Rust](https://www.rust-lang.org).
 
+*(Please note that `gitoxide` is not currently available for use in Python, and that Rust is required.)*
+
 ## GitPython
 
 GitPython is a python library used to interact with git repositories, high-level like git-porcelain,
@@ -82,9 +92,9 @@ The project is open to contributions of all kinds, as well as new maintainers.
 
 ### REQUIREMENTS
 
-GitPython needs the `git` executable to be installed on the system and available in your `PATH` for most operations.
-If it is not in your `PATH`, you can help GitPython find it by setting
-the `GIT_PYTHON_GIT_EXECUTABLE=<path/to/git>` environment variable.
+GitPython needs the `git` executable to be installed on the system and available in your
+`PATH` for most operations. If it is not in your `PATH`, you can help GitPython find it
+by setting the `GIT_PYTHON_GIT_EXECUTABLE=<path/to/git>` environment variable.
 
 - Git (1.7.x or newer)
 - Python >= 3.7
@@ -100,7 +110,7 @@ GitPython and its required package dependencies can be installed in any of the f
 
 To obtain and install a copy [from PyPI](https://pypi.org/project/GitPython/), run:
 
-```bash
+```sh
 pip install GitPython
 ```
 
@@ -110,7 +120,7 @@ pip install GitPython
 
 If you have downloaded the source code, run this from inside the unpacked `GitPython` directory:
 
-```bash
+```sh
 pip install .
 ```
 
@@ -118,7 +128,7 @@ pip install .
 
 To clone the [the GitHub repository](https://github.com/gitpython-developers/GitPython) from source to work on the code, you can do it like so:
 
-```bash
+```sh
 git clone https://github.com/gitpython-developers/GitPython
 cd GitPython
 ./init-tests-after-clone.sh
@@ -128,7 +138,7 @@ On Windows, `./init-tests-after-clone.sh` can be run in a Git Bash shell.
 
 If you are cloning [your own fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks), then replace the above `git clone` command with one that gives the URL of your fork. Or use this [`gh`](https://cli.github.com/) command (assuming you have `gh` and your fork is called `GitPython`):
 
-```bash
+```sh
 gh repo clone GitPython
 ```
 
@@ -136,7 +146,7 @@ Having cloned the repo, create and activate your [virtual environment](https://d
 
 Then make an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs):
 
-```bash
+```sh
 pip install -e ".[test]"
 ```
 
@@ -148,7 +158,7 @@ In rare cases, you may want to work on GitPython and one or both of its [gitdb](
 
 If you want to do that *and* you want the versions in GitPython's git submodules to be used, then pass `-e git/ext/gitdb` and/or `-e git/ext/gitdb/gitdb/ext/smmap` to `pip install`. This can be done in any order, and in separate `pip install` commands or the same one, so long as `-e` appears before *each* path. For example, you can install GitPython, gitdb, and smmap editably in the currently active virtual environment this way:
 
-```bash
+```sh
 pip install -e ".[test]" -e git/ext/gitdb -e git/ext/gitdb/gitdb/ext/smmap
 ```
 
@@ -184,42 +194,38 @@ you will encounter test failures.
 
 Ensure testing libraries are installed. This is taken care of already if you installed with:
 
-```bash
+```sh
 pip install -e ".[test]"
 ```
 
-Otherwise, you can run:
-
-```bash
-pip install -r test-requirements.txt
-```
+If you had installed with a command like `pip install -e .` instead, you can still run
+the above command to add the testing dependencies.
 
 #### Test commands
 
 To test, run:
 
-```bash
+```sh
 pytest
 ```
 
-To lint, and apply automatic code formatting, run:
+To lint, and apply some linting fixes as well as automatic code formatting, run:
 
-```bash
+```sh
 pre-commit run --all-files
 ```
 
-- Linting without modifying code can be done with: `make lint`
-- Auto-formatting without other lint checks can be done with: `black .`
+This includes the linting and autoformatting done by Ruff, as well as some other checks.
 
 To typecheck, run:
 
-```bash
-mypy -p git
+```sh
+mypy
 ```
 
 #### CI (and tox)
 
-The same linting, and running tests on all the different supported Python versions, will be performed:
+Style and formatting checks, and running tests on all the different supported Python versions, will be performed:
 
 - Upon submitting a pull request.
 - On each push, *if* you have a fork with GitHub Actions enabled.
@@ -227,10 +233,12 @@ The same linting, and running tests on all the different supported Python versio
 
 #### Configuration files
 
-Specific tools:
+Specific tools are all configured in the `./pyproject.toml` file:
 
-- Configurations for `mypy`, `pytest`, `coverage.py`, and `black` are in `./pyproject.toml`.
-- Configuration for `flake8` is in the `./.flake8` file.
+- `pytest` (test runner)
+- `coverage.py` (code coverage)
+- `ruff` (linter and formatter)
+- `mypy` (type checker)
 
 Orchestration tools:
 
@@ -265,57 +273,6 @@ Please have a look at the [contributions file][contributing].
 6. Run `make release`.
 7. Go to [GitHub Releases](https://github.com/gitpython-developers/GitPython/releases) and publish a new one with the recently pushed tag. Generate the changelog.
 
-### How to verify a release (DEPRECATED)
-
-Note that what follows is deprecated and future releases won't be signed anymore.
-More details about how it came to that can be found [in this issue](https://github.com/gitpython-developers/gitdb/issues/77).
-
-----
-
-Please only use releases from `pypi` as you can verify the respective source
-tarballs.
-
-This script shows how to verify the tarball was indeed created by the authors of
-this project:
-
-```bash
-curl https://files.pythonhosted.org/packages/09/bc/ae32e07e89cc25b9e5c793d19a1e5454d30a8e37d95040991160f942519e/GitPython-3.1.8-py3-none-any.whl > gitpython.whl
-curl https://files.pythonhosted.org/packages/09/bc/ae32e07e89cc25b9e5c793d19a1e5454d30a8e37d95040991160f942519e/GitPython-3.1.8-py3-none-any.whl.asc >  gitpython-signature.asc
-gpg --verify gitpython-signature.asc gitpython.whl
-```
-
-which outputs
-
-```bash
-gpg: Signature made Fr  4 Sep 10:04:50 2020 CST
-gpg:                using RSA key 27C50E7F590947D7273A741E85194C08421980C9
-gpg: Good signature from "Sebastian Thiel (YubiKey USB-C) <byronimo@gmail.com>" [ultimate]
-gpg:                 aka "Sebastian Thiel (In Rust I trust) <sebastian.thiel@icloud.com>" [ultimate]
-```
-
-You can verify that the keyid indeed matches the release-signature key provided in this
-repository by looking at the keys details:
-
-```bash
-gpg --list-packets ./release-verification-key.asc
-```
-
-You can verify that the commit adding it was also signed by it using:
-
-```bash
-git show --show-signature  ./release-verification-key.asc
-```
-
-If you would like to trust it permanently, you can import and sign it:
-
-```bash
-gpg --import ./release-verification-key.asc
-gpg --edit-key 4C08421980C9
-
-> sign
-> save
-```
-
 ### Projects using GitPython
 
 - [PyDriller](https://github.com/ishepard/pydriller)

GitPython-3.1.43.dist-info/RECORD

@@ -0,0 +1,44 @@
+git/__init__.py,sha256=w6fnS0QmwTfEFUSL6rfnpP0lUId2goSguZFOvVX3N3U,8899
+git/cmd.py,sha256=qd-gIHSk4mfsYjd9YA08cPyO8TMxaibTXAbFnHK71uc,67659
+git/compat.py,sha256=y1E6y6O2q5r8clSlr8ZNmuIWG9nmHuehQEsVsmBffs8,4526
+git/config.py,sha256=Ald8Xc-G9Shcgx3QCISyXTkL4a6nbc3qll-xUw4YdyY,34924
+git/db.py,sha256=vIW9uWSbqu99zbuU2ZDmOhVOv1UPTmxrnqiCtRHCfjE,2368
+git/diff.py,sha256=IE5aeHL7aP9yxBluYj06IX8nZjoJ_TOM3gG31-Evf_8,27058
+git/exc.py,sha256=Gc7g1pHpn8OmTse30NHmJVsBJ2CYH8LxaR8y8UA3lIM,7119
+git/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git/remote.py,sha256=IHQ3BvXgoIN1EvHlyH3vrSaQoDkLOE6nooSC0w183sU,46561
+git/types.py,sha256=xCwpp2Y01lhS0MapHhj04m0P_x34kwSD1Gsou_ZPWj8,10251
+git/util.py,sha256=1E883mnPAFLyFk7ivwnEremsp-uJOTc3ks_QypyLung,43651
+git/index/__init__.py,sha256=i-Nqb8Lufp9aFbmxpQBORmmQnjEVVM1Pn58fsQkyGgQ,406
+git/index/base.py,sha256=A4q4cN_Ifxi8CsAR-7h4KsQ2d3JazBNFZ1ltbAKttgs,60734
+git/index/fun.py,sha256=37cA3DBC9vpAnSVu5TGA072SnoF5XZOkOukExwlejHs,16736
+git/index/typ.py,sha256=uuKNwitUw83FhVaLSwo4pY7PHDQudtZTLJrLGym4jcI,6570
+git/index/util.py,sha256=fULi7GPG-MvprKrRCD5c15GNdzku_1E38We0d97WB3A,3659
+git/objects/__init__.py,sha256=O6ZL_olX7e5-8iIbKviRPkVSJxN37WA-EC0q9d48U5Y,637
+git/objects/base.py,sha256=0dqNkSRVH0mk0-7ZKIkGBK7iNYrzLTVxwQFUd6CagsE,10277
+git/objects/blob.py,sha256=zwwq0KfOMYeP5J2tW5CQatoLyeqFRlfkxP1Vwx1h07s,1215
+git/objects/commit.py,sha256=vLZNl1I9zp17Rpge7J66CvsryirEs90jyPTQzoP0JJs,30208
+git/objects/fun.py,sha256=B4jCqhAjm6Hl79GK58FPzW1H9K6Wc7Tx0rssyWmAcEE,8935
+git/objects/tag.py,sha256=gAx8i-DEwy_Z3R2zLkvetYRV8A56BCcTr3iLuTUTfEM,4467
+git/objects/tree.py,sha256=jJH888SHiP4dGzE-ra1yenQOyya_0C_MkHr06c1gHpM,13849
+git/objects/util.py,sha256=Ml2eqZPKO4y9Hc2vWbXJgpsK3nkN3KGMzbn8AlzLyYQ,23834
+git/objects/submodule/__init__.py,sha256=6xySp767LVz3UylWgUalntS_nGXRuVzXxDuFAv_Wc2c,303
+git/objects/submodule/base.py,sha256=MQ-2xV8JznGwy2hLQv1aeQNgAkhBhgc5tdtClFL3DmE,63901
+git/objects/submodule/root.py,sha256=5eTtYNHasqdPq6q0oDCPr7IaO6uAHL3b4DxMoiO2LhE,20246
+git/objects/submodule/util.py,sha256=sQqAYaiSJdFkZa9NlAuK_wTsMNiS-kkQnQjvIoJtc_o,3509
+git/refs/__init__.py,sha256=DWlJNnsx-4jM_E-VycbP-FZUdn6iWhjnH_uZ_pZXBro,509
+git/refs/head.py,sha256=GAZpD5EfqSciDXPtgjHY8ZbBixKExJRhojUB-HrrJPg,10491
+git/refs/log.py,sha256=kXiuAgTo1DIuM_BfbDUk9gQ0YO-mutIMVdHv1_ES90o,12493
+git/refs/reference.py,sha256=l6mhF4YLSEwtjz6b9PpOQH-fkng7EYWMaJhkjn-2jXA,5630
+git/refs/remote.py,sha256=WwqV9T7BbYf3F_WZNUQivu9xktIIKGklCjDpwQrhD-A,2806
+git/refs/symbolic.py,sha256=c8zOwaqzcg-J-rGrpuWdvh8zwMvSUqAHghd4vJoYG_s,34552
+git/refs/tag.py,sha256=kgzV2vhpL4FD2TqHb0BJuMRAHgAvJF-TcoyWlaB-djQ,5010
+git/repo/__init__.py,sha256=CILSVH36fX_WxVFSjD9o1WF5LgsNedPiJvSngKZqfVU,210
+git/repo/base.py,sha256=mitfJ8u99CsMpDd7_VRyx-SF8omu2tpf3lqzSaQkKoQ,59353
+git/repo/fun.py,sha256=tEsClpmbOrKMSNIdncOB_6JdikrL1-AfkOFd7xMpD8k,13582
+GitPython-3.1.43.dist-info/AUTHORS,sha256=h1TlPKfp05GA1eKQ15Yl4biR0C0FgivuGSeRA6Q1dz0,2286
+GitPython-3.1.43.dist-info/LICENSE,sha256=hvyUwyGpr7wRUUcTURuv3tIl8lEA3MD3NQ6CvCMbi-s,1503
+GitPython-3.1.43.dist-info/METADATA,sha256=sAh3r1BMVw5_olGgDmpMS69zBpVr7UEOeRivNHKznfU,13376
+GitPython-3.1.43.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+GitPython-3.1.43.dist-info/top_level.txt,sha256=0hzDuIp8obv624V3GmbqsagBWkk8ohtGU-Bc1PmTT0o,4
+GitPython-3.1.43.dist-info/RECORD,,

{GitPython-3.1.41.dist-info → GitPython-3.1.43.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: bdist_wheel (0.43.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

git/__init__.py

@@ -5,39 +5,7 @@
 
 # @PydevCodeAnalysisIgnore
 
-__version__ = '3.1.41'
-
-from typing import List, Optional, Sequence, Tuple, Union, TYPE_CHECKING
-
-from gitdb.util import to_hex_sha
-from git.exc import *  # noqa: F403  # @NoMove @IgnorePep8
-from git.types import PathLike
-
-try:
-    from git.compat import safe_decode  # @NoMove @IgnorePep8
-    from git.config import GitConfigParser  # @NoMove @IgnorePep8
-    from git.objects import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.refs import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.diff import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.db import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.cmd import Git  # @NoMove @IgnorePep8
-    from git.repo import Repo  # @NoMove @IgnorePep8
-    from git.remote import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.index import *  # noqa: F403  # @NoMove @IgnorePep8
-    from git.util import (  # @NoMove @IgnorePep8
-        LockFile,
-        BlockingLockFile,
-        Stats,
-        Actor,
-        remove_password_if_present,
-        rmtree,
-    )
-except GitError as _exc:  # noqa: F405
-    raise ImportError("%s: %s" % (_exc.__class__.__name__, _exc)) from _exc
-
-# __all__ must be statically defined by py.typed support
-# __all__ = [name for name, obj in locals().items() if not (name.startswith("_") or inspect.ismodule(obj))]
-__all__ = [  # noqa: F405
+__all__ = [
     "Actor",
     "AmbiguousObjectName",
     "BadName",
@@ -52,6 +20,7 @@ __all__ = [  # noqa: F405
     "CommandError",
     "Commit",
     "Diff",
+    "DiffConstants",
     "DiffIndex",
     "Diffable",
     "FetchInfo",
@@ -65,18 +34,19 @@ __all__ = [  # noqa: F405
     "HEAD",
     "Head",
     "HookExecutionError",
+    "INDEX",
     "IndexEntry",
     "IndexFile",
     "IndexObject",
     "InvalidDBRoot",
     "InvalidGitRepositoryError",
-    "List",
+    "List",  # Deprecated - import this from `typing` instead.
     "LockFile",
     "NULL_TREE",
     "NoSuchPathError",
     "ODBError",
     "Object",
-    "Optional",
+    "Optional",  # Deprecated - import this from `typing` instead.
     "ParseError",
     "PathLike",
     "PushInfo",
@@ -90,54 +60,241 @@ __all__ = [  # noqa: F405
     "RepositoryDirtyError",
     "RootModule",
     "RootUpdateProgress",
-    "Sequence",
+    "Sequence",  # Deprecated - import from `typing`, or `collections.abc` in 3.9+.
     "StageType",
     "Stats",
     "Submodule",
     "SymbolicReference",
-    "TYPE_CHECKING",
+    "TYPE_CHECKING",  # Deprecated - import this from `typing` instead.
     "Tag",
     "TagObject",
     "TagReference",
     "Tree",
     "TreeModifier",
-    "Tuple",
-    "Union",
+    "Tuple",  # Deprecated - import this from `typing` instead.
+    "Union",  # Deprecated - import this from `typing` instead.
     "UnmergedEntriesError",
     "UnsafeOptionError",
     "UnsafeProtocolError",
     "UnsupportedOperation",
     "UpdateProgress",
     "WorkTreeRepositoryUnsupported",
+    "refresh",
     "remove_password_if_present",
     "rmtree",
     "safe_decode",
     "to_hex_sha",
 ]
 
+__version__ = '3.1.43'
+
+from typing import Any, List, Optional, Sequence, TYPE_CHECKING, Tuple, Union
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+import warnings
+
+from gitdb.util import to_hex_sha
+
+from git.exc import (
+    AmbiguousObjectName,
+    BadName,
+    BadObject,
+    BadObjectType,
+    CacheError,
+    CheckoutError,
+    CommandError,
+    GitCommandError,
+    GitCommandNotFound,
+    GitError,
+    HookExecutionError,
+    InvalidDBRoot,
+    InvalidGitRepositoryError,
+    NoSuchPathError,
+    ODBError,
+    ParseError,
+    RepositoryDirtyError,
+    UnmergedEntriesError,
+    UnsafeOptionError,
+    UnsafeProtocolError,
+    UnsupportedOperation,
+    WorkTreeRepositoryUnsupported,
+)
+from git.types import PathLike
+
+try:
+    from git.compat import safe_decode  # @NoMove
+    from git.config import GitConfigParser  # @NoMove
+    from git.objects import (  # @NoMove
+        Blob,
+        Commit,
+        IndexObject,
+        Object,
+        RootModule,
+        RootUpdateProgress,
+        Submodule,
+        TagObject,
+        Tree,
+        TreeModifier,
+        UpdateProgress,
+    )
+    from git.refs import (  # @NoMove
+        HEAD,
+        Head,
+        RefLog,
+        RefLogEntry,
+        Reference,
+        RemoteReference,
+        SymbolicReference,
+        Tag,
+        TagReference,
+    )
+    from git.diff import (  # @NoMove
+        INDEX,
+        NULL_TREE,
+        Diff,
+        DiffConstants,
+        DiffIndex,
+        Diffable,
+    )
+    from git.db import GitCmdObjectDB, GitDB  # @NoMove
+    from git.cmd import Git  # @NoMove
+    from git.repo import Repo  # @NoMove
+    from git.remote import FetchInfo, PushInfo, Remote, RemoteProgress  # @NoMove
+    from git.index import (  # @NoMove
+        BaseIndexEntry,
+        BlobFilter,
+        CheckoutError,
+        IndexEntry,
+        IndexFile,
+        StageType,
+        # NOTE: This tells type checkers what util resolves to. We delete it, and it is
+        # really resolved by __getattr__, which warns. See below on what to use instead.
+        util,
+    )
+    from git.util import (  # @NoMove
+        Actor,
+        BlockingLockFile,
+        LockFile,
+        Stats,
+        remove_password_if_present,
+        rmtree,
+    )
+except GitError as _exc:
+    raise ImportError("%s: %s" % (_exc.__class__.__name__, _exc)) from _exc
+
+
+def _warned_import(message: str, fullname: str) -> "ModuleType":
+    import importlib
+
+    warnings.warn(message, DeprecationWarning, stacklevel=3)
+    return importlib.import_module(fullname)
+
+
+def _getattr(name: str) -> Any:
+    # TODO: If __version__ is made dynamic and lazily fetched, put that case right here.
+
+    if name == "util":
+        return _warned_import(
+            "The expression `git.util` and the import `from git import util` actually "
+            "reference git.index.util, and not the git.util module accessed in "
+            '`from git.util import XYZ` or `sys.modules["git.util"]`. This potentially '
+            "confusing behavior is currently preserved for compatibility, but may be "
+            "changed in the future and should not be relied on.",
+            fullname="git.index.util",
+        )
+
+    for names, prefix in (
+        ({"head", "log", "reference", "symbolic", "tag"}, "git.refs"),
+        ({"base", "fun", "typ"}, "git.index"),
+    ):
+        if name not in names:
+            continue
+
+        fullname = f"{prefix}.{name}"
+
+        return _warned_import(
+            f"{__name__}.{name} is a private alias of {fullname} and subject to "
+            f"immediate removal. Use {fullname} instead.",
+            fullname=fullname,
+        )
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+if not TYPE_CHECKING:
+    # NOTE: The expression `git.util` gives git.index.util and `from git import util`
+    # imports git.index.util, NOT git.util. It may not be feasible to change this until
+    # the next major version, to avoid breaking code inadvertently relying on it.
+    #
+    # - If git.index.util *is* what you want, use (or import from) that, to avoid
+    #   confusion.
+    #
+    # - To use the "real" git.util module, write `from git.util import ...`, or if
+    #   necessary access it as `sys.modules["git.util"]`.
+    #
+    # Note also that `import git.util` technically imports the "real" git.util... but
+    # the *expression* `git.util` after doing so is still git.index.util!
+    #
+    # (This situation differs from that of other indirect-submodule imports that are
+    # unambiguously non-public and subject to immediate removal. Here, the public
+    # git.util module, though different, makes less discoverable that the expression
+    # `git.util` refers to a non-public attribute of the git module.)
+    #
+    # This had originally come about by a wildcard import. Now that all intended imports
+    # are explicit, the intuitive but potentially incompatible binding occurs due to the
+    # usual rules for Python submodule bindings. So for now we replace that binding with
+    # git.index.util, delete that, and let __getattr__ handle it and issue a warning.
+    #
+    # For the same runtime behavior, it would be enough to forgo importing util, and
+    # delete util as created naturally; __getattr__ would behave the same. But type
+    # checkers would not know what util refers to when accessed as an attribute of git.
+    del util
+
+    # This is "hidden" to preserve static checking for undefined/misspelled attributes.
+    __getattr__ = _getattr
+
 # { Initialize git executable path
+
 GIT_OK = None
 
 
 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 <git.cmd.Git.refresh>` for details on how to achieve this.
+
+    :note:
+        This calls :meth:`Git.refresh <git.cmd.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 <git.cmd.Git.refresh>` or
+        :meth:`FetchInfo.refresh <git.remote.FetchInfo.refresh>` directly.
+
+    :note:
+        This function is called automatically, with no arguments, at import time.
+    """
     global GIT_OK
     GIT_OK = False
 
     if not Git.refresh(path=path):
         return
     if not FetchInfo.refresh():  # noqa: F405
-        return  # type: ignore [unreachable]
+        return  # type: ignore[unreachable]
 
     GIT_OK = True
 
 
-# } END initialize git executable path
-
-
-#################
 try:
     refresh()
 except Exception as _exc:
     raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc
-#################
+
+# } END initialize git executable path