This package is intended to facilitate interactions with student repositories created via GitHub Classroom for educators who may not be as familiar with git and the automation of git commands across multiple repositories. The package uses git commands internally so individual students' repositories can be treated just like any other cloned repository (i.e. with full git functionality) if needed.
You can install ghctools from github with the devtools package. If you do not already have many of the dependencies installed (dplyr, ghql, httr, knitr, rmarkdown), this may take a moment to install. Since much of the functionality of this package is based on interactions with GitHub using git commands, it requires a fully functional local installation of command line git. To check whether you have git installed, run git --version from your operating system's terminal, which will print which version of git is installed (if any). If you don't have git yet or an older version (newer than 2.0 is highly recommended), please consult the Git Installation Instructions for your operating system.
install.packages("devtools") # skip this if you have devtools already installed
devtools::install_github("KopfLab/ghctools")Access to private repositories within the GitHub Classroom organization (e.g. to clone all students' assignment repositories for a private homework assignment) and push access to the student's repositories (e.g. for adding solution files or other updates) is managed via access token for security. To generate an access token for your classroom, follow the GitHub instructions and make sure to allow full repo access in the scopes (see screenshot below) - additional administrative privileges for your classroom token are not necessary and not recommended. Keep the token secure and use it when first fetching the students' repositories (ghc_repos_git_clone_respositories(..., token = "my-token")) as detailed in the User Guide below. The token will be stored in the local git remote origin for each repository, thus allowing easy git pull and git push access thereafter both through ghctools functions and directly via the git command line. Do NOT post your token publicly.
All ghctools functions start with the ghc_repos_git_ prefix to make it easy to search for the right function via code completion in IDEs such as RStudio.
To simply find information about students' repositories for an assignment, provide the name of the GitHubClassroom organization, the prefix of the assignment repository and an access token (required to query the GitHub API). This will return information about the repository names, creation date, last push and last pull request (date and user).
library(ghctools)
ghc_repos_get_github_information(
prefix = "assignment-prefix",
org = "my-classroom",
token = "my-access-token"
)To actually clone all students' repositories for an assignment, provide the name of the GitHubClassroom organization, the prefix of the assignment repository, an access token (only necessary if repositories are private and/or you intend to push changes back to GitHub), and optionally, a folder where to clone to.
library(ghctools)
ghc_repos_git_clone(
prefix = "assignment-prefix-",
org = "my-classroom",
folder = ".",
token = "my-access-token"
)ghc_repos_git_clone and all other command functions in the ghctools package take the prefix parameter as their first parameter and return it invisibly and thus can be used in pipelines that act on the same set of students' repositories. For example, the following pipeline would make sure the master branch is up to date for all repositories that match the prefix, create a new branch in the repositories, copy a file to this branch in all repositories, commit the change and push it back to the server.
library(ghctools)
"assignment-prefix" %>%
# make sure master branch is active
ghc_repos_git_switch_branch(branch = "master") %>%
# pull latest changes from github
ghc_repos_git_pull() %>%
# create a new branch based on master (could be based on a commit instead)
ghc_repos_git_create_branch(branch = "new_branch", parent = "master") %>%
# copy a file to all repositories (will overwrite existing)
ghc_repos_copy_to(from = "README.md", git_add = TRUE) %>%
# commit the change
ghc_repos_git_commit(message = "new file added") %>%
# push back to the server
ghc_repos_git_push()