Start at moving tests for git module ⚡️

CHANGELOG.rst

@@ -8,6 +8,7 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`
 
 [unreleased]
 ------------
+- Test suite for git module (@lwasser, #448, #194)
 - Remove old unused code from before the big redirection (@kcranston, #449, #465)
 - Reoganize github module into smaller chunks (@kcranston, #447)
 - Check for working ssh keys before git commands that connect to github (@kcranston, #366)

abcclassroom/git.py

@@ -97,15 +97,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 = "git@github.com:{}/{}.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
 
 
@@ -149,14 +169,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"
@@ -180,7 +217,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",
@@ -190,7 +227,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(
@@ -201,16 +238,30 @@ 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)
 
 
 def push_to_github(directory, branch="main"):
-    """Push `branch` of the repository in `directory` back to GitHub"""
+    """Push `branch` of the repository in `directory` back to GitHub
+
+    Assumes git remotes are already setup.
+
+    Parameters
+    ----------
+    directory : PathLib Path object
+        A path to the local directory where the git repo of interest is saved.
+    branch : str
+        A string representing the branch that you wish to pull. Default = main
+
+    Returns
+    -------
+    Pushes any new commits to the repo locally to GitHub.
+    """
     try:
         # first, check that local git set up with ssh keys for github
         check_git_ssh()
@@ -221,8 +272,25 @@ def push_to_github(directory, branch="main"):
         raise e
 
 
+# TODO here we have a parameter called directory. I suspect that is actually
+# a URL to a git repo
 def pull_from_github(directory, branch="main"):
-    """Pull `branch` of local repo in `directory` from GitHub"""
+    """Pull `branch` of local repo in `directory` from GitHub.
+
+    Assumes git remotes are already setup.
+
+    Parameters
+    ----------
+    directory : PathLib Path object
+        A path to the local directory where the git repo of interest is saved.
+    branch : str
+        A string representing the branch that you wish to pull. Default = main
+
+    Returns
+    -------
+    Pulls any new commits to the repo from GitHub to local computer.
+
+    """
     try:
         # first, check that local git set up with ssh keys for github
         check_git_ssh()