A Git workflow with RStudio, R and usethis

In this guide, we will work on a cook book project using Git, R and RStudio. We will start going through all the steps for an individual project (you’re working on the cook book alone) and then we will see how to collaborate with others.

Preparations

To follow this guide you need:

• Git installed
• RStudio and R installed
• The R package usethis installed

The usethis is a very cool workflow package that has a lot of functionality including Git workflows. Install it in R with:

install.packages("usethis")

Setup PAT to use HTTPS protocol with GitHub

You can manage access to GitHub with a personal access token (PAT) instead of using your password. Check if you already have a personal access token with the correct configurations for GitHub.

usethis::gh_token_help()

This will tell you exactly what’s going on (in general, usethis is very helpful - so always read what it prints in the console): Do you already have a token or are problems with your current token? And if you need a token, it will also tell you can create one. To create a new token, call the function:

usethis::create_github_token()

This will open GitHub and ask you to sign in.

Next, you are asked to create a new personal access token.

On top enter a note to remind you what this token is for (e.g. Something like “RStudio on PC”).

Set an expiration date of your choice (the shorter the more secure, but you have to update more often - GitHub will send you a reminder for this).

You can also choose the scope for your PAT but for general use, the default settings are fine.

Scroll down and click on Generate token.

Copy the token to the clipboard.

Warning

You will not be able to read the token again after you closed GitHub. So leave the window open until you successfully set up your connection. You can also save the token in a safe place (e.g. a password manager).

Now register the token with git using the function:

gitcreds::gitcreds_set()

You are now prompted to paste your token into the R console.

Now your PAT should be added to the credentials. You can check it again with

usethis::gh_token_help()

Check the console to see if everything is fine and usethis now knows your GitHub Account data.

Optional: Add usethis to your .Rprofile

If you want to load the usethis package automatically when starting R, you can add it to your .Rprofile. This way, you have all the usethis functionality available without having to load the package first.

Careful when adding packages to .Rprofile

Loading packages via the .Rprofile should only be done for packages that are not used in your R scripts. Otherwise, you might forget to explicitly load the package in your script and the script breaks if you use it somewhere else.

Adding utility packages like usethis to the .Rprofile can however be very convenient.

Read more about this topic here.

You can open your .Rprofile file with

usethis::edit_r_profile()

Then you can add the following line, save the file and close it:

# supress messages just means that messages are not printed when loading the package
if (interactive()) {
  suppressMessages(library(usethis))
}
options(
  usethis.protocol = "https" # or "ssh" if you set up ssh
)

With this, usethis will be loaded every time you open RStudio and you already registered the default protocol that you want to use with Git (This is only relevant for the Git things you do with usethis).

A Git workflow for your individual project

Step 1: Create new R project

To create a new R project for this exercise call the function:

usethis::create_project(path = "path/to/project/project_name")

This will create a folder with project_name and set up and empty RStudio project. The project will open in a new RStudio instance. You can see that by default, the project already has some files inside (among them a .gitignore file).

Here you can see my new project (called “demo_project”) in R Studio. The files are highlighted in pink:

Of course you can also set up the project manually via RStudio (File -> New Project -> New Directory -> New Project) but I want to showcase the functionality of usethis here.

Step 2: Initialize a new Git repository

With the project open call the function

usethis::use_git()

Read the text in the console:

R tells you which changes will be committed. This is just the first commit that will include all the files that are in created by default and that are not in the .gitignore.

Confirm that you want to commit these files by selecting the correct number for the “Yes” answer and press enter. Then agree to the first commit with the commit message “Initial commit” (again by selecting the correct number).

RStudio will restart and a the Git GUI client will be added.

Can you find the Git tab in the top right pane? Here is where all the buttons for Git are located.

Step 3: Publish your project on GitHub

You can skip this step if you only want to work locally. But I recommend you try it, it’s really cool.

To create a new GitHub repository and link it to your local repository, all we need to do is all the function:

usethis::use_github(private = TRUE) # default is private = FALSE

With the private argument you can choose if your repository should be private or public.

This should now open GitHub in the browser and bring you to a freshly created GitHub project with all the files that were in your local repository (not a lot yet).

Really convenient 🎉

Step 4: Make some changes

Now let’s make some changes to the project.

Create a new R file in your project and add some content to it.

You can just copy the following code for convenience:

library(ggplot2)
penguins |>
  ggplot(aes(x = flipper_len, y = body_mass, color = species)) +
  geom_point() +
  theme_minimal()

Save the file in your project.

Step 5: Make a commit

If you have new changes that are not committed yet, you will see the changes listed in the Git pane of RStudio (top right). I have for example addedd a new file called penguins_plot.R.

To commit this file, just click on the “Commit” button in the Git pane:

Now you can select which files you want to commit. In this case we only have one file. To select (i.e. stage) files, just check the check box next to the file name. Now you can also see the changes that you made in the file (the code that you added is green, deleted code is shown in red).

Enter a commit message in the top right field. You can write a one-line commit message. Optionally, you can also add a more detailed description of your changes followed by a blank line. Click Commit when you are ready.

When everything is finished, close the commit window that opened.

Step 6: Push the changes to GitHub

Now push the changes to GitHub by clicking on the green upward arrow on the top right.

Go to GitHub and check if everything was pushed as you expected.

Collaboration workflows

In collaboration workflows, you normally first need to be added as a collaborator to a project. Then you can clone the project to your computer and work on it. We will skip those two steps here. You cannot do this from within RStudio. So if you want to clone a repository, you would need to do it with GitHub Desktop or in the terminal.

In the following, we will explore branching and merging from inside RStudio on our own project. But the workflow is the same when you work on a project of someone else.

Step 1: Create a new branch

In this step, you will create a new branch for a new feature that you want to introduce. This branch will later be use to do a pull request on GitHub.

In RStudio, you can create a new branch (e.g. to add a data analysis file), by clicking on the little violet branch symbol in the Git pane:

Enter a name for your new branch (no white space in name allowed) and leave everything else as it is. Click on create and RStudio will create and switch the branch for you. The new branch will also directly be pushed to GitHub Don’t worry - this does not mess up anything. You are in a new branch so the main branch stays untouched by this. You can close the dialog that opened now. Note that the branch that you are on is not main anymore but you new branch (see image above).

Step 2: Change files and push changes

Now that you are on your new branch, you can make changes to the files.

You could for example add a new R file with some data analysis code. Or you could add new code to the R file that you already created in step 4 of the individual workflow.

When you are done making changes, commit and push them (like in step 5 and 6 of the individual workflow).

Now your changes should be available on GitHub in the new branch and you can do a pull request.

Step 3: Create a pull request

See here for a guide on how to create a pull requests.