Miscellaneous Git Functions

Since the majority of assignment submissions rely on the presence of a git repository, this module contains a number of helper functions for interacting with GitPython, and thus git.

is_clean(repo: Repo, boolean_output: bool = False) → Tuple[List[str], List[str], List[str]] | bool

Determine if the repository has a clean working tree.

Returns a Tuple of two values;

1. A list of the untracked files in the repository.

2. A list of the changed files in the repository.

In the event that boolean_output is True, instead just returns True/False if the repository is clean/unclean.

is_git_repo(git_root_dir: Path) → bool

Returns True if a valid git repository is found at the directory provided, and False otherwise.

locate_repo_in_tree(search_root: Path) → Path

Given a root folder to search from, recurse through the directory tree from this location and return the path to the first git repository that is found.

If no repository is found, the return value is None.

switch_if_safe(repo: Repo, to_branch: str, create: bool = False) → None

Switch to the given reference using git switch.

If the reference doesn’t exist, passing the “create” flag will create the branch and switch to it. Otherwise, an error will be raised via reporting the invalid reference.

switch_to_main_if_possible(repo: Repo, *allowable_other_names: str) → str

Switches the main branch in the repo, if this is possible.

If the main branch doesn’t exist, the method will attempt to switch to the allowable other names, in the order they are provided. It will switch to the first name that it finds a reference to.

The returned value will be a string that describes any non-fatal warnings that were encountered when trying to switch the repository to the desired branch. Specifically: - If the repository was not already on the main branch. - If the repository has no main branch, but did have a branch corresponding to one of the allowable_other_names.

Raises an AssignmentCheckerError if the branch cannot be switched to.