Overview

Welcome!

This workshop provides an overview of what “version control” systems are and how they fit into collaborative coding within your team. Specifically, we are focusing here on an introductory approach to version control that focuses on using git via RStudio and GitHub. We are always happy to improve workshop content so please don’t hesitate to post an Issue on our GitHub repository if you see clear areas for improvement!

To maximize the value of this workshop to you, we recommend that you take the following steps before the day of the workshop. Depending on whether you’ve used RStudio and/or GitHub before you may have already completed some or all of these steps but please read through the following materials regardless to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the “Content Creators” tab.

Programs to Install

Note for those of you with a dedicated IT team that has sole power to install software on your computer: you will need to contact them before the workshop to install the following programs.

R & RStudio

Install R and its more convenient (in our opinion) user-interface: RStudio.

If you already have R, check that you have at least version 4.0.0 by running the following code:

version$version.string

If your version starts with a 3 (e.g., the above code returns “R version 3…”), please update R to make sure all packages behave as expected.

git

Install git

If you are a Windows user, be sure to follow along with “Option 1” in the instructions linked above! That variant gives some under-the-hood tools we’ll implicitly rely on later.

RStudio not detecting git?

If you had your RStudio session open while you installed git for the first time, RStudio may not have detected git on your computer. In that case, please close and restart RStudio. Check if RStudio is able to detect it now by going to Tools -> Global Options -> Git/SVN. If you see a file path under “Git executable” then you are good to go!

Once you’ve successfully installed R, RStudio, and git, follow the rest of the setup instructions below.

Accounts to Create / Connect

GitHub

Create a GitHub account using your web browser of choice.

Next, you will have to connect git to your GitHub profile and then create a personal access token (PAT). A token is essentially a more secure password that git requires. You can accomplish these two steps by running the following code in RStudio:

# Install the `usethis` and `gitcreds` packages
#install.packages(c("usethis", "gitcreds"))
library(usethis); library(gitcreds)

# Add your GitHub username and email
usethis::use_git_config(user.name = "Jane Doe",
                        user.email = "jane@example.org")

# Create a token (Note this will open a GitHub browser tab)
# See steps 6-10 in GitHub's tutorial (link below)
usethis::create_github_token()

# Copy your Personal Access Token at the end of the above step!

# Now, give your token to RStudio
# After you run this line you'll follow some prompts in the "Console" tab of RStudio
gitcreds::gitcreds_set()

At the end of the above steps your token should be set! For additional information, see GitHub’s PAT Tutorial or the Happy Git with R PAT Tutorial. If this seems a little intimidating, please keep in mind that your experience with downloading programs and creating web accounts will help with these tasks even if you have more minimal coding experience!

GitHub + Science Publications

The reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team’s disciplinary backgrounds and motivations.

In the ecology and evolutionary biology sphere, Pereira Braga et al. published “Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution” in Methods in Ecology & Evolution. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper’s second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) Pereira Braga et al. 2023 for more detail than we’ve included in this blurb.

If you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the blue bars). We also think that some of the intermediate technical difficulty uses (orange bars) may be relevant to working group priorities and goals.