Chapter: 2 Git and Github

The what and why of version control (specific to R!) can be found here

2.1 Git in RStudio

There is a “git” tab in RStudio, but it can’t perform simple operations required to develop a project from a fork, so you likely want to start using the terminal for all of your git needs. If you are a visual person, there are many flavors of git guis for download( (which can be found here) that have graphical history viewers that show color coded history trees.

Gitk's interface [@gitk]

Figure 2.1: Gitk’s interface (Git 2020)

Gitk (shown above) and git-gui come with a standard Git install. If you wish to make a commit with a gui, use the command git gui and if you wish to view the history tree, execute gitk --all in your terminal.

2.1.1 Setting Up Remotes for the First Time

Create a fork on GitHub. A fork is a static copy of someone else’s Github repository. A remote repository is the version that is stored on a GitHub server (as opposed to your personal laptop or local machine), and is the version available for viewing on github.com. An upstream repository is the shared version of the project that you are contributing to.

# create a local copy (clone) of your fork
git clone https://github.rcac.purdue.edu/<YOUR_USERNAME>/SuperPower.git
# remote origin is your own personal fork as it lives on GitHub
git remote set-url origin https://github.rcac.purdue.edu/<YOUR_USERNAME>/SuperPower.git
# remote upstream is the parent repository as it lives on GitHub
git remote add upstream https://github.rcac.purdue.edu/ScientificSolutions/SuperPower.git
# list remotes
git remote -v

2.2 Git Workflow from a Fork

Inspired by @Chaser324’s Gist.

2.2.1 Merge upstream changes into your own master branch

This should be nontrivial if you committed and pushed the last time you coded.

# Fetch from upstream remote
git fetch upstream

# Checkout your master branch and merge upstream
git checkout master
git merge upstream/master

2.2.2 Create a branch to work on a new feature or bugfix

# Checkout the master branch - you want your new branch to come from master
git checkout master

# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature

# Switch to your new branch
git checkout newfeature

2.2.3 Use the Repeated Amend strategy to develop your feature branch

This strategy comes from Chapter 24 of Happy Git with R. I highly suggest that you read the whole thing yourself.

The idea of a repeated amend is that you can have a version of your code to fall back on (with a git reset --hard) that is more recent than your last commit. Imagine, you don’t want to make a tiny commit for every trivial change, but at some point you are far through your next commit, and things start breaking. A repeated amend is how we prevent tiny commits, and provide ourselves with a fail safe at every step of your code that still runs.

# make a few changes to the code and test to make sure nothing is broken

# commit so we have something to revert back to if need be
git commit -m "The name of the thing I want to accomplish in the completed commit"

# make a few more changes

# instead of making another giant commit, we amend our last one with the new changes
git commit --amend # --no-edit if you don't need to change the message

# we continue this process until we want to start a new commit, by not using --amend

2.2.3.1 Incorperate upstream changes

Just make sure you’re incorperating upstream changes to origin master. Then you can pull from master to your feature branch.

git fetch upstream
git checkout master
git merge upstream/master
git checkout newfeature
git pull --rebase origin master

This works as long as the upstream changes don’t overlap with any of the changes you have made. If this doesn’t work for you there are other, more complicated ways to deal with this.

Note: a rebase rewrites your history so that your new commits are shifted to the top of the master branch, as shown below.

Rebase of feature branch [@rebase]

Figure 2.2: Rebase of feature branch (Tutorials and Atlassian Git Tutorial 2020)

2.2.4 Push changes to GitHub and create pull request

References

Tutorials, Git, and Training | Atlassian Git Tutorial. 2020. “Git Rebase: Branch onto Master.” https://wac-cdn.atlassian.com/dam/jcr:e4a40899-636b-4988-9774-eaa8a440575b/02.svg?cdnVersion=752.