soniamitchell/github

GitHub tutorial (for RStudio)

Contents

• Setup Git on RStudio
• Create a new GitHub repository
• Create a new RStudio project
• Using Git in RStudio
• Generate a package structure in RStudio
• Final remarks
• Useful resources

Prerequisites

1. First, create a GitHub account with your academic email address
2. Verify your account
3. Go to https://education.github.com, click Students or Get benefits for students, and follow the instructions

Setup Git on RStudio

In RStudio, click on the RStudio menu bar and go to Preferences (or Tools and Global Options if you're using Windows)

Go down to the GIT/SVN tab and ensure that Enable version control interface for RStudio projects is checked.

While you're here, make sure you have a Git executable. If this box is empty, you need to install Git. Click on the Using Version Control with RStudio link and scroll down to the Installation section. This will take you to a site that describes how to install Git on your machine. Now restart RStudio.

Now that we're sure Git is installed, we're going to set up encryption between our laptop and GitHub. To do this we need to generate a certificate. Click on Create RSA Key...

Now, click Create to generate your RSA key

It should look like this

Now you need to copy your public key and register it with GitHub, so click on View public key

.. and copy the key to your clipboard

Then in GitHub, in your Personal settings, open the SSH and GPG keys tab

Create a New SSH key

Paste the public key that you copied from RStudio into the box and click Add SSH key

Now back in RStudio, tell Git your user name and email address (these are used to label each commit that you make to GitHub). Make sure the email address you enter here is the same as the one that you registered on GitHub.

install.packages("usethis")
library(usethis)

use_git_config(
  scope = "user",
  user.name = "insert_github_username_here",
  user.email = "insert_email_address_here"
)

RStudio will now remember your details, so don't worry about having to enter them again in the future. You should, however, check that your username and email address was entered correctly! So from the terminal tab, input the following (this will only work on a Mac):

git config --global --list

Create a new GitHub repository

It's important that you use version control in your project workflow, so let's set up a new GitHub repository (you should make a new repository for each project you're working on). To do this, click New

Choose a short, descriptive name for your repository and Initialize this repository with a README. Since this is a tutorial and not a real project, this repository has been named test.

Congratulations! You have successfully created a new GitHub repository, containing a single README.md file. Remember this for later.

Now copy the URL associated with your GitHub repository to your clipboard

Create a new RStudio project

In RStudio, click File > New project...

Since we're integrating version control into this project workflow, click Version Control

Select the option to clone a project from a Git repository

Paste your Repository URL into the first box, then click Browse... and navigate to the git folder on your desktop. If you don't have a git folder on your desktop then make one, as it's good practice to keep all of your projects together and well organised. RStudio will create a new subdirectory that will mirror the contents of your Git repository (so make sure you don't already have a folder with the same name as the repository you created, as this will cause problems). Now click Create Project

Congratulations! You have successfully created a new RStudio project (now with added version control). In the example below, the RStudio project is called test. A new directory, test, has been created inside the git folder on your desktop (this is now your working directory). Inside this directory are three files, including a GitHub README.md file (imported from your GitHub repository), an RStudio project file (test.Rproj), and an invisible .gitignore file (created by RStudio).

Note the appearance of a new Git tab next to Connections. This is important.

Using Git in RStudio

Compare the contents of your working directory to the files listed in the Git tab. The Git tab is a useful tool that shows you how your remote directory (your GitHub repository) differs from your local directory (in this case ~Desktop/Git/test). Currently, the README.md file in your local directory is identical to the one in your remote directory. That's why you can't see it in the Git tab. Instead, .gitignore and test.Rproj are listed with yellow Status question marks. What do these icons mean?

• "?" - Files or directories that don't currently exist in your git repository (you either want to commit these or add them to .gitignore)
• "A" - Files that have been staged and are ready to commit (you're in the process of committing these)
• "M" - Files that are modified versions of those in the repository (you definately want to commit these)
• "D" - Files that are no longer in your local directory (you want to commit these to GitHub)

Open the README.md file by clicking on its filename in the Files tab. Does this look familiar? (Compare the contents of this file to your repository on GitHub)

Usually a GitHub README (written in GitHub Flavored Markdown) will describe the contents of the GitHub repository or give an example of how to use the contents of said repository. Make some edits to README.md and save your file. Note that when we make edits to the README file, its Status changes to "M". This means that the file in your local directory is no longer identical to the file in your remote directory (on GitHub).

Click Commit to upload these changes to GitHub.

The RStudio: Review Changes window has opened. Click on the Staged checkbox next to README.md and enter a Commit message. Your message should describe the changes you've made to the file you're uploading (in this case, an initial commit). These changes are shown in the lower half of the screen, with deletions and insertions highlighted in red and green, respectively. Click Commit to continue.

Congratulations! README.md is now staged, with 7 insertions and 1 deletion. Close this window.

Then Push all staged files (at the moment, just README.md) to GitHub.

You'll need to enter your password..

Congratulations again! You've successfully pushed these changes to GitHub. Close this window and the Review Changes window beneath it.

Note that README.md is no longer listed in the Git tab (because both the local and remote versions are identical).

... and the GitHub README is immediately updated.

Final remarks

RStudio offers integrated version control, which is useful for daily tasks such as pushing, pulling, and reviewing changes (click on Diff in the Git tab). However, this is just the tip of the iceberg. If you have time, why not take a look at the links below. Try the interactive tutorials in "Learn Git Branching" by Peter Cottle and experiment in RStudio's Terminal tab with your own repository.

Useful resources

• Learn Git Branching, by Peter Cottle
• R packages - Git and GitHub, by Hadley Wickham
• Pro Git, by Scott Chacon and Ben Straub
• git/github guide, by Karl Broman
• Learn Git with GitKraken
• Learn the Basics of Git in Under 10 Minutes, by Gowtham Venkatesan
• git - the simple guide, by Roger Dudler