R Projects and Version Control

Objectives: The objectives of this notebook are to:

• Show you how to create a GitHub Repository.
• Use RStudio to create a clone of your GitHub repository on your local machine via an R Project, and use that R Project to manage your GitHub repository.

Why Use Version Control?

Now that you’ve created a GitHub account, you can use GitHub to house repositories for projects that you’re working on. For example, I have a GitHub repository for most of the courses I teach. Those repositories house many of my course notes, old exams, projects, and more. Importantly, those repositories also track the evolution of these course materials. This means that if I try something new and don’t like how it turned out when I implemented it, I can simply revert the status of the repository back to its state prior to making those changes. This is a powerful upgrade from explicitly saving lots of different versions of files. Firstly, it is a much more organized approach and, secondly, it is safer and more reliable.

Creating a GitHub Repository

Creating a GitHub can be done in many ways. We’ll use the simplest method.

• Navigate to GitHub and log in using the username and password that you originally selected.
• Once you’ve logged in, you should see a green button with the word New on it. Click it to create a new repository (or repo if you want to be up on your git-slang).
• Give your repository a name – something like MAT434 should do. Choose something that will let you know that this is a GitHub repository associated with our course.
• (Optional) Add a description if you would like.
• Decide whether you want your repository to be public (anyone with the link can see the repository) or private (only people you explicitly invite can see the repository).
• You can click the checkbox to initialize the repository with a README if you’d like. A README file shows in the repository by default and is a place where you can describe, in detail, the contents and the state of the repository.
• Set the .gitignore template to R. This will prevent GitHub from syncing files specific to your local R workspace (such as your R code history and any API keys – passwords – that you may have provided during your R session).
• You can choose a license for your project if you’ve like. I usually choose the MIT license which is really permissive. It allows people to use my files and edite their own copies of my files. This document provides a reasonable description of a few license types.
• Click the green button to Create repository.

Using an R Project to Manage a GitHub Repository

Since you have RStudio configured to work with GitHub, you can now use RStudio to clone a copy of your repository to your local machine and to use RStudio to manage that GitHub repository.

• From your GitHub repository, click the green Code button and copy the https location of the repository.
• Open RStudio on your computer.
• Go to File -> New Project.
• Click on Version Control and then on git.
• Paste the repository URL into the first line of the dialog box.
• Change the name of the project if you don’t like the default name.
• Change the location where you want the clone of your repository to live on your computer. I have a GitHub directory inside of my Documents folder. All my local repositories live here.
• Click to Create project.
• Check that your top-right pane in RStudio now has a Git tab. This will track your changed files and allow you to sync the changes you’ve made to your local files with your remote GitHub repository (origin).

Adding a File to your Repository

Any changes you make within the directory corresponding to the R project you just created will be tracked in the Git tab. You’ll see a list of changed files here that need to be synced to your remote repository on GitHub. Right now that tab is empty though. Let’s change that.

• Click on File -> New File -> Quarto Document..., add a title, include your name as the author, and leave the default output set as HTML. Click Create to create the document.

• Click File -> Save As... and save the Quarto file in the directory corresponding to your R Project and GitHub repository. That should be the location that opens by default when you click on Save As...

  • Note that the file has shown up in that Git tab!

• Use the following sequence of button pushes in that top-right pane:

  • Pull in changes from the remote repository to your local repository using the blue, downward-pointing arrow icon.

  • Click the checkbox(es) under the staged column next to the file(s) you’ve changed.

    • New files that aren’t present in your remote repository will be accompanied by yellow question mark icons, files with changes have blue icons.

  • Click the Commit button, add a commit message describing the updates you are making to the textbox, and then click the Commit button.

  • Finally, Push your changes out to the remote repository by using the green, upward-pointing arrow icon.

• Navigate back to your GitHub repository on the web and check that your files are there. This is how you will ensure that the version of your repository on your local machine is the same as the version present on GitHub. The Pull -> Commit -> Push pattern is an important workflow to follow as it will minimize the impact of collisions (conflicting changes) once you start working with other collaborators.

---

Next Steps

Now that you’re using RStudio to manage your GitHub repository, let’s make this notebook into something meaningful.

• Navigate to our course webpage and open the Tidy Analyses in R notebook for either new students or returning students.

  • The difference between the two documents is in the data set being utilized and in the amount of guidance I am providing. If you remember the basics about piping chains of commands together in R, then use the returning student version. Otherwise, choose the new student version.

• Use your notebook to either follow the walkthrough (new students) or complete the tasks (returning students). Be sure to add discussion to your notebooks. Mixing text and code is a real strength of markdown notebooks.

When you are done, render your document and then sync your changes to GitHub using the Pull -> Commit -> Push workflow.

• Note: Rendering your document takes the markdown and code that you’ve been writing here and compiles it into a shareable HTML file.