An Rstudio addin for version control that allows users to clone repositories, create and delete branches, and sync forks on GitHub, GitLab, etc. Furthermore, the addin uses the GitLab API to allow instructors to create forks and merge requests for all students/teams with one click of a button.
gitgadget is an Rstudio addin for version control and assignment management using git. The assignment management functions currently support the gitlab API. PRs for github, bitbucket, etc welcome.
gitgadget is not intended as a tool for all-things-git. For that you need something like sourcetree. Its goal is to provide a few additional features not (yet) available in Rstudio that can be useful to students and faculty using git for classes. For an excellent discussion of this type of functionality see happy git with R by Jenny Bryan.
Please use the issue tracker on GitHub to suggest enhancements or report problems: https://github.com/vnijs/gitgadget/issues.
To start using git and gitgadget introduce yourself to git
Set a global user name and email for git. Please use your gitlab user name. If available,
gitgadget will put
~/.ssh/id_rsa.pub into the clipboard when you click the
SSH key button. Provide the key to github or gitlab for authentication. By default,
gitgadget will try to turn on credential helpers for your platform. See http://happygitwithr.com/credential-caching.html for additional information
To avoid possible authentication issues with SSH on gitlab we recommend you clone, push, pull, etc. using HTTPS
Enter the path to a local directory to create a repo on gitlab. If the local directory does not yet exist it will be created. For existing directories you can click the
Open button and navigate to a file in the directory of interest. The directory path will be parsed from the provided file path. If a
Group name is provided it will be used to place the repo on gitlab. If left blank, the user name will be used as the group. A
Prefix can be used and will default to the value of
git.prefix in .Rprofile in your home directory (see Initial settings below). The prefix is used for assignment management to avoid conflicting assignment/case names.
User file is only relevant for assignment management (see below). If a user file is provided a radio button will be shown that can be used to indicate if the work should be completed individually or in teams.
Clone a repo from gitlab (or github) (e.g., https://github.com/vnijs/gitgadget-test-repo). The name for the directory placed inside
Clone into will be taken from the repo name unless an alternative name is provided in
Clone to. If no Rstudio project file (
.Rproj) exists in the repo one will be created.
To activate an HTTPS credential helper the first time you clone from github or gitlab you may need to use the command line (e.g., git clone repo-to-clone)
Create a local branch from the active branch by providing a
Branch name and clicking
Create local. Link and push to the (gitlab) remote by clicking the
Link remote button. If remote branches exists click the
Check out button to work with a branch locally. If branches other than
master exist you can
Merge branches or delete them if they are no longer needed. To undo a merge-in-progress, e.g., with merge conflicts, click the
Abort merge button.
Unlink remote will not remove the local or the remote branch but only the link to the remote (i.e., the push/pull arrows in Rstudio will gray-out).
Changes to the list of available branches may only be visible in Rstudio after clicking the
refreshbutton in the Git tab.
If the repo you are working on is a fork you probably want to make sure it is up to date and merge any changes into the version you are working on locally. The first step is to ensure that git knows about the
upstream repo you forked from. Copy the HTTPS link to clone the original repo into the
Sync from input in the Sync tab and then press
Sync. The repo you forked will now be added as a remote. Click
Merge to update your local version with any changes to the original. Fix merge conflicts if they pop up and proceed working on the repo. To undo the merge simply click the
Abort merge button. When you are done commit and then push your changes to gitlab.
Collect assignments from students/teams using Merge Requests (MR) on gitlab. When you navigate to the Collect tab gitgadget will search for all assignments in the specified group on gitlab. Once all inputs are provided, including the path to a file with student information, press the
Collect button. MRs will be generated for all students (or team leads). Once this step is completed you can review and comment on the MRs using the gitlab UI.
To view, run, and edit the MRs locally press the
Fetch button. After fetching all MRs they are converted to branches using the student-id as the branch name and pushed back up to the server. Switch between branches to test code and provide comments and/or fixes. Use the Git tab in Rstudio to push local changes to the remote branch. Notify students of the comments/fixes by providing a link to the branch in the comments on the original MR.
Key functions in
git.R that can be accessed through the
gitgadget interface are:
Used to create a group for a course. The
Group name variable should be set to something like "school-courseid-year". This creates the group and adds students as
reporters with read-only access on gitlab. Access this functionality through the Create tab in
gitgadget. Creating a group requires an input file of the following form:
Note: Markdown for the table above was generated using tablegenerator.com
To create an assignment repo set
Local directory to the directory with the assignment files. A
Prefix should be added to avoid conflicts across courses that might use the same assignment name (e.g., assignment1). Access this functionality through the Create tab in
Forks the assignment repo uploaded by a faculty member or TA for each student/team and creates the appropriate groups for team work. Requires a csv file with the structure shown above, including the students' (gitlab) private token. Getting access to these tokens will most likely require that student accounts are created centrally for the class/program.
Generates Merge Requests for all students or teams. Requires a csv file with the structure shown above.
Fetch Merge Requests for all students or teams from the gitlab server. After fetching all MRs they are converted to branches using the student-id as the branch name and pushed back up to the server. Switch between branches to test code and provide comments. Push to update the remote branch with the local changes.
Gitgadget supports the following input from an .Rprofile file:
options(git.user = "yourgitlabid")options(git.email = "email@example.com")options(git.password = "")options(git.home = "/Users/you/Desktop/git")options(git.server = "")options(git.group = "school-courseid-2016")options(git.prefix = "school-courseid-2016-")options(git.userfile = "path-to-user-file.csv")
Use a text editor (e.g., notepad on Windows) to create or edit .Rprofile in your home directory.
create_repowhen group already exists