index.qmd

---
logo: "img/wtf-logo-square-transparent.png"
format: 
  revealjs: 
    theme: [night, slides.scss]
    highlight-style: a11y
    transition: fade
    slide-number: true
    chalkboard: true
    navigation-mode: linear
    controls: false
    mermaid-format: svg
execute:
  freeze: auto
from: markdown+emoji
---

# {background-image="img/forks.jpg"}

<h1><span class="highlight">using version control<span></h1>


## imagine we need to work on a document together 

how should we do that?  

## key questions

- which version of the document is the authoritative one?  
- if you and I change the same thing:
  - how will we know we did that?
  - whose edits should win?

```{r}
countdown::countdown(
  minutes = 3,
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em"
  )
```

## some solutions

::: {layout-nrow=1}
::: fragment
![dropbox](img/dropbox.svg){width=20%}
:::
::: fragment
![shared drive](img/fileserver.svg){width=20%}
:::
::: fragment
![email](img/email.png){width=20%}
:::
::: fragment
![google docs](img/googledocs.svg){width=20%}
:::
:::

::: notes
let's talk about how we're not solving the problem:

If you and I need to collaborate on a document _today_, what options do we have?

warm up discussion: consider these mechanisms for shared editing and limitations:

- dropbox
  - You have to trust dropbox to figure out conflicts for you and then hope they got it right
- email attachments
  - every email attachment of the document is a new, potentially authortiative copy and this gets increasingly confusing as you add collaborators
  - `doc_date_FINAL.docx`
- shared drive
  - typically only one person can modify the document at a time
- sharepoint
  - we may not have access to the same proprietary program for editing
  - depends on shared service access
- a google doc
  - google docs are pretty good, actually, until we start talking about code


what if you're working on code? what if your collaborators are strangers? what if they're halfway around the world?

plain text is a least common denominator
we're not assuming access to shared hardware
we are assuming that collaboration is async
:::

## on plain text

![beware](img/evernote.png)

::: notes
Be careful about storing valuable IP of yours in places that can take it away from you when they change business models
:::


# agenda

## agenda

- terminology
- terminalogy
- workflows: I
- tools
- workflows: II
- unhappy paths

## resources

::: columns

::: {.column}

### What They Forgot

[![](./img/wtf-logo-square-transparent.png)](https://rstats.wtf)
:::

::: {.column}

### Happy Git with R

[![](./img/happy-git.png)](https://happygitwithr.com)
:::

:::

## goals

![](./img/inception.webp)

::: notes
our objective is to go deeper
this workshop will emphasize terminal workflows and preview how other tools layer interactions on top
choose a workflow that works for you, and pick up sharper tools when needed
:::

# terminology

## git

_distributed_ version control system

::: notes
distributed = we all have a copy
contrast with other approaches where there is only one copy
:::

## repository

```bash
./
├── ChangeLog
├── config.site
├── configure*
├── configure.ac
├── configure.patch
├── COPYING
├── doc/
├── etc/
├── INSTALL
├── m4/
├── Makeconf.in
├── Makefile.fw
├── Makefile.in
├── po/
├── README
├── share/
├── src/
├── tests/
├── tools/
├── VERSION
└── VERSION-NICK
```

::: notes
a repository is a a project
opinions on the scope of what belongs in a single repository vary widely
monorepos?
:::

## remote

git vs. github / gitlab / bitbucket

::: notes
git is decentralized
github is how we coordinate
the authoritative copy is stored by the code host
:::

## clone / fork

::: notes
who has permissions to make changes to a consensus copy is managed by the service provider
forks are for untrusted collaborators / open source salt
:::

## commit

```{mermaid}
gitGraph
  commit id: "initial commit"
  commit id: "snapshot one"
  commit id: "snapshot two"
```

::: notes
a snapshot of project state
shopping cart analogy?
:::

## diff

```{mermaid}
gitGraph
  commit id: "initial commit"
  commit id: "snapshot one"
  commit id: "snapshot two"
```

::: notes
the difference between  _any_ two project snapshots
draw on the slides!
:::

## `HEAD`

```{mermaid}
gitGraph
  commit id: "initial commit"
  commit id: "snapshot one"
  commit id: "HEAD"
```

# terminalogy

## words have meaning

terminal  
shell  
command-line interface (CLI)[^so]

[^so]: https://askubuntu.com/a/506628


## structure

`command subcommand --long-argument -s`

## navigating

`pwd`  
`cd`  
`ls -lha`  

## creating

`mkdir <directory-name>`  
`rmdir <directory-name>`  
`touch <file-name.ext>`  
`cp <from-file> <to-file>`  
`mv `

::: callout-caution
`rm -rf <directory>`
:::


## look around

- create a directory
- put some files in it
- delete it

```{r}
countdown::countdown(
  minutes = 3,
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em",
  bottom = "30%"
  )
```

# workflows: I

## systems check

::: panel-tabset

### terminal

```bash
git config --global --list
```
### R

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


## systems check

hidden files:

::: panel-tabset

### terminal

```bash
ls -lha
```

### {{< fa brands windows >}}

![](./img/show-hidden-files.png)

### {{< fa brands apple >}}

`CMD + SHIFT + .`

:::

## new project

- create project (from rstudio, or terminal)

```bash
mkdir intro-git
cd intro-git
git init
```

::: notes
inspect the directory
presence of `.git` is what makes it a repository
you can be a productive user of git without deeply understanding the contents of that directory
:::

## `git status`

run often

## `git status`

```bash
❯ git status
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)
```

## add some files

```bash
touch index.qmd
```

## untracked files

```bash
❯ git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	_quarto.yml
	index.qmd

nothing added to commit but untracked files present (use "git add" to track)
```

## `git stage`

```bash
❯ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
	new file:   _quarto.yml
	new file:   index.qmd
```

::: notes
all the documentation you will ever see is for `git add`
:::

## {{< fa brands windows >}}

```bash
$ git add index.qmd
warning: LF will be replaced by CRLF in index.qmd.
The file will have its original line endings in your working directory
```

::: panel-tabset

### CR

`\r`

### LF

`\n`

### CRLF

`\r\n`

:::

<hr>

[dos2unix](https://linux.die.net/man/1/dos2unix)


## new project, who dis


::: panel-tabset

### terminal

```bash
git config --global user.name edavidaja
git config --global user.email david@posit.cor
```

### R

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

:::

## `git commit`


```bash
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
#
# Initial commit
#
# Changes to be committed:
#       new file:   _quarto.yml
#       new file:   index.qmd
"~/Documents/projects/intro-git/.git/COMMIT_EDITMSG" 12L, 255B
```

## `EDITOR`

::: panel-tabset

### vim

➡️normal mode  
`I`: insert mode, write a message  
`ESC`: return to normal mode  
`:` : command mode  
`wq`: write the file and quit  
`q!`: quit without saving  

### nano

`CTRL|CMD + O` to save  
`CTRL|CMD + X` to exit  

:::

## `git commit -m`

```bash
❯ git commit -m "initial commit"
[main (root-commit) cab0112] initial commit
 2 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 _quarto.yml
 create mode 100644 index.qmd
```

## `git status`

```bash
❯ git status
On branch main
nothing to commit, working tree clean
```

## repeat

with rstudio, vscode

## `git log`

```bash
❯ git log
commit 3efdc26af7bf6ea223bfa61c6cb4507de632690e (HEAD -> main)
Author: edavidaja <edavidaja@hey.com>
Date:   Thu Jul 20 15:03:03 2023 -0400

    added vs code workspace

commit 0d98a3c9cf2a351da39b26adbfad442c834ff8d4
Author: edavidaja <edavidaja@hey.com>
Date:   Thu Jul 20 14:55:34 2023 -0400

    added rstudio project files

commit cab0112f6f96bdd82a46e622d8fccd445fc38d17
Author: edavidaja <edavidaja@hey.com>
Date:   Thu Jul 20 14:51:23 2023 -0400

    initial commit
```
::: notes
discuss hashes
:::


## `git status`

```bash
❯ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   index.qmd

```


## publish to github

[existing project, github first](https://happygitwithr.com/existing-github-first.html)

## publish to github: setup

```bash
git remote add origin https://github.com/edavidaja/intro-git.git
git branch -M main
```

## `git push`

```bash
❯ git push -u origin main
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 418 bytes | 418.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/edavidaja/intro-git.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
```


## all together now

```bash
mkdir intro-git
cd intro-git
git init
touch _quarto.yml
git stage _quarto.yml
git commit -m "added quarto yml"
touch index.qmd
git stage index.qmd
git commit -m "added quarto document"
```

create intro-git on GH  
follow instructions to push

```{r}
countdown::countdown(
  minutes = 10,
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em"
  )
```

## `.gitignore`

```bash
.Renviron
.env
.Rproj.user
*.csv
data/
```

# tools

## launchers

::: columns

::: column

### {{< fa brands apple >}}

- [spotlight](https://support.apple.com/guide/mac-help/search-with-spotlight-mchlp1008/mac)
- [alfred](https://www.alfredapp.com/)
- [raycast](https://www.raycast.com/)

:::

::: column
### {{< fa brands windows >}}

- `CTRL + ESC`
- [PowerToys Run](https://learn.microsoft.com/en-us/windows/powertoys/run)

:::

:::


## terminals

::: columns

::: column
### {{< fa brands apple >}}

- [Terminal.app](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac)
- [warp](https://warp.dev)
- [iTerm2](https://iterm2.com/)


:::

::: column
### {{< fa brands windows >}}

- [wt](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701)

:::

:::

### cross-platform

[alacritty](https://alacritty.org/)

## shell helpers

- [Nerd Fonts](https://www.nerdfonts.com/)
- [starship](https://starship.rs/)
- [fig](https://fig.io)
- [`{prompt}`](https://github.com/gaborcsardi/prompt)
- `oh-my-*` ([zsh](https://ohmyz.sh/), [posh](https://ohmyposh.dev/), [bash](https://ohmybash.nntoan.com/))
- [fzf](https://github.com/junegunn/fzf)
- [atuin](https://atuin.sh/)


## command line interfaes

- [tldr](https://tldr.sh)
- [gh](https://cli.github.com/)

## editors

- [vs code](https://code.visualstudio.com/) 
- [sublime](https://www.sublimetext.com/)
- [notepad++](https://notepad-plus-plus.org/)

## git GUIs

[Recommended Git Clients](https://happygitwithr.com/git-client#recommended-git-clients)

## how?!

[personal radmin](https://rstats.wtf/personal-radmin)


# workflows: II

::: notes
1.  local workflow:
branch
commit
log
merge
log

2. GitHub Workflow
branch 
commit
log
push
open PR
merge on GH
pull

:::

## branch

```{mermaid}
gitGraph
  commit
  commit
  commit
  branch experiment
  checkout experiment
  commit
```

## create a branch

all equivalent:

```bash
❯ git branch new_branch
❯ git checkout new_branch
Switched to branch 'new_branch'
```
<br/>
<hr>
<br/>

```bash
❯ git checkout -b new_branch
Switched to a new branch 'new_branch'
```
<br/>
<hr>
<br/>


```bash
❯ git switch --create new_branch
Switched to a new branch 'new_branch'
```

## `git status`

```bash
❯ git status
On branch new_branch
nothing to commit, working tree clean
```

## back to main

```bash
❯ git checkout main
Switched to branch 'main'
```

<br/>
<hr>
<br/>

```bash
❯ git switch main
Switched to branch 'main'
```

## multiverse

- checkout `new_branch`
- edit an existing file
- commit
- switch back to main

```{r}
countdown::countdown(
  minutes = 10,
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em",
  bottom = "30%"
  )
```

## commit on branch

```bash
❯ git commit -am "commit on a branch"
[new_branch f1c234b] commit on a branch
 1 file changed, 3 insertions(+)

❯ cat index.qmd
---
title: happy git
---

❯ git checkout main
Switched to branch 'main'

❯ cat index.qmd

```

## merge

```{mermaid}
gitGraph
  commit
  commit
  commit
  branch experiment
  checkout experiment
  commit
  checkout main
  merge experiment
```

## `git merge`

```bash
git merge new_branch
❯ git merge new_branch
Updating 7614b5c..f1c234b
Fast-forward
 index.qmd | 3 +++
 1 file changed, 3 insertions(+)
```

## PRs

- checkout `second_branch`
- edit an existing file
- commit
- push the branch to GitHub


## `--set-upstream`

```bash
❯ git push
fatal: The current branch second-branch has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin second-branch

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.
```

## `git config`

[`git config --global push.autoSetupRemote true`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushautoSetupRemote)

<br/>

::: callout-warning
I set this globally because my workflow is pretty basic, ymmv
:::

## `git push -u`

```bash
❯ git push -u origin second-branch
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 308 bytes | 308.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'second-branch' on GitHub by visiting:
remote:      https://github.com/edavidaja/intro-git/pull/new/second-branch
remote:
To https://github.com/edavidaja/intro-git.git
 * [new branch]      second-branch -> second-branch
branch 'second-branch' set up to track 'origin/second-branch'.
```

## permissions & project management

![](./img/gh-pr.png)

::: notes
GitHub makes it easier to collaborate on who is allowed to make changes to projects and under what circumstances
you might want to condition a merge on whether all your test pass with the new code
:::

# unhappy paths

## push rejection

- make a new file locally, then try to push to GH

```bash
❯ git push
To https://github.com/edavidaja/intro-git.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/edavidaja/intro-git.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
```

```{r}
countdown::countdown(
  minutes = 2,
  # Fanfare when it's over
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em"
  )
```

## merge strategy

```bash
❯ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 636 bytes | 212.00 KiB/s, done.
From https://github.com/edavidaja/intro-git
   2bdda53..424444e  main       -> origin/main
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.
```


## merge conflicts

```{mermaid}
gitGraph
  commit
  commit
  commit
  branch experiment
  checkout experiment
  commit
  checkout main
  commit
```
## merge conflict

- modify a file on GH
- modify the same file locally

```bash
❯ git pull --rebase
Auto-merging main.R
CONFLICT (content): Merge conflict in main.R
error: could not apply 160ea3e... added tidyverse
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 160ea3e... added tidyverse
```

```{r}
countdown::countdown(
  minutes = 2,
  # Fanfare when it's over
  play_sound = FALSE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em"
  )
```

## 

```r
<<<<<<< HEAD
library(shiny)
||||||| parent of 160ea3e (added tidyverse)
=======
library(tidyverse)
>>>>>>> 160ea3e (added tidyverse)

```