Added git utilities.

Author: eriq-augustine

edq/util/git.py

@@ -0,0 +1,113 @@
+"""
+Handle interfacing with git repos.
+"""
+
+import os
+import re
+import typing
+
+import git
+
+UNKNOWN_VERSION: str = 'UNKNOWN'
+VERSION_LEN: int = 8
+DIRTY_SIFFIX: str = '-d'
+
+def get_version(path: str = '.', throw: bool = False) -> str:
+    """
+    Get a version string from the git repo.
+    This is just a commit hash with some dressup.
+    """
+
+    if (os.path.isfile(path)):
+        path = os.path.dirname(path)
+
+    try:
+        repo = git.Repo(path, search_parent_directories = True)
+        version = repo.head.commit.tree.hexsha[:VERSION_LEN]
+    except Exception as ex:
+        if (throw):
+            raise ValueError(f"Path '{path}' is not a valid Git repo.") from ex
+
+        return UNKNOWN_VERSION
+
+    if (repo.is_dirty()):
+        version += DIRTY_SIFFIX
+
+    return version
+
+def ensure_repo(
+        url: str,
+        path: str,
+        username: typing.Union[str, None] = None,
+        token: typing.Union[str, None] = None,
+        update: bool = False,
+        ref: typing.Union[str, None] = None,
+        ) -> None:
+    """
+    Ensure that a git repo exists locally.
+    Clone the repo if it does not exist.
+    Optionally update (pull) the repo.
+    """
+
+    if (os.path.isfile(path)):
+        raise ValueError(f"Target git path exists and is a file: '{path}'.")
+
+    if (not os.path.exists(path)):
+        clone(url, path, username = username, token = token)
+
+    repo = get_repo(path)
+
+    if (update):
+        update_repo(repo)
+
+    if (ref is not None):
+        checkout_repo(repo, ref)
+
+def get_repo(path: str) -> git.Repo:
+    """ Get a reference to a git repo. """
+
+    return git.Repo(path)
+
+def clone(
+        url: str,
+        path: str,
+        username: typing.Union[str, None] = None,
+        token: typing.Union[str, None] = None,
+        ) -> git.Repo:
+    """ Clone a git repo to the target location and return a reference to it. """
+
+    # If we have a username or password, we need to rewrite the URL.
+    # This is not very robust, but should work.
+    # After clone, the credentials are saved in the local git config.
+    if (username is not None):
+        if (token is None):
+            raise ValueError("If username is specified, a token must also be specified.")
+
+        auth_text = f"{username}:{token}"
+        url = re.sub(r'(http(s?)://)', rf"\1{auth_text}@", url)
+
+    return git.Repo.clone_from(url, path)
+
+def checkout_repo(repo: git.Repo, ref: str) -> None:
+    """ Checkout the given reference on the given repo. """
+
+    repo.git.checkout(ref)
+
+def update_repo(repo: git.Repo) -> bool:
+    """
+    Update (pull) the given repo.
+    Return true if an update occurred.
+    """
+
+    fetch_results = repo.remotes.origin.pull()
+
+    for fetch_result in fetch_results:
+        if (fetch_result.ref.name != f"origin/{repo.active_branch.name}"):
+            continue
+
+        if (fetch_result.flags == git.remote.FetchInfo.HEAD_UPTODATE):
+            return False
+
+        return True
+
+    return False

edq/util/git_test.py

@@ -0,0 +1,29 @@
+import os
+
+import edq.testing.unittest
+import edq.util.dirent
+import edq.util.git
+
+THIS_DIR = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+
+class TestGit(edq.testing.unittest.BaseTest):
+    """ Test git functionality. """
+
+    def test_version_in_repo(self):
+        """ Test getting a git version inside of a repo. """
+
+        version = edq.util.git.get_version(THIS_DIR)
+        self.assertNotEqual(edq.util.git.UNKNOWN_VERSION, version, 'Got an unknown version (assumes test is run in a repo).')
+
+    def test_version_cwd(self):
+        """ Test getting a git version using the current working directory. """
+
+        version = edq.util.git.get_version()
+        self.assertNotEqual(edq.util.git.UNKNOWN_VERSION, version, 'Got an unknown version (assumes test is run in a repo)')
+
+    def test_version_not_in_repo(self):
+        """ Test getting a git version when not inside of a repo. """
+
+        path = edq.util.dirent.get_temp_path(prefix = 'edq-test-git-')
+        version = edq.util.git.get_version(path)
+        self.assertEqual(edq.util.git.UNKNOWN_VERSION, version)

requirements.txt

@@ -1,3 +1,4 @@
+GitPython>=3.1.31
 beautifulsoup4>=4.10.0
 json5>=0.9.14
 platformdirs