Tutorial 1 - Getting Started with R, RStudio, Git, and GitHub Tutorial

Installing R and RStudio

In this tutorial, we’re going to get R, RStudio, and R Markdown set up on your computer. It’s important that you follow these steps in order. You may experience errors if you try go out of order. To get started:

1. Download and install the most recent version of R. There are versions available for the Windows, Mac, and Linux operating systems. On a Windows computer, you will want to install using the R-x.y.z-win.exe file where x.y.z is a version number. On a Mac, you will want to install using the R-x.y.z.pkg file that is notarized and signed.
2. With R installed, download and install RStudio. RStudio is a type of “integrated development environment” or IDE designed for R. It makes working with R considerably easier and is available for most platforms. It is also free.
3. Install the packages we will use throughout the semester. To do this, either type or copy and paste each of the following lines of code into the “Console” in RStudio (lower left panel by default). Make sure you do this separately for each line. If you are asked if you want to install any packages from source, type “no”. Note that the symbols next to my_package are a less than sign < followed by a minus sign - with no space between them. (Don’t be worried if you see some red text here. Those are usually just messages telling you information about the packages you are installing. Unless you see the word Error you should be fine.)

my_packages <- c("tidyverse", "usethis", "devtools", "learnr",
                 "tinytex", "gitcreds", "gapminder")
install.packages(my_packages, repos = "http://cran.rstudio.com")
remotes::install_github("kosukeimai/qss-package", build_vignettes = TRUE)

4. For some things in the course, we’ll need produce PDFs from R and that requires something called LaTeX. If you’ve never heard of that, it’s completely fine and you should just run the following two lines of R code:

install.packages('tinytex')
tinytex::install_tinytex()  # install TinyTeX

Installing and configuring git

Git is a version control program that helps organize the process of writing and maintaining code. It allows you to maintain a history of edits to your code without having to resort to a set of files like:

my_code.R
my_code_v1.R
my_code_v2_FINAL.R

There’s a lot to git and it will be hard to use in the beginning if you’re not familiar, but in the long term there are large benefits. First, when you use git, you are much less likely to encounter a devastating data failure. All of your (committed) changes to your project are preserved, even when you make new changes or you revert old changes.

Git is also a very useful way for people to collaborate. There is a large community built up around it and, once your projects are publicly available on Github (a website for hosting git repositories), there are a host of ways that people can collaborate with you.

Install git

You might already have git installed on your computer, especially if you have a Mac. To check, in RStudio, click on the Terminal tab in the bottom-left panel (next to the Console tab). Type git --version at the command prompt. If you get a response with a version number, great you are all set. If you get any kind of error message, then you’ll need to install git.

Git install for Mac

Go to the terminal tab in RStudio and type git --version to elicit an offer to install developer command line tools. This will appear as a popup menu on your computer (it may get stuck behind other windows that you already have open, so look around for it if you don’t see it immediately). Accept the offer and click on “install”.

Git install for Windows

Download Git here and click to install. Click “next” at the GNU General Public License screen. Select an installation path. Note that RStudio will look for Git in the "C:\Program Files" path by default, so that might be a good place to install Git. However, you can install Git using any path you’d like and we can tell RStudio where to find it.

Next you’ll be confronted with a bunch of different installation options. We can go with the default for all of these options, so you can just click “next” to keep navigating through to the “install” button.

Now that you’ve installed Git, you’ll want to check to see if RStudio can find it. Go to the terminal tab in RStudio and type git --version. If you see a version listed, then you’re all set and can move on to the next step. If you get an error message saying something along the lines of “git not found” or “git is not recognized”, then you’ll need to point RStudio to the Git installation path.

You can do this by navigating to the “Tools” menu in RStudio, selecting “Global Options”, then clicking on the Git/SVN icon in the left menu bar. Enter the Git installation path in the “Git executable:” box and add \bin\git to the end of the path (so, for example, if your installation path was C:\Documents\R_Stuff\Git then you want to enter C:\Documents\R_Stuff\Git\bin\git.) Click “apply” then click “ok” and then you’ll need to restart RStudio. After the restart go to the terminal window in RStudio and type git --version and you should see something like “git version 2.43.0.windows.1” displayed. Once you see that message, you can move on to the next step.

Setup a GitHub account

Next, you can setup a GitHub account. You can think of GitHub as similar to Dropbox or Google Drive for your git projects (“repositories”) where everything is public by default. Since you might use this account to interact with potential employers in the future, you should probably pick a professional username.

Once you have a GitHub account, you can configure your local git program to interact with your GitHub account. Run the following two lines of code in the Terminal replacing "Bruce Springsteen" with your name and "bruce@tulane.edu" with your email address used to sign up for GitHub.

git config --global user.name "Bruce Springsteen"
git config --global user.email "bruce@tulane.edu"

You will not see any output when you enter these commands. To check that they worked, enter the following command at the Terminal:

git config --list

You should see your name and email address listed in the output.

Set up RStudio to talk to GitHub

We also need to set up RStudio to be able to communicate with GitHub securely. This requires a process that we luckily only have to do once. Basically, we need to get a secret code from GitHub and store it in RStudio (kind of like an app-specific password when you’re using two-factor authentication). We can start the process by entering the following code at the R Console (not the Terminal):

usethis::create_github_token()

This will open a page on GitHub asking you to create a “Personal Access Token” or PAT (this is the secret code). You’ll have to give the PAT a note that describes what it’s for and choose an expiration date. To minimize problems throughout the semester, you should set it to a date after the semester ends such as 12/31/2024. Keep the “scope” selections as they are and click the “Generate Token” button at the bottom of the page.

You will then see a new screen with a long sequence of letters. This is your token or secret code. You should treat it like a password and do not share it with anyone. Copy this by hitting the button with the two boxes.

Once you have copied the PAT, call gitcreds::gitcreds_set() from the RStudio console and paste the PAT when prompted. You should see the following:

> gitcreds::gitcreds_set()
? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.

Once this is done, you should be all set for RStudio to communicate with GitHub. If you have any problems with the PAT process or want to know more about it, the Happy Git and GitHub for the useR book has a great chapter about it.

Creating your first repo

Once you are logged into Github and at its homepage, you can now create a new repo (shorthand for “repository”). These repositories are like folders in Dropbox except a bit more structured. Create one by clicking on the green “New” button in the top-left of the screen next to “Repositories.” It should look like this:

Now a new screen should pop up requesting some information for the new repo. Give this new Repository the name hpam7660-tutorial1 and set it to be a private repository. You can give it an informative description and check the “Initialize this repository with a README” checkbox. This latter option will add a README to the repository where you can add more information that will display nicely in the repository’s homepage. Your setup should look something like this:

Once you create your repo, you are ready to connect it to RStudio on your local computer (this process is called “cloning”). The easiest way to do this is go to the repo homepage (you’re already there if you’ve just created it) and click on the green “Code” button toward the top right of the page. When you click that, a popup will appear and you can copy the URL (you can click the little clipboard icon to copy this automatically).

Now, switch to RStudio. Go to the menu bar and hit “File > New Project”. You can then choose what type of project to start. Since we’re importing from Github, we’ll use the “Version Control” option (it’s the bottom of the list).

In the next menu, choose “Git”.

Now, you can paste the URL in the “Repository URL” box. I’ve noticed that the “Project Directory Name:” field and the “Create project as subdirectory of:” field are typically autofilled on a Mac, but not always on a PC. If those fields don’t autofill, add your repo name as the project directory name and a local folder path where you want to store R files as the subdirectory. Click “Create Project” and you’ll have your project ready to go in RStudio.

Working with a project in RStudio

You’ll now see the files from your Github project in the bottom right window of RStudio.

Let’s edit the README file by clicking on README.md in that file pane. You’ll be able to edit the file in the top-left pane.

Change the header from # hpam7660-tutorial1 to # Introduction and save the file (⌘+S or Ctrl+S). If you click on the “Git” tab in the top right panel, you will a list of the changes you’ve made to the repo since the last commit (you can think of a commit as a more permanent type of saving work to the git repo).

One thing you’ll notice here is that git thinks that hpam7660-tutorial1.Rproj is a file that maybe should go into the repo. But this file is just for our local copy of RStudio and shouldn’t really go into the repo. To prevent git from bothering us about it every time we open something, we can modify the .gitignore file to tell git to ignore certain files. Open .gitignore and add a new line with *.Rproj on it to tell git to ignore any file with the extension .Rproj. Make sure to save the file.

If you go back to the Git tab in the top right and refresh (little circular arrow in the top right corner), you see that hpam7660-tutorial1.Rproj is removed from our list. Now we are ready to commit our changes. Click the “Staged” box for .gitignore and README.md and hit the “Commit” button just above the file list. You’ll see a window with the changes that you are about to commit. You can click on different files to see what exactly you are changing. Add a short but informative commit message that describes what you are committing and hit “Commit”. You’ll see a popup window that summarizes the changes. You can click “Close”.

Once this completes, you can hit the “Push” button in the top right to push that commit back to Github. You’ll see another popup indicating that the push was successful. You can click “Close”.

If you go back to your repo’s homepage on Github and refresh the page, you’ll see the updates to your README file and the new .gitignore.

Finally, you’ll need to provide me access to this repo (and all future repos for class) so that I can grade your work. To do so, click on “Settings” on your repo homepage and then “Collaborators” at the top of the left panel. Click “Add people”, search for k-callison, and add me as a collaborator.

You’re done! You’ve just created your first repo. From now on, we’ll use repos for our tutorials and our assignment submissions.