Much of this tutorial is borrowed from Jenny Bryan at the University of British Columbia.
If you are using your own local installation of RStudio, you may need to install the
git program. This should not be necessary if you are on Linux, or a Mac running OS X 10.9 or later, as
git is preinstalled. If you are on Windows or an earlier version of OS X… just use the RStudio server for now at least.
You can use
git to track changes in your own work without using GitHub. But if you want to use
git collaboratively, and in particular, if you want to use it to turn in work for this class, then you need a copy of your repo to exist “in the cloud”. GitHub is by far the most popular choice for this.
You can either create a new project first in RStudio and then “upload” it to GitHub, or you can create a project in GitHub and “download” it to RStudio. The latter is a bit easier.
You now have a minimal project with two files: the
README.md documentation (this file is a Markdown file and you can use the same syntax to format it that you use to format RMarkdown documents, minus the code chunks), and a special file called
.gitignore that tells
git to ignore certain temporary files when recording changes to a repo.
But if you actually want to do anything with this project you need a copy of the repo where you use RStudio (for most people, this is the Oberlin RStudio server)
https://github.com/ocstats/stat209-s2021-git-intro-crdawson.git, but with your GitHub account name at the end instead of mine), and provide a name for the directory that will be created in your RStudio account to store your project files, as we’ve done in the past for labs (you might want to use a shorter name like
README.mdfile in RStudio, add a short description of the project, and save the file. Now select the “Git” tab in the upper right pane. You should see
README.mdappear in the list with an “M” next to it (this tells us that the file has been
Modified since the last commit. To tell git that we want to commit these changes, check the box next to the file to put it in the “staging” area (the changes are not committed yet, but they are ready to be committed when you give the go ahead). This is equivalent to the
addstep at the command line. To see the differences between the archived and current version of the file, you can click “Diff”. When you’re ready to commit, you will need to add a commit message in the text box. This should be a brief but informative statement about what you have added or changed since your last commit. Then click “Commit”. Now the current state of your project is registered in your local repo. (They are not yet uploaded to GitHub, but you have created a snapshot of your project that you can revert to if needed)
You should commit changes often; every time you finish some meaningful chunk of work
If you are collaborating on a project, your collaborators can only see changes that you have “uploaded” or
pushed to the shared, remote copy of the repo.
Caution: Before you
push, you should always
pull! This way, if someone else has made changes since your last push, you will be informed of any conflicts that need to be resolved. If you try to push while your local repo is out of date, you will get an error which can be non-trivial to resolve.
Create a new
.Rmd file (File > New > RMarkdown), change the title and author, save it, and Knit to
.html. You should see the new
.html files show up in the Git tab. “Stage” them, then
Replace the plot command in the RMarkdown template document with a
ggplot() command that plots
distance using the
cars data. Knit, stage, commit, pull and push. (In practice you will not necessarily push every time you commit, nor will you commit every time you change a single line, but we are developing muscle memory here)
scratchpad.R(this is a file that just contains R code; no Markdown). Add a comment, and save it. Stage the file, commit, pull and push. Now suppose you didn’t actually want to keep that file. Delete it by checking the box next to the file in the “Files” tab and clicking “Delete”. In the “Git” tab, you should now see a red “D” for “Deleted”. The next time you commit, the latest snapshot in the repo will have that file removed. (Since it had previously been committed, however, it can still be recovered from an earlier snapshot if needed)