gitgadget is an R-studio addin for version control and
assignment management using git. The assignment management functions
currently support the GitLab
API. PRs for use with GitHub are welcome. For alternative that uses
GitHub see https://github.com/rundel/ghclass although this does not
(currently) have a shiny user interface.
gitgadget is not intended as a tool for all-things-git.
For that you need something like
gitgadget provides a few additional features not (yet)
available in R-studio that can be useful to students and faculty using
git for classes. For an excellent discussion of this level of
functionality see happy git with
R and talk about version
control by Jenny Bryan and git for
humans by Alice Bartlett.
gitgadget requires Rstudio version 1.2 or later. Please
use the issue
tracker on GitHub to suggest enhancements or report problems. To
install the latest version of
gitgadget use the command
gitgadget click on the Addins menu in Rstudio
and then on
On macOS, you will you will need to run the command below from a terminal to get access to git commands:
On Windows you will need to install git bash from https://git-scm.com/download/win/.
Note: Hover over any button in the
gitgadgetapplication for additional information about what clicking the button will accomplish
To start using git and
gitgadget first introduce yourself to
git. Set a global user name and email for git (e.g., your GitLab
user name and email). By default,
gitgadget will try to
turn on an appropriate credential helper for your operating system. See
for additional information.
To create and fork repos and collect merge requests you will need to
provide a GitLab personal access token. First create the token on
GitLab and then copy-and-paste it in the
Unless you plan to use
gitgadget to manage student
student as the
Finally, enter the main directory where you plan to clone code repos
If you want to use an SSH key, make sure to click on the
Introduce button, restart Rstudio, and then click on the
SSH key button. Copy the key shown in GitGadget to the gitlab.com page that
should have opened in your default browser. To securely connect to
gitlab from your computer you will need to restart Rstudio and use
git clone git@some-private-repo from a terminal in Rstudio
the first time you clone a repo. After that, cloning, creating, etc.
from GitGadget should work smoothly. See the videos below for a
Note: On Windows we recommend cloning and creating repos using HTTPS rather than SSH
Note: As of version 0.7.0 the default branch has been set to ‘main’
Note: In these videos we use a docker container (see https://github.com/radiant-rstats/docker/tree/master/install/) but this is not required
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. You can also
Open button and navigate to an existing
directory. If a
Group name is provided it will be used to
place the repo on GitLab. This is recommended if you are using
gitgadget for assignment management. If left blank, the
GitLab user name will be used as the group. A
Prefix can be
added and will default to the value of
.Renviron (see Initial settings below). The prefix can be used
to avoid conflicting assignment names across classes (e.g., multiple
classes using “assignment1”).
If you selected
faculty as the
User type in
the Introduce tab you will have the option to upload a CSV file
with student tokens (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. Furthermore, you can choose if you
want to hide or show the main class repo to students.
Hiding the main repo can avoid confusion where a student might
accidentally clone the wrong repo (i.e., the class repo rather than
their own fork) and not be able to push there changes back to gitlab.
Showing the main repo, on the other hand, will make it possible
to sync any changes to the class repo after it was forked for
If a CSV file with TA information is specified they will be added as
“Maintainer” to the class repo. The will also be added as “Maintainer”
to all created student (or team) forks. TA information should include
Clone a repo from GitLab (or GitHub) (e.g.,
email@example.com:username/test-repo.git). The name for the
directory placed inside
Base directory to clone repo into
will be taken from the repo name unless a
Custom directory to clone repo into is provided. If there
is no R-studio project file (
.Rproj) in the remote repo,
one will be created.
Note: To use an SSH key with GitGadget you should clone from a terminal the first time. See the video linked above (Setup for git and gitlab) for a demo. As mentioned above, for Windows users we recommend using HTTPS to clone and create repos.
Note: To activate an HTTPS credential helper the first time you clone a repo from GitHub or GitLab you will be asked to provide your username and password in the Rstudio terminal
Create a local branch from the active branch by providing a name for
the new branch and clicking
Create local. Link and push to
the (GitLab) remote by clicking the
Link remote button. If
remote branches exist click the
Check out button to work
with a branch locally. If branches other than
Merge branches or delete them if they are no longer
needed. To undo a merge-in-progress, e.g., with merge conflicts, click
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 R-studio will gray-out).
Note: Changes to the list of available branches may only be visible in R-studio after clicking the
refreshbutton in the Git tab.
To commit changes to the local copy of your repo provide a
Commit message and then click the
button. If you committed changes you are not sure about, the
Undo button will let you revert the latest commit (after
If the remote repo contains changes you do not yet have locally press
Pull button. To add committed local changes to the
remote repo, click the
Push button. It you completely broke
the local repo and want to start over with a clean copy of the remote
repo, press the
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 SSH or HTTPS link to clone the
original repo into the
Sync repo with remote it was forked from input in the
Sync tab and then press
Sync. The repo you forked
will now be added as a remote. Click
update your local copy of the repo with any changes to the original
remote repo. Fix merge conflicts, if any, and proceed to work on the
local repo. To undo a merge with merge conflicts click the
Abort merge button. Click the
Unlink to remove
the reference to the upstream repo you forked from.
Collect assignments from students/teams using Merge Requests (MR) on
GitLab. Inputs will only be shown if the user type in the
Introduce tab is set to
If a CSV file with TA information is specified they removed from
(Hide) or added to (Show) to all created student (or
team) forks as a “Maintainer”. TA information should include
To collect and fetch assignments linked to class repo you must first
open a clone of that repo in Rstudio and provide your
Assignment name input should now
show the assignment repo name on gitlab.com. Next, indicate of the
team and click
Collect button to generate Merge Requests for all
students (or team leads). Once this step is completed you can review and
comment on the MRs using the GitLab UI. Collecting assignments requires
that MRs be generated, which in turn requires that the class repo be
visible to students. The
Hide button can be used to ensure
students will not have access to the MRs. However, since this is likely
to be after the assignment due data, visibility of the class repo and
MRs may not be or much concern. The
Show button will
provide students access to the class repo and MRs.
To view, run, and edit the MRs locally, press the
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 R-studio or the Sync tab in
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
If students update their assignment repo these changes will be
visible in the MRs as long as the class repo is visible to students
Show button to ensure access). If you want to
Fetch these updates for local review you should first
delete the existing branches for one or more students. This can be done
through the Branch tab by selecting all branches you want to
delete and clicking the
Delete local button. Then click the
Fetch button in the Collect tab again to obtain
the latest version.
Key functions in
git.R that can be accessed through the
gitgadget interface are:
Used to create a group for a course. The
variable should be set to something like “school-courseid-year”. This
creates the group and adds students as, for example,
reporters with read-only access on GitLab. Make sure to
specify a valid
To create an assignment repo set
Local directory to the
directory with the assignment files. A
Prefix could 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. This requires a csv file with the structure shown below, including the students’ (GitLab) private token.
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 .Renviron file (e.g.,
“C:/Users/me/.Renviron”). The easiest way to view
is to click on the
Check button in the Introduce
tab or use
git.user = "your-gitlab-id"
git.email = "firstname.lastname@example.org"
git.token = "abc123"
git.home = "~/git"
git.server = "https://gitlab.com/api/v4/"
git.group = "school-courseid-2019"
git.prefix = "school-courseid-2019-"
git.userfile = "path-to-user-file.csv"
git.tafile = "path-to-ta-file.csv"
git.user.type = "faculty"