02-git.Rmd

# Git and Github {#git}

The what and why of version control (specific to R!) can be found [here](https://happygitwithr.com/)


## 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](https://git-scm.com/downloads/guis)) that have graphical history viewers that show color coded history trees. 

```{r, echo=FALSE, fig.cap="Gitk's interface [@gitk]"}
knitr::include_graphics("images/gitk.png")
```

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.


### 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.

```bash
# 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

```

## Git Workflow from a Fork

Inspired by \@Chaser324's [Gist](https://gist.github.com/Chaser324/ce0505fbed06b947d962).

### Merge upstream changes into your own master branch

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

```bash
# Fetch from upstream remote
git fetch upstream

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

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

```bash
# 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
```
### Use the Repeated Amend strategy to develop your feature branch {#repeatedAmend}

This strategy comes from Chapter 24 of [Happy Git with R](https://happygitwithr.com/repeated-amend.html). 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.

```bash
# 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
```

#### Incorperate upstream changes

Just make sure you're incorperating upstream changes to origin master. Then you can pull from master to your feature branch. 
```bash
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](https://happygitwithr.com/pull-tricky.html).

Note: a [rebase](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) rewrites your history so that your new commits are shifted to the top of the master branch, as shown below.

```{r, echo=FALSE, fig.cap="Rebase of feature branch [@rebase]"}
knitr::include_graphics("images/rebase.svg")
```

### Push changes to GitHub and create pull request