If you are participating in this training series, we are so excited to help you acquire new or hone existing technical and interpersonal skills in the realm of synthesis science! To ensure that you get the most out of this training series, we recommend that you take the following steps before the first week.
If your organization has a dedicated IT team that has sole power to install software on your computer, you will need to contact them before the training to do the installation bits of the preparation steps we outline below.
1 Install R
“R” is the coding language we’ll use for all of the code-related training modules. Follow the relevant instructions for your operating system here: r-project.org.
If you already have R, check that you have at least version 4.5.0 by running the following R code: version$version.string. If your R version is earlier than that version, please update to minimize avoidable issues.
2 Install an IDE
Next, you’ll need to install an integrated development environment or “IDE”. This is a fancy term for any piece of software that lets you write software. Essentially, your IDE will allow you to write code and use Git with a neat, easy-to-use interface. There are a number of IDEs that exist but RStudio or Positron are reasonable ‘first choices’ for those coding primarily in R
Follow the relevant instructions for your operating system at positron.posit.co. Update your version if your version number is much lower than what you see on the preceding link.
Follow the relevant instructions for your operating system at posit.co/products/open-source/rstudio. Update your version if your version number is much lower than what you see on the preceding link.
You may already be familiar and comfortable with RStudio (we are too!). Positron is the next generation IDE developed by the same folks who made RStudio, and it has better integration for Quarto, non-R programming languages, and Git/GitHub. Because the makers of RStudio themselves are pushing this transition, we feel it is worth making the leap for this training.
That said, nearly everything in this training will work equally well in RStudio!
3 Install Necessary R Packages
So-called “base R” contains some useful, fundamental operations from the moment you install it. However, there are a variety of external packages that contain more specific tools that can also be extremely useful to you. Most of these we will provide installation instructions for in the lessons that use them, but there are a few that it will benefit you to install now. Choose one option and run the respective R code in the “Console” pane of Positron/RStudio.
This is the built-in function to install packages in R. This is what you will most likely see “in the wild” and works well.
install.packages("usethis")
install.packages("gitcreds")Do not use install.packages() in a script, though, since it will re-install the package every time you run it - not good practice for reproducibility or performance.
The librarian package is an improved way to install and manage R packages. It will test to see if the package is already installed, and if not, it will install it for you, and then load the package.
librarian::shelf(package) takes the place of install.packages("pakage") + library(package).
## install.packages("librarian")
librarian::shelf(usethis, gitcreds)- 1
-
The
shelffunction will automatically install the packages that you don’t already have and then load all the identified libraries
Because librarian::shelf() checks to see if a package has already been installed, it is safe to include in a script!
4 Install Git
Git is the name of the software that we can use to do “version control” for the code files we’ll develop. We’ll get into this more later but for now, it is enough to know this is analogous to Microsoft Word’s “track changes” feature but with some extra tools that are great for code files.
Installing Git differs slightly depending on your computer’s operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan’s excellent “Happy Git and GitHub for the useR” ebook.
Run the following command line code.
xcode-select --installFor more detailed instructions, see here.
Install Git for Windows (a.k.a. “Git Bash”). When asked about “Adjusting your PATH environment”, select “Git from the command line and also from 3rd-party software”.
For more detailed instructions, see here.
Install Git via your distro’s package manager (in the Terminal).
If you use Ubuntu or Debian Linux that code is as follows:
sudo apt-get install gitIf instead you use Fedora or RedHat Linux the code is instead:
sudo yum install gitFor more detailed instructions, see here.
Check that the installation was successful by running the following command line code in the terminal (you may need to restart your computer first):
git --versionIf successful, you should see something like git version 2.40.1.windows.1.
5 Make a GitHub Account
GitHub is a nice web interface for collaborating with other people who use Git. Later in the lifecycle of a project, GitHub is also useful for sharing and publicizing your code beyond your team and also has some potentially useful project management tools.
For this training:
- Make a profile at github.com
- Consider adding a profile photo
- Doing so will make you stand out relative to the default ‘space invader’ image your account will start with
6 Set Git Options
Before you can use Git, you need to tell it who you are (a.k.a. you must set the global options). You can do this either with command line code or with R code from the usethis package. For this lesson we will use the usethis package. However, you can also find the command line code to reference in the future.
Technically, the “Terminal” is an interface for the shell, a computer program. We use the Terminal to directly tell a computer what to do outside of R. This is different from the “Console” in your IDE (Positron, RStudio), which interprets R code and returns a value.
The Terminal should be visible by default in your IDE, but if it is not, you can open it by clicking Terminal New Terminal. A Terminal tab should now be open right next to the Console tab.
Most of our Git operations will be done with R code, but there are some situations where you must work in the Terminal and use command line. It may be daunting to code in the Terminal, but as your comfort increases over time, you might find you prefer it. Either way, it’s beneficial to learn enough command line and to not be intimidated in the Terminal.
6.1 Configure GitHub Username and Email
First, update your global options with your GitHub username and email. You can use either command line code in the Terminal or R code in the Console
Step 1: Tell Git (1) your GitHub username and (2) your GitHub-associated email address.
usethis::use_git_config(user.name = "my_user_name",
user.email = "my_email@nceas.ucsb.edu")Step 2: Define the default name for a branch that gets created when you make the first commit in a new Git repository (a.k.a. “repo”).
usethis::git_default_branch_configure(name = "main")Step 3: Check to make sure everything looks correct.
usethis::git_sitrep()Step 1: Tell Git (1) your GitHub username and (2) your GitHub-associated email address.
git config --global user.name "my_user_name"git config --global user.email "my_email@nceas.ucsb.edu"Step 2: Define the default name for a branch that gets created when you make the first commit in a new Git repository (a.k.a. “repo”).
git config --global init.defaultBranch mainStep 3: Check to make sure everything looks correct.
git config --global --listPreviously, the default branch name was “master” and this terminology for Git branches is problematic, which motivates us to update our default branch to “main” instead.
6.2 Configure Strategy for Reconciling Differences
When you’re working on the same GitHub repository as the rest of your team, what happens when you and a teammate edit the same file at the same time? How does Git ‘know’ how to reconcile those differences? Simply put, we tell Git how we want it to make that judgment call!
There are three options, “merge,” “rebase,” and “fast forward.” We recommend that you choose the “merge” strategy as it will seamlessly handle easy situations where human oversight isn’t needed but will flag more nuanced problems (called “merge conflicts”) for you to resolve manually. For more information on “merge” versus “rebase”, see here. You can always revisit this decision later using essentially the same code below!
Set the default strategy for reconciling differences.
usethis::use_git_config(pull.rebase = "false")Set the default strategy for reconciling differences.
git config --global pull.rebase falseNote: The --global option will set this as default for all repositories on your computer. If you remove that piece, it will only set for the current repo.
If you forget to set your pull.rebase option, you will get the following error message when you try to sync your local computer with GitHub. Note, the error message gives you the terminal code to fix it!
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint: git config pull.rebase false # merge (the default strategy)
hint: git config pull.rebase true # rebase
hint: git config pull.ff only # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --norebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches- 1
-
This is the Terminal code to set the “merge” strategy, though we recommend you set this globally using the
--globaloption.
7 Authenticate Your Computer with GitHub
While you will use your GitHub password to log in to your account on a web browser, in order to actually send code you write from your local computer up to GitHub, you’ll need to “authenticate” in a different, more secure way.
The book Happy Git and GitHub for the useR has a wealth of information related to working with Git in R, and the instructions below are based off of Chapter 9: Personal access token for HTTPS in that book.
We will be using Personal Access Token (PAT) authentication for this training series. If this topic is of interest, you can find information on a different approach to authentication–called “SSH keys”–here.
Step 1: Jumpstart the token creation process with the following R code. This will open a new browser window with a big checklist of different options (“scopes”) for your token. Feel free to scroll through them at your leisure.
usethis::create_github_token()Step 2: Scroll to the bottom of the token creation page and click “Generate Token”.
Step 3: Copy the generated token. You will never be able to see this token again (ever!) when you leave this page!
Step 4: Return to your IDE and run the following R code.
gitcreds::gitcreds_set()Step 5: When prompted, paste your newly-created PAT into the Console.
Step 6: Check all of those steps worked by running the following R code. You are hoping to see Personal access token for 'https://github.com': '<discovered>', if you see <unset> instead, something has gone wrong with the preceding steps.
usethis::git_sitrep()8 Celebrate!
Congratulations! If you worked through all of the above steps, you should be ready for any of the Git/GitHub lessons in this training series!