Version Control & Project Management

# Version Control & Project Management
### Alec Robitaille
### 2020-02-06

---

# Project Management

```
]

.pull-right[
```
project
└───data/
    └───derived/
    └───raw/
└───R/
└───script/
└───graphics/
└───README.md
```
]

.footnote[[Efficient R: Projects](https://csgillespie.github.io/efficientR/set-up.html#project-management)]

---
class: review

# Exercise: an example project

1. Find and open scripts

1. Modify the subset of the input data

1. Modify the plot and save in the appropriate folder

1. Document your changes in the code comments and README.md 
]

---

# Review:

1. organize files into folders and number scripts

1. separate input/output files

1. keep raw data raw

1. document everything

1. save intermediate objects (.Rds) `\(^{[1]}\)`
]

.footnote[
`\(^{[1]}\)`: [Efficient R: IO](https://csgillespie.github.io/efficientR/input-output.html#top-5-tips-for-efficient-data-io)
]

---
# What is git?

---
# Why use git? Why use GitLab / GitHub?

.large[
* Open science
* Collaboration
* Exposure
* Reproducible research
* Connect with larger community (e.g.: rOpenSci, Carpentries)
]

.footnote[
![:scale 20%](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e0/Git-logo.svg/1280px-Git-logo.svg.png)
![:scale 20%](https://about.gitlab.com/images/press/logo/svg/gitlab-logo-gray-rgb.svg) ![:scale 20%](https://s19386.pcdn.co/wp-content/uploads/2017/10/github-logo-1.png)

[Why use Git/GitHub - Jenny Bryan](https://peerj.com/preprints/3159v2/)]

???
gitlab/github simply host the repository

---
# Examples

.large[
* books: [Advanced R](https://adv-r.hadley.nz/), [Efficient R](https://csgillespie.github.io/efficientR/). 
* websites: [robitalec.ca](http://robitalec.ca)
* courses: [stat545](https://github.com/rstudio-education/stat545)
* papers: [Noise Phenomena](https://github.com/cboettig/noise-phenomena) and [WEEL/SocCaribou](https://gitlab.com/WEEL_grp/SocCaribou)
* packages: [`spatsoc`](https://github.com/ropensci/spatsoc)
]

---
# Git basics

---
class: review

# Guide: Making a new repository

At [gitlab.com/projects/new](https://gitlab.com/projects/new):

1. Name your project (no spaces)
1. Check the namespace (e.g.: `robit.a/potato` vs `WEEL/potato`)
1. Set visibility level (public/private)
1. Check initialize with a README
1. Create project
1. [Add members](https://gitlab.com/robit.a/potato/-/project_members)

On your computer:

1. Use GitAhead to clone or `git clone https://gitlab.com/robit.a/potato.git`
1. Make edits, commit, push, ...

---

# Exercise: paired practice

#### Together:
1. Create a new repository on GitLab.com under one of your namespaces 
1. Set members (include me!)
1. Clone the repository to one computer
1. Setup a new project (together)
1. Commit and push your changes (together)
1. Clone the project on the other computer
]

---

# Exercise: paired practice

#### Separate:
1. Make changes to *different files*
1. Practice rebasing, merging changes

---
class: review

# Exercise: paired practice - branches

.large[
#### Separate:
1. Create a branch 
1. Make some changes on your own branch
1. Commit, push
1. Checkout your partner's branch
1. Merge them both into the master branch
]

---

.pull-left[
### Git subtleties
* Git doesn't track folders, only the files within them
* Conflicts occur when two or more people change the same lines of the same file
* Git can't diff binary files e.g.: docx files
]

.pull-right[
### Best practices
* Commits should be atomic
* Commit messages should be informative and use imperative mood
* Always commit before pulling
* Always fetch before pulling

[![](https://imgs.xkcd.com/comics/git_commit_2x.png)](https://xkcd.com/1296/)

[Plenty more...](https://sethrobertson.github.io/GitBestPractices/)

]

---

# Exercise: your own project!

1. Set members, optionally share with the WEEL group

1. Clone the repository to your computer

1. Add your scripts, etc. to folders

1. Commit and push your changes

1. Continue using Git?
]

---
# Resources

[Data Carpentry: Version Control with Git](http://swcarpentry.github.io/git-novice/)

[Pro Git](https://git-scm.com/book/en/v2)

---
# Etc: setup GitAhead with GitLab

1. Fill GitLab username
1. [Generate a personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
    1. [Gitlab.com -> Profile -> Personal Access Tokens](https://gitlab.com/profile/personal_access_tokens)
    1. Name it `gitahead`
    1. Grant it all permissions except read_registry
1. Copy the access token and use it to fill the password