Excuse me, do you have a moment to talk about version control?

.title[
# Excuse me, do you have a moment to talk about version control?
]
.subtitle[
## A dive into Git and GitHub
]
.author[
### INFO 5940 <br /> Cornell University
]

---

# How was your Fall Break?

]

---

# Git? What?

---

## Why Git?

.footnote[Source: [Excuse Me, Do You Have a Moment to Talk About Version Control?](https://www.tandfonline.com/doi/full/10.1080/00031305.2017.1399928)]

- Version control system
- Repository

---

## Why GitHub?

]

]

---

## GitHub vs. GitHub Enterprise

- <https://github.com>
- <https://github.coecis.cornell.edu/>

What's the difference between them?

---

## Why bother?

### Will it hurt?

**Yes** 🤷

- More complicated workflow
- Clunky at first
- Need to break bad habits

### What's the payoff?

- Ease of access
- Collaboration

]

]

---

# Configuring and using Git with `usethis`

---

## Configuring and using Git with `usethis`

### `usethis`

```r
library(usethis)
use_git_config(
  user.name = "Jane Doe",
  user.email = "jane@example.org"
)
```

```r
# default branch named 'main'
git_default_branch_configure()
```

]

### From the shell

```bash
git config --global user.name 'Jane Doe'
git config --global user.email 'jane@example.com'

git config --global init.defaultBranch main
```

]

---

# New project, RStudio first

---

## ⏱ Create a local Git repo

- Run `usethis::use_course("css-skills/practice-repo")` in the R console
- Create Git repo with `use_git()`
- Practice generating **commits**

---

## 🔑 Key terms

- Stage
- Commit
- Push

---

## `.gitignore`

```r
usethis::edit_git_ignore(scope = "project")
```

---

## Connect RStudio and GitHub

- Interacting with GitHub
- Providing **credentials**

### Authentication methods

- Personal access token (PAT)
- SSH key

`usethis` requires PAT

---

## ⏱ Painless authentication with PAT

.panel-name[GitHub Enterprise]
```r
usethis::create_github_token(
  scopes = c("repo", "user", "gist", "workflow"),
  description = "RStudio Workbench",
  host = "https://github.coecis.cornell.edu/"
)
```

```r
gitcreds::gitcreds_set(url = "https://github.coecis.cornell.edu/")

#> ? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#> -> Adding new credentials...
#> -> Removing credentials from cache...
#> -> Done.
```

]

```r
usethis::create_github_token(
  scopes = c("repo", "user", "gist", "workflow"),
  description = "RStudio Workbench"
)
```

```r
gitcreds::gitcreds_set()

#> ? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#> -> Adding new credentials...
#> -> Removing credentials from cache...
#> -> Done.
```

]
]

---

## ⏱ Connect project to GitHub

```r
usethis::use_github(host = "https://github.coecis.cornell.edu/")
```

---

## Get a sitrep

```r
usethis::git_sitrep()
```

---

## Tired of setting `host`?

Change the default GitHub host using `.Renviron`

```r
usethis::edit_r_environ(scope = "user")
```

Add to the file:

```
GITHUB_API_URL="https://github.coecis.cornell.edu/"
```

Restart R, then all `usethis` functions involving Git will always use GitHub Enterprise

---

# New project, GitHub first

---

## ⏱ New project, GitHub first

Create a Git controlled project already connected to GitHub

1. Make a repo on GitHub
1. New RStudio Project via RStudio \> New Project \> Version Control \> Git
1. Copy files from the first project to the new project
    - Stage
    - Commit
    - Push

---

# Git for collaboration

---

## Git for collaboration

.footnote[Source: [Excuse Me, Do You Have a Moment to Talk About Version Control?](https://www.tandfonline.com/doi/full/10.1080/00031305.2017.1399928)]

---

## Git for collaboration

.footnote[Source: [Excuse Me, Do You Have a Moment to Talk About Version Control?](https://www.tandfonline.com/doi/full/10.1080/00031305.2017.1399928)]

---

## ⏱ Incorporating changes from GitHub

1. Make a change on GitHub and commit
1. **Pull** changes from GitHub locally

---

# Avoid messes with branches

---

## Branching

---

## ⏱ Create a branch

1. Create a branch using RStudio
1. Modify a file in the repo
1. Stage, commit, and push to GitHub
1. Check the repo on GitHub - what has changed?

---

## Merging branches

```bash
git checkout main
git merge BRANCH-NAME
```

---

## Merge conflicts

---

## Merge conflicts

```bash
git merge documentation
# Auto-merging README.md
# CONFLICT (content): Merge conflict in README.md
# Automatic merge failed; fix conflicts and then commit the result.
```

```bash
<<<<<<< HEAD:README.md
Contact: ben@bensoltoff.com
=======
Please contact me at ben@bensoltoff.com
>>>>>>> documentation:README.md
```

- Resolving merge conflicts

---

## ⏱ Practice a merge conflict

- Generate distinct changes in the README file
    - One form locally
    - Another form on GitHub
- Attempt to push to GitHub
- Pull from GitHub, resolve merge conflicts
- Stage, commit, and push

---

# Contributing to internal projects

---

.footnote[Source: [Planned Parenthood](https://plannedparenthood.tumblr.com/post/175851570842/national-french-fry-day-is-today-but-you-can-use)]

---

## Pull requests

- Inform others about changes you've pushed
- Discuss and review potential changes with collaborators
- Easily add follow-up commits before changes are merged

---

## ⏱ Create a pull request

1. Open a pull request from your new branch
1. Merge the pull request on GitHub
1. Pull the revised `main` branch to your local repo

---

# Contributing to external projects

---

## Forking

---

## Forking

---

## Forking

- `usethis`
    
    ```r
    usethis::create_from_github(
      repo_spec = "OWNER/REPO",
      host = "https://github.coecis.cornell.edu/"
    )
    ```

- Or interactively on GitHub

---

## ⏱ Forking

1. Create a fork of [`cis/practice-repo`](https://github.coecis.cornell.edu/cis/practice-repo)
1. Stage, commit, push a change to GitHub
1. Open a pull request to the original repo

---

## Other useful GitHub features

- Issues
- Discussion forums
- Private repos
- [Free GitHub Pro while you are a student](https://education.github.com/discount_requests/student_application)

---

## Other useful `usethis` functions

- [Pull request helpers](https://usethis.r-lib.org/articles/pr-functions.html)
- [All the `usethis` git functions](https://usethis.r-lib.org/reference/index.html#git-and-github)

---

## Don't use RStudio much?

Not required for Git!

- Pick a [Git client](https://git-scm.com/downloads/guis) (or do it all in the shell!)
- Check if your IDE has Git integration
- Use a [project-oriented workflow](https://rstats.wtf/project-oriented-workflow.html)

---

## When in doubt...