Much of this tutorial is borrowed from Jenny Bryan at the University of British Columbia.
gitIf 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.
gitYou 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.
git accountsGit associates your name and e-mail address with each commit, which helps when multiple people collaborate on a project. To configure your name and e-mail address in git, go to Tools > Shell…, and type the following (substituting your name and the email address you used to register a GitHub account)
git config --global user.name 'Your Name'
git config --global user.email 'your@email.com'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 git-intro).README.md file 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.md appear 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 add step 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 .Rmd and .html files show up in the Git tab. “Stage” them, then commit, pull and push.
Replace the plot command in the RMarkdown template document with a ggplot() command that plots speed against 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)