TESTS: tests for git module ⚡️

abcclassroom/git.py

@@ -99,15 +99,35 @@ def clone_repo(organization, repo, dest_dir):
 
     Raises RuntimeError if ssh keys not set up correctly, or if git clone
     fails for other reasons.
+
+    Parameters
+    ----------
+    organization : string
+        A string with the name of the organization to clone from
+    repo : string
+        A string with the name of the GitHub repository to clone
+    dest_dir : string
+        Path to the destination directory
+        TODO: is this a full path, path object or string - what format is
+        dest_dir in
+    Returns
+    -------
+    Cloned github repository in the destination directory specified.
     """
 
     try:
         # first, check that local git set up with ssh keys for github
         check_git_ssh()
         url = "[email protected]:{}/{}.git".format(organization, repo)
-        print("cloning:", url)
+        print("Cloning:", url)
         _call_git("-C", dest_dir, "clone", url)
     except RuntimeError as e:
+        # TODO will this add too much feedback to running??
+        print(
+            r"Oops, something went wrong when cloning {}\{}: \n".format(
+                organization, repo
+            )
+        )
         raise e
 
 
@@ -122,6 +142,7 @@ def repo_changed(directory):
     return bool(ret.stdout)
 
 
+# TODO: DO WE USE THIS? i can't find it called anywhere
 def new_branch(directory, name=None):
     """Create a new git branch in directory"""
     if name is None:
@@ -164,14 +185,31 @@ def commit_all_changes(directory, msg=None):
         print("No changes in repository {}; doing nothing".format(directory))
 
 
+# TODO - are all directories in abc PATHLIB objects? and does full vs relative
+# paths matter and when? filling out docstrings but am unsure and need feedback
 def init_and_commit(directory, custom_message=False):
     """Run git init, git add, git commit on given directory. Checks git status
-    first and does nothing if no changes.
+    first and does nothing if no changes are detected.
+
+    Parameters
+    ----------
+    directory : Pathlib Path object?
+        A relative or full Path to the directory that needs to be
+        initialized via git init.
+    custom_message : str (defaults to default message - 'Initial commit')
+        String with a custom message if you wish the first commit to not be
+        the stock git init message provided by abc-classroom.
+
+    Returns
+    -------
+    Initializes the specified directory with a .git file and associated
+    tracking
     """
-    # local git things - initialize, add, commit
-    # note that running git init on an existing repo is safe, so no need
+    # Local git things - initialize, add, commit
+    # Running git init on an existing repo is safe, so no need
     # to check anything first
     git_init(directory)
+    print("Initializing", directory, "directory for you now.")
     _master_branch_to_main(directory)
     if repo_changed(directory):
         message = "Initial commit"
@@ -195,7 +233,7 @@ def _master_branch_to_main(dir):
     """
 
     try:
-        # first, verify if the  master branch exists (this is only true
+        # First, verify if the  master branch exists (this is only true
         # if there are commits on the master branch)
         _call_git(
             "show-ref",
@@ -205,7 +243,7 @@ def _master_branch_to_main(dir):
             directory=dir,
         )
     except RuntimeError:
-        # master branch verification fails, so we check for main and create
+        # Master branch verification fails, so we check for main and create
         # it if it does not exist
         try:
             _call_git(
@@ -216,10 +254,10 @@ def _master_branch_to_main(dir):
                 directory=dir,
             )
         except RuntimeError:
-            # no main branch, create one
+            # No main branch, create one
             _call_git("checkout", "-b", "main", directory=dir)
     else:
-        # rename branch
+        # Rename master to main
         print("master exists, renaming")
         _call_git("branch", "-m", "master", "main", directory=dir)