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
refresh
button 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:
create_group(...)
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:
userid | team | token | |
---|---|---|---|
id1 | team1 | [email protected] | px....... |
id2 | team1 | [email protected] | n9....... |
id3 | team2 | [email protected] | VR....... |
Note: Markdown for the table above was generated using tablegenerator.com
create_repo(...)
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 gitgadget
.
assign_work(...)
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.
collect_work(...)
Generates Merge Requests for all students or teams. Requires a csv file with the structure shown above.
fetch_work(...)
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:
optionsoptionsoptionsoptionsoptionsoptionsoptionsoptions
Use a text editor (e.g., notepad on Windows) to create or edit .Rprofile in your home directory.
create_repo
when group already exists