Version control

# Version control
### 2019-03-24

---

# Check-in

To follow along, you should have:

- a GitHub account - [create one now](https://github.com/) if you don't have one already!
- git installed and connected to RStudio (detailed installation instructions at [Happy Git with R](https://happygitwithr.com/workshops.html#pre-workshop-set-up))

## Slides link: http://bit.ly/hu-git

---
This presentation is based on:

[Happy Git with R](http://happygitwithr.com)  
[NCEAS GitHub crash course](https://nceas.github.io/training-git-intro/getting-started-with-git-rstudio.html)  
[Ocean Health Index GitHub training](http://ohi-science.org/data-science-training/github.html)

---
background-image: url(http://www.phdcomics.com/comics/archive/phd101212s.gif)
background-position: center
background-size: auto 100%

---

# Why learn and use git/GitHub?

- Version control
- Easy to share and distribute files, especially code/analyses
- Files accessible from anywhere with an internet connection
- Improves collaboration
- Contribute to open source!

_Git enables time travel & alternate realities!_

---
background-image: url(https://media.giphy.com/media/kxAX99ncvbPk4/giphy.gif)
background-position: center
background-size: cover

---
# git

.pull-right[
<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5e/Cropped-big-brother-is-watching-1984.png/800px-Cropped-big-brother-is-watching-1984.png" width=100%>
]

---
# git is _not_

git works best with _text-based_ files!
]

"Dropbox" for git-based projects on the internet.

- share/store analyses and functions
- browse past versions of code
- browse source code ([CRAN](https://github.com/cran),  [tidyverse](https://github.com/tidyverse/), [rOpenSci](https://github.com/ropensci))
- use packages not on CRAN (`devtools::install_github("account/repo")`)
- host web pages

--
 
You get unlimited private GitHub repositories for _free_ (used to be $7/month)!

---
background-image: url(http://ohi-science.org/data-science-training/img/commit_compare_3.png)
background-position: center
background-size: auto 100%

---
# GitHub terminology

- **repository** or repo - project/folder 
- **local** - files stored on your computer 
- **remote** - files on github.com

---

# GitHub: let's get oriented!  
---
class: exercise

Take a moment to explore this repository:

# https://github.com/isteves/typos

- When was the .xlarge[repository 📁] first created?
- What .xlarge[commits 💍] have been made to the repository?
- What .xlarge[issues ❌] have been submitted?
- What .xlarge[pull requests 🙏] (PRs) have been submitted?
- Are there any .xlarge[forks 🍴] or .xlarge[branches 🌵]?

---
background-image: url(img/github-account.png)
background-position: center
background-size: 100%
---
background-image: url(img/github-copies.png)
background-position: center
background-size: 100%
---
background-image: url(img/github-commits.png)
background-position: center
background-size: 100%
---
class: exercise

# Let's create a repo from scratch...  
### (choose a unique name!)

- don't use special characters
- name it `something_meaningful` and `not-too-long`
- note for advanced users: R packages cannot take underscores or dashes
---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/create_repository_2.png)
background-position: center
background-size: 100%

---

# Let's connect to RStudio!

---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/clone_step1.png)
background-position: center
background-size: 100%
---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/new_project_1.png)
background-position: center
background-size: 100%
---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/new_project_2.png)
background-position: center
background-size: 100%
---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/new_project_3.png)
background-position: center
background-size: 100%
---
class: inverse
background-image: url(https://media.giphy.com/media/vt4gALQsxCDmM/giphy.gif)
background-position: center
background-size: 100%
---
class: inverse
background-image: url(https://media.giphy.com/media/vt4gALQsxCDmM/giphy.gif), url(http://ohi-science.org/data-science-training/img/new_project_4.png)
background-position: bottom right, center
background-size: 30%, 100%

---
class: inverse, center, middle

# Inspect your repository 🕵

---
class: inverse
background-image: url(http://ohi-science.org/data-science-training/img/RStudio_IDE_git.png)
background-position: center
background-size: 100%

---
You now have a GitHub PROJECT!

https://speakerdeck.com/jennybc/workflow-you-should-have-one

---
# What's the deal with projects?

Each project is a self-contained set of files. Projects make it **easy to transfer** files to another computer because its **boundaries are clearly defined**

.center[
<img src="img/project.jpg" width=50% align="center">
]
---
# Use relative paths inside projects
 
- looks cleaner
- works for other people/computers

```r
read.csv("data/eilat_survey_2017.csv")
#rather than
read.csv("C:/חזי/phd/thesis/reef_surveys/data/eilat_survey_2017.csv")
```

You never have to use `setwd()` again!

**Pro tip:** use `here::here()` to deal with path differences across Rmd's, R scripts, and Shiny apps.
---

# Practice time

1. Create an Rmd file in the project you created before (output = HTML)
2. Make some edits
3. Save as `index.Rmd`
4. Knit (ctrl/cmd + shift + K)

You end up with two new files: `index.Rmd` and `index.html`

---
class: inverse, center, middle
# Basic git flow ~ courtship cycle 
---
# First, **pull** them in

.center[
<img src="img/push.jpg" width=60%> 
]
---
background-image: url(http://ohi-science.org/data-science-training/img/push_pull_clone.png)
background-position: center
background-size: auto 90%

---
# Sync from RStudio to GitHub

.center[
![](http://ohi-science.org/data-science-training/img/commit_overview.png)
.img-small[
[![http://www.rstudio.com/wp-content/uploads/2016/01/rstudio-IDE-cheatsheet.pdf](img/version-control-rstudio-cheatsheet.PNG)](http://www.rstudio.com/wp-content/uploads/2016/01/rstudio-IDE-cheatsheet.pdf)
]
]

---
background-image:url(img/pull.jpg), url(http://ohi-science.org/data-science-training/img/pull.png)
background-position: bottom right, center
background-size: 30%, 100%
---
background-image:url(img/commit.jpg), url(http://ohi-science.org/data-science-training/img/staged.png)
background-position: bottom right, center
background-size: 30%, 100%
---
background-image:url(img/commit.jpg), url(http://ohi-science.org/data-science-training/img/commit.png)
background-position: bottom right, center
background-size: 30%, 100%
---
background-image:url(img/push.jpg), url(http://ohi-science.org/data-science-training/img/push.png)
background-position: bottom right, center
background-size: 30%, 100%
---
background-image: url(img/github-flow.png)
background-position: center
background-size: 90%
---
class: exercise

# Your turn

1. Pull - make sure your branch is up-to-date
2. Make changes to `index.Rmd`. Save and knit
3. Stage ✅ `index.Rmd` and ✅ `index.html` 
4. Commit 💍
5. Push - sync with remote repository

---
class: inverse, center, middle
# Host Rmd's online with GitHub Pages
---
background-image: url(img/github-pages.PNG)
background-position: center
background-size: 90%

---

# Your turn

1. Turn on GitHub pages (from the repo home page, click Settings --> set source to _master branch_)
2. Check out your new web page!

## USERNAME.github.com/REPONAME

_Note:_ if your file was not named `index.html`, then you'll have to add `/FILENAME.html` to the end of the URL

---
# A few tricks

- Use `index.html` to set a home page for your repo: username.github.io/reponame = username.github.io/reponame/index.html
- use `toc_float` to add a floating table of contents to your RMarkdown webpage (more details [here](https://bookdown.org/yihui/rmarkdown/html-document.html))

```r
---
output:
  html_document:
    toc: true
    toc_float: true
---
```
---
class: inverse, center, middle
# Let's collaborate!
---
# Contribute changes

If you want to work off of an existing repository on GitHub...

1. **Fork a repo** = make a copy of the repo on your account
2. **Make a branch** = start an alternate timeline
3. **Make a change**
4. **Examine the differences**

It's good practice to keep your "master" branch clean so that you can keep it synchronized with the original repository

---
class: exercise

# Your turn

https://github.com/isteves/typos

1. Fork the repo = make a copy of the repo on your account
2. Make a branch = start an alternate timeline
3. Make and commit a change
4. Submit a pull request
---
# Collaborating on a single repo

Eventually, you'll have to start thinking about .xlarge[merge conflicts]. This is especially true when you start to collaborate on a single repostory.

If you edit the same line of code or text as your collaborator, you will need to _manually_ resolve the conflict.

---
class: exercise

# Work in pairs

1. Choose one of your repos
2. Go into `Settings` --> `Collaborators`. Add your neighbor as a collaborator
3. Accept the email invitation

# Make a change

1. The collaborator - create a new git repository in RStudio
2. Both - make and commit a change ON THE SAME LINE
3. Collaborator - PUSH the change
4. Repo owner - PULL
5. Repo owner - resolve the conflict, COMMIT, and PUSH

---

---
# https://happygitwithr.com/

Ultimate guide for R/RStudio workflows with git/GitHub

- installation problems
- connecting GitHub to an RStudio project (or vice versa)
- setting up ssh
- how to "burn it all down" 🔥

---

# Use the terminal

Most of the resources online tell you what series of `git` commands to use to achieve your goal. The **terminal** is where you can type those commands

Check out these resources for step-by-step guides for:

- using `gitignore` to tell git what NOT to track
- dealing with merge conflicts
- collaborating using forks and branches
- burning it all down & starting afresh