Version control systems (VCS) allow developers to maintain a record of how their code has changed over time. When used properly, a VCS can help a developer track down the exact point in time when a bug was introduced or fixed, easily undo changes, and collaborate with other developers.
There are many types of version control systems. Some of the more popular ones include CVS, subversion, mercurial, and Git. In recent years, Git has quickly become the most popular of the group.1 You should watch this 20 minute video for a quick introduction to Git. (warning, in the video there is a picture of someone giving the middle finger as a rude gesture).
You can host a public (open to the world) or private (open to just you or a few individuals) repository on GitHub. GitHub has many useful features beyond the standard Git functions.
To install Git for Windows, click here: Git for Windows. This will
install msysgit
or “Git Bash” in addition to some other
useful tools, such as the Bash shell. Yes, all those names are totally
confusing, but you might encounter them elsewhere and I want you to be
well-informed.
This method of installing Git for Windows leaves the Git executable in a conventional location, which will help you and other programs, e.g. RStudio, find it and use it. This also supports a transition to more expert use, because the “Git Bash” shell will be useful as you venture outside of R/RStudio.
C:/Program Files
and this appears to be the default. This
implies, for example, that the Git executable on my Windows system is
found at C:/Program Files/Git/bin/git.exe
. Unless you have
specific reasons not to, follow this convention.If you follow these instructions you can use the shell (also called the terminal) directly from within RStudio. We will walk you through how/when to use it in videos referenced later on this page. If you are extra ambitious see this article for more information on how to use it and setup RStudio to use Git Bash, rather than the Command Prompt.
Mac OS X already includes the shell, so all you need to do is install Git.
Install the Xcode command line tools (not all of Xcode), which includes Git.
Go to the shell and enter one of these commands to elicit an offer to install developer command line tools:
git --version
git config
Accept the offer! Click on “Install”.
Here’s another way to request this installation, more directly:
xcode-select --install
We just happen to find this Git-based trigger apropos.
Note also that, after upgrading macOS, you might need to re-do the above and/or re-agree to the Xcode license agreement. We have seen this cause the RStudio Git pane to disappear on a system where it was previously working. Use commands like those above to tickle Xcode into prompting you for what it needs, then restart RStudio.
Install Git from here: http://git-scm.com/downloads.
If Git is not already available on your machine you can try to install it via your distro’s package manager.
Debian/Ubuntu
sudo apt-get install git
Fedora/Redhat Linux
sudo yum install git
You only have to do this once per machine.
In order to track changes and attribute them to the correct user, we need to tell Git your name and email address.
usethis
The usethis
package includes helpful functions for common setup and development
operations in R. Install it by running the command
install.packages("usethis")
from the console in RStudio. Then run the following commands:
library(usethis)
use_git_config(user.name = "hathawayj", user.email = "hathawayj@byui.edu")
Replace hathawayj
and hathawayj@byui.edu
with your name and email address. Your name could be your GitHub
username, or your actual first and last name. Your email address
must be the email address associated with your GitHub
account.
Open the shell on your computer. From there, type the following commands (replace the relevant parts with your own information):
git config --global user.name 'hathawayj'
git config --global user.email 'hathawayj@byui.edu'
You will not see any output from these commands. To ensure the
changes were made, run git config --global --list
.
RStudio can only act as an interface for Git if Git has been successfully installed AND RStudio can find it.
A basic test for successful installation of git is to simply enter
git
in the shell. It will print
a bunch of stuff to the screen, which is fine. However, if you get a
complaint about git
not being found, it means installation
was unsuccessful or that it is not being found, i.e. it is not on your
PATH
.
If you are not sure where the git executable lives, try this in a shell:
which git
(Mac, Linux)where git
(most versions of Windows)If Git appears to be installed and findable, launch RStudio and try again. If it still doesn’t work, quit and re-launch RStudio if there’s any doubt in your mind about whether you opened RStudio before or after installing Git.
From RStudio, go to Tools > Global Options > Git/SVN and make sure that the box Git executable points to the Git executable. It should read something like:
/usr/bin/git
(Mac, Linux)C:/Program Files (x86)/Git/bin/git.exe
(Windows)If you make any changes, restart RStudio and try the steps at the top of the page again.
Still not working? Try googling your problem or speak with myself or the TA.
Now that RStudio can find Git on your computer, we need to connect RStudio to GitHub online. You should have already signed up for a GitHub account.
Note that there have been recent changes in how RStudio authenticates for using GitHub, so some of the helpful blogs/resources online are now outdated. The instructions here are lifted from the rfortherestofus.com website.
I recommend (and explain below) connecting RStudio and GitHub by using your username and a Personal Access Token (PAT) for HTTPS operations. Alternatively, you could set up SSH keys.
To generate a personal acces token, run the following code in your R console. It will take you to the appropriate page on the GitHub website, where you’ll give your token a name and copy it (don’t lose it because it will never appear again!). On that same page, I recommend setting the expiration option to “No expiration”, or choose “custom” and set it to something longer than the semester, so that you don’t have to go through this process again. Watch the 1 minute video demonstration..
install.packages("usethis") #ignore this line if you installed the package already
library(usethis) #ignore this line if you loaded the package already
create_github_token()
Now that you’ve created a Personal Access Token, we need to store it so that RStudio can access it and know to connect to your GitHub account. Run the code below, and when prompted, enter your GitHub username and the Personal Access Token as your password (NOT your GitHub password). Once you’ve done all of this, you have connected RStudio to GitHub!
install.packages("gitcreds")
library(gitcreds)
gitcreds_set()
These emails often are filtered to your junk or clutter email folders automatically, so be sure to check there for them. Also, be sure you click the “accept” link in the invite, not just a link to view the repos.
In RStudio, start a new Project: File > New Project > Version Control > Git.
https://github.com/hathawayj/myrepo.git
. See the picture
below. Clip on the clipboard icon to copy the url.Whenever possible, this will be the preferred route for setting up your R projects.
Note: This is probably the simplest way to connect RStudio and Github. However, if you would like to connect GitHub to a previously created R-Studio project you can follow this guide.
Do this every time you finish a valuable chunk of work, at least once a day.
You can watch this video for a step-by-step demonstration of the steps described below.
To test it out, look in RStudio’s file browser pane for the
README.md
file at the top level directory of your project.
Double click it to open it. Modify the README.md
file by
adding the line “This is a line from RStudio”. Save your changes. Now
sync your local project with the online Github repo by following these 4
steps in the Terminal. (Usually the terminal tab is located next to your
Console tab in Rstudio).
git pull
and hit
enter. This will bring any changes that others may have pushed to your
Github repor down to your local machine. This is particularly helpful if
you are working as a team on a larger project, or if you are accessing
the Github repo from multiple computers (i.e. your work computer and
your home computer). You may be asked to resolve conflicts if your local
version conflicts with what is found in the repository.git add .
and hit enter. The period means you
are staging all the files in the Git pane. In the uncommon occurence
that you only want to upload certain files you can specify them by
name.git commit -m"put a cutomized message here"
and hit enter. This batches the changes and will be something that git
tracks. The -m
stands for message. The customized message
is not optional, it should describe the nature of the changes you have
made.git push
and hit enter. This officially
pushes from your local machine to the Github repository.Note, you cannot copy and paste into the terminal, you will have to type it out. There is a point and click method to do this as well in Rstudio, but it is slow and clunky. If you want to use it instead of the terminal commands, you can try watching this video.
Caution: Before you push your changes to GitHub, first you should pull from GitHub. Why? If you make changes to the repo in the browser or from another machine or (one day) a collaborator has pushed, you will be happier if you pull those changes in before you attempt to push.
Here is an image that illustrates the work flow commands that were just described.
Please take care to save the homework in the right folder and push it to Github in order for it to be graded.
This material was lifted from https://byui-cs.github.io/CS246/week-04/prepare.html, https://byui-cs.github.io/CS246/week-04/teach.html, and https://cfss.uchicago.edu/setup/what-is-git/.↩︎