Fully qualify non-builtin exceptions in :raise:

This expands exceptions from git.exc and gitdb.exc in :raise:
sections of docstrings, to include those qualifiers.

This serves a few purposes. The main benefits are:

- Immediately clarify which exceptions are not built-in ones, as
  not all readers are necessarily familiar with all built-in
  exceptions.

- Distinguish exceptions defined in GitPython (in git.exc) from
  those defined in gitdb (in gitdb.exc). Although the gitdb
  exceptions GitPython uses are imported into git.exc and listed
  in __all__, they are still not introduced in GitPython, which is
  relevant for (a) preventing confusion, so developers don't think
  they accidentally imported a different same-named exception,
  (b) understanding why they do not have documentation in the
  generated GitPython docs.

It also has these minor benefits:

- May help sphinx-autodoc find them. In practice I think this is
  unlikely to be necessary.

- Most other references, including references to classes, within
  docstrings in the git module, are now fully qualified, when not
  defined/introduced in the same module. So this is consistent with
  that. This consistency might be more than a minor benefit if
  there were a committment to keep most such refernces fully
  qualified, but this really should not be a goal: especially where
  Sphinx autodoc is guaranteed to be able to resolve them,
  shortening (in some cases, re-shortening) the references in the
  future may lead to better docstring readability.

Author: EliahKagan

git/cmd.py

@@ -699,7 +699,7 @@ def wait(self, stderr: Union[None, str, bytes] = b"") -> int:
                 May deadlock if output or error pipes are used and not handled
                 separately.
 
-            :raise GitCommandError:
+            :raise git.exc.GitCommandError:
                 If the return status is not 0.
             """
             if stderr is None:
@@ -1091,7 +1091,7 @@ def execute(
             Note that git is executed with ``LC_MESSAGES="C"`` to ensure consistent
             output regardless of system language.
 
-        :raise GitCommandError:
+        :raise git.exc.GitCommandError:
 
         :note:
            If you add additional keyword arguments to the signature of this method,

git/db.py

@@ -56,13 +56,13 @@ def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
         """
         :return: Full binary 20 byte sha from the given partial hexsha
 
-        :raise AmbiguousObjectName:
+        :raise gitdb.exc.AmbiguousObjectName:
 
-        :raise BadObject:
+        :raise gitdb.exc.BadObject:
 
         :note:
-            Currently we only raise :class:`BadObject` as git does not communicate
-            ambiguous objects separately.
+            Currently we only raise :class:`~gitdb.exc.BadObject` as git does not
+            communicate ambiguous objects separately.
         """
         try:
             hexsha, _typename, _size = self._git.get_object_header(partial_hexsha)

git/index/base.py

@@ -284,7 +284,7 @@ def merge_tree(self, rhs: Treeish, base: Union[None, Treeish] = None) -> "IndexF
             self (containing the merge and possibly unmerged entries in case of
             conflicts)
 
-        :raise GitCommandError:
+        :raise git.exc.GitCommandError:
             If there is a merge conflict. The error will be raised at the first
             conflicting path. If you want to have proper merge resolution to be done by
             yourself, you have to commit the changed index (or make a valid tree from
@@ -624,7 +624,7 @@ def write_tree(self) -> Tree:
         :raise ValueError:
             If there are no entries in the cache.
 
-        :raise UnmergedEntriesError:
+        :raise git.exc.UnmergedEntriesError:
         """
         # We obtain no lock as we just flush our contents to disk as tree.
         # If we are a new index, the entries access will load our data accordingly.
@@ -1077,7 +1077,7 @@ def move(
         :raise ValueError:
             If only one item was given.
 
-        :raise GitCommandError:
+        :raise git.exc.GitCommandError:
             If git could not handle your request.
         """
         args = []

git/index/fun.py

@@ -88,7 +88,7 @@ def run_commit_hook(name: str, index: "IndexFile", *args: str) -> None:
     :param args:
         Arguments passed to hook file.
 
-    :raise HookExecutionError:
+    :raise git.exc.HookExecutionError:
     """
     hp = hook_path(name, index.repo.git_dir)
     if not os.access(hp, os.X_OK):

git/objects/submodule/base.py

@@ -1106,7 +1106,7 @@ def remove(
             Doesn't work atomically, as failure to remove any part of the submodule will
             leave an inconsistent state.
 
-        :raise InvalidGitRepositoryError:
+        :raise git.exc.InvalidGitRepositoryError:
             Thrown if the repository cannot be deleted.
 
         :raise OSError:
@@ -1382,7 +1382,7 @@ def module(self) -> "Repo":
         """
         :return: Repo instance initialized from the repository at our submodule path
 
-        :raise InvalidGitRepositoryError:
+        :raise git.exc.InvalidGitRepositoryError:
             If a repository was not available.
             This could also mean that it was not yet initialized.
         """
@@ -1454,7 +1454,7 @@ def branch(self) -> "Head":
         :return:
             The branch instance that we are to checkout
 
-        :raise InvalidGitRepositoryError:
+        :raise git.exc.InvalidGitRepositoryError:
             If our module is not yet checked out.
         """
         return mkhead(self.module(), self._branch_path)

git/remote.py

@@ -801,7 +801,7 @@ def create(cls, repo: "Repo", name: str, url: str, allow_unsafe_protocols: bool
         :return:
             New :class:`Remote` instance
 
-        :raise GitCommandError:
+        :raise git.exc.GitCommandError:
             In case an origin with that name already exists.
         """
         scmd = "add"

git/repo/base.py

@@ -202,12 +202,12 @@ def __init__(
             Please note that this was the default behaviour in older versions of
             GitPython, which is considered a bug though.
 
-        :raise InvalidGitRepositoryError:
+        :raise git.exc.InvalidGitRepositoryError:
 
-        :raise NoSuchPathError:
+        :raise git.exc.NoSuchPathError:
 
         :return:
-            git.Repo
+            :class:`Repo`
         """
 
         epath = path or os.getenv("GIT_DIR")
@@ -893,7 +893,7 @@ def _set_alternates(self, alts: List[str]) -> None:
             The array of string paths representing the alternates at which git should
             look for objects, i.e. ``/home/user/repo/.git/objects``.
 
-        :raise NoSuchPathError:
+        :raise git.exc.NoSuchPathError:
 
         :note:
             The method does not check for the existence of the paths in `alts`, as the
@@ -1553,7 +1553,7 @@ def archive(
               repository-relative path to a directory or file to place into the archive,
               or a list or tuple of multiple paths.
 
-        :raise GitCommandError:
+        :raise git.exc.GitCommandError:
             If something went wrong.
 
         :return:

git/repo/fun.py

@@ -59,7 +59,7 @@ def touch(filename: str) -> str:
 def is_git_dir(d: "PathLike") -> bool:
     """This is taken from the git setup.c:is_git_directory function.
 
-    :raise WorkTreeRepositoryUnsupported:
+    :raise git.exc.WorkTreeRepositoryUnsupported:
         If it sees a worktree directory. It's quite hacky to do that here, but at least
         clearly indicates that we don't support it. There is the unlikely danger to
         throw if we see directories which just look like a worktree dir, but are none.
@@ -234,7 +234,7 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
         ``git rev-parse``-compatible revision specification as string. Please see
         http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html for details.
 
-    :raise BadObject:
+    :raise gitdb.exc.BadObject:
         If the given revision could not be found.
 
     :raise ValueError: