_02_basic_git.Rmd

---
title: "Git Basics"
output:
  xaringan::moon_reader:
    css: [default, rd.css, rd-font.css, "hygge"]
    lib_dir: assets
    seal: false
    nature:
      highlightStyle: dracula
      countIncrementalSlides: false
      beforeInit: "macros.js"
---


# Git Basics

```{r setup_02, include = FALSE}
source("_setup.R")
# knitr::clean_cache(TRUE)
htmltools::tagList(
  xaringanExtra::use_clipboard(
    button_text = "<i class=\"fa fa-clipboard\"></i>",
    success_text = "<i class=\"fa fa-check\" style=\"color: #37abc8\"></i>",
  ),
  rmarkdown::html_dependency_font_awesome()
)
xaringanExtra::use_scribble()
```




---

# Prerequisite: `r gt()`


## `r gt()` installed


```{bash}
git --version
```


---
# Prerequisite: a terminal `r lc()`

### All users

- [R Studio](https://support.rstudio.com/hc/en-us/articles/115010737148-Using-the-RStudio-Terminal-in-the-RStudio-IDE)

--

### Windows 

- [Cygwin](https://www.cygwin.com/) / [Windows 10 bash shell](https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/)

--

### Perso

- I work on [Debian](https://www.debian.org/) / my Desktop environment is [Gnome](https://www.gnome.org/)
- I use [gnome-terminal](https://help.gnome.org/users/gnome-terminal/stable/) with [Z shell](https://en.wikipedia.org/wiki/Z_shell) and a configuration framework named [prezto](https://github.com/sorin-ionescu/prezto) 




---

class: inverse, center, middle

# Your local `r gt()` repo

![:custom_hr]()

## Set your local `r gt()` repository up.




---
# Initiate your repository: `git init`

```sh 
$ mkdir proj1
$ cd proj1
$ git init 
#> Initialized empty Git repository in /path/to/proj1/.git/
```



---
# Initiate your repository: `git init`

## What just happened?

### The database `.git` has been created 

```sh
$ tree .git
#> .git
#> ├── config
#> ├── description
#> ├── HEAD
#> ├── hooks
#> │  └── README.sample
#> ├── info
#> │  └── exclude
#> ├── objects
#> │  ├── info
#> │  └── pack
#> └── refs
#>    ├── heads
#>    └── tags
```



---
# Inspect your repository: `git status`

## Use `git status`!

--

```sh
$ git status
#> On branch main

#> No commits yet

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


--

- `r nf()` `man git status`, `git status --help`,  `git status -h`


---
# `r lc()` Let's do this 

## Initiate a repo and check it.




---

class: inverse, center, middle

# Basic workflow

![:custom_hr]()


---
# Basic workflow 

### 1. Initiate the repository (`git init`)

--

### 2. Edit your files

--

### 3. Stage the modifications to be committed (`git add`)

--

### 4. Create a new commit object (`git commit`)

--

### 5. Go back to step 2.

---
# Edit a file and check the repo

```sh
$ echo "# Our great project" > README.md  
```

```sh
$ git status
#> On branch main

#> No commits yet

#> Untracked files:
#>   (use "git add <file>..." to include in what will be committed)
#> 	README.md

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

--

```sh
$ git status -s
#> ?? README.md
```

- `r nf()` ` git status -s` =  `git status --short`


---
# Track a file: `git add`

- See https://github.com/git-guides/git-add

```sh
$ git add README.md
```

--

<br>

## README.md `r ar()` Staging area

--


### README.md `untracked` `r ar()` README.md `staged`

---
# Track a file: `git add`


```sh
$ git status 
#> On branch main
#>
#> No commits yet
#>
#> Changes to be committed:
#>   (use "git rm --cached <file>..." to unstage)
#> 	new file:   README.md
```

--

```sh
$ git status -s
#> A  README.md
```


---
# What happened? 

- `README.md` has been added to the staging area (a.k.a. "the index");

- The file `README.md` is now a *blob* in `.git`;

- To ensure integrity, `r gt()` has computed a [SHA-1](https://en.wikipedia.org/wiki/SHA-1) for it;

--

```sh
git ls-tree -r HEAD
#> 100644 blob 1f18e72276e6dda33cca0065b1f8dd377c72c8c6	README.md
```

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_1.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_2.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_3.png)]


---
# Edit and check again

```sh
$ echo "This is a great project" >> README.md  
```

--

### 1. In staging area: **"#Our great project"** ready to be committed

### 2. Workspace: README.md is modified **"+ This is a great project"**


---
# Edit and check again


```sh
$ git status  
#> On branch main
#>
#> No commits yet
#>
#> Changes to be committed:
#>  (use "git rm --cached <file>..." to unstage)
#>  new file:   README.md
#> 
#> 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:   README.md
```

```sh
$ git status -s
AM README.md
```

---
# `r lc()` Let's do this 

## Edit and check a file.




---
# Create a first commit: `git commit`


```sh
$ git add README.md
```

--

```sh
$ git commit -m "Add our README"
#> [main (root-commit) 618b684] Add our README
#>  1 file changed, 2 insertions(+)
#>  create mode 100644 README.md
```

--

```sh
$ git status 
#> On branch main
#> nothing to commit, working tree clean
```


---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_3.png)]

---
# How `r gt()` works
.center[![:scale 92%](img/part2/ct_4.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_5.png)]



---
# `r lc()` Let's do this 

## Create a commit.



---
# Initiate, stage & commit with `r rp()`

- Use package [`gert`](https://CRAN.R-project.org/package=gert)

```{R init, eval = FALSE}
if (!file.exists("proj1")) dir.create("proj1")
setwd("proj1")
library(gert)
git_init() 
writeLines("# Our great project\n This is a great project", "README.md") 
git_add("README.md")
git_status()
git_commit("Add our README")
```

---
# Initiate your repository with `r rp()`

## With `gert`

- `git init` `r ar()` `git_init()`
- `git add` `r ar()` `git_status()`
- `git commit` `r ar()` `git_commit()`


## Use `r gt()` from `r rp()`

- `system()` and `system2()` to pass any command



---
# One more commit 

```sh
$ echo "seq_nrow <- function(x) seq_len(NROW(x))" > seq_nrow.R
$ git add seq_nrow.R
$ git commit -m "Add seq_nrow()"
#> [main dd28a77] Add seq_nrow()
#>  1 file changed, 1 insertion(+)
#>  create mode 100644 seq_nrow.R
```

???
more than one file at the time.



---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_6.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_7.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_8.png)]

---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_9a.png)]


---
# How `r gt()` works

.center[![:scale 92%](img/part2/ct_9b.png)]




---
# One more commit 

```sh
$ echo "Cool seq_nrow() function" >> README.md
$ git status -s 
#>  M README.md
$ git add README.md
$ git commit -m "Improve the documentation"
#> [main 58d5363] Improve the documentation
#>  1 file changed, 1 insertion(+)
```

???
do this one with commit without -m
and explain that you can use an editor


---
# `r lc()` Let's do this 

## Create two more commits.

## Do not use option `-m` for the second one and add a body. 


---
# How to create a good commit?

### Hard to say! 

--

### Some rules of thumb!

- 1 commit = one goal 
- 1 commit = a digestible amount of code (no minimal amount of code)


---
# How to write a good commit message?

--

### It may depend on the project! 

--

### Good habits 

- https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
- https://cbea.ms/git-commit/
  - Separate subject from body with a blank line
  - Limit the subject line to 50 characters
  - Capitalize the subject line
  - Do not end the subject line with a period
  - Use the imperative mood in the subject line
  - Wrap the body at 72 characters
  - Use the body to explain what and why vs. how

- https://gitmoji.dev/

???
may be one more commit with body



---
# Basic workflow 


- https://ndpsoftware.com/git-cheatsheet.html#loc=workspace 






---

class: inverse, center, middle

# Navigate your history

![:custom_hr]()

log and checkout/switch


---
# Check the history `git log`

## Use `git log`! (see [Pro Git](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History))

```sh
$ git log 
#> commit 8c43aea1ba20ddaccd3c469b7928f532d88275fc (HEAD -> main)
#> Author: Kevin Cazelles <kevin.cazelles@insileco.io>
#> Date:   Tue Jan 18 21:07:36 2022 -0500
#>  
#>     Improve the documentation
#>  
#> commit 7ab0cfb54a54bd732991a4998be0c36d84021452
#> Author: Kevin Cazelles <kevin.cazelles@insileco.io>
#> Date:   Tue Jan 18 21:06:57 2022 -0500
#>  
#>     Add seq_nrow()
#>  
#> commit cbb5a9e2aafb7ad16a8e5dc8f682718946d83292
#> Author: Kevin Cazelles <kevin.cazelles@insileco.io>
#> Date:   Tue Jan 18 21:06:30 2022 -0500
#>  
#>     Add our README
```

???
a lot of options

---
# Check the history `git log`

## `git log` has a lot of options


```sh
$ git log --oneline
#> 8c43aea (HEAD -> main) Improve the documentation
#> 7ab0cfb Add seq_nrow()
#> cbb5a9e Add our README
```
--

```sh
$ git log --pretty=format:"%h - %an, %ar : %s"
#> 8c43aea - Kevin Cazelles, 3 minutes ago : Improve the documentation
#> 7ab0cfb - Kevin Cazelles, 4 minutes ago : Add seq_nrow()
#> cbb5a9e - Kevin Cazelles, 4 minutes ago : Add our README
```

- see [Pro Git](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History)

---
# Navigate your history

```sh
$ git log --oneline
#> 8c43aea (HEAD -> main) Improve the documentation
#> 7ab0cfb Add seq_nrow()
#> cbb5a9e Add our README
```

```sh
$ tree 
#> .
#> ├── README.md
#> └── seq_nrow.R
```

---
# Navigate your history: `git checkout`

```sh
$ git checkout cbb5a9e
#> Note: switching to 'cbb5a9e'.
#> 
#> You are in 'detached HEAD' state. You can look around, make experimental
#> changes and commit them, and you can discard any commits you make in this
#> state without impacting any branches by switching back to a branch.
#> 
#> If you want to create a new branch to retain commits you create, you may
#> do so (now or later) by using -c with the switch command. Example:
#> 
#>   git switch -c <new-branch-name>
#> 
#> Or undo this operation with:
#> 
#>   git switch -
#> 
#> Turn off this advice by setting config variable advice.detachedHead to false
#> 
#> HEAD is now at cbb5a9e Add our README
```

---
# Navigate your history


```sh
$ tree 
#> .
#> └── README.md
```

```sh
$ git status
#> HEAD detached at cbb5a9e
#> nothing to commit, working tree clean
```


---
# Navigate your history: `git switch`

```sh
git switch -
```

--

<br>

## `git switch` or `git checkout`?

--

### `git checkout` does a lot! v2.23 introduces `git switch` and `git restore` to have aliases of subsets of what it does (see e.g. [this link](https://tanzu.vmware.com/developer/blog/git-switch-and-restore-an-improved-user-experience/))



---
# Navigate your history: `git switch`


```sh
$ git checkout cbb5a9e
```

or (and **preferred**)

```sh
$ git switch -d cbb5a9e
```

or 

```sh
$ git checkout HEAD~2
```

or 

```sh
$ git switch -d HEAD~2
```

- https://stackoverflow.com/questions/2221658/whats-the-difference-between-head-and-head-in-git

---
# What happened?

.center[![:scale 100%](img/part2/sp_4.png)]

---
# What happened?

.center[![:scale 100%](img/part2/sp_6.png)]


---
# `r lc()` Let's do this 

## Navigate our history.


---
# What happened?

```sh
git switch -d cbb5a9e 
```

--

- `r gt()` has pulled out the snapshot from `.git`.

- The HEAD is now detached: 
  - you can still commit but it won't replace the commits you've done;
  - branch will be on a different commit history;
  - so far it won't have any impact and won't really be part of your work;
  - if want to include it in your "regular" history, you can branch.

???
good transition








---
class: inverse, center, middle

# Branching

![:custom_hr]()

## `r gt()` killer feature! 


???
Any question so far


---
# Branching

## 1. Branch, branch and branch! 

--

## 2. Use `git branch` a lot!

<br>

--

### Branching allows you to create divergent history ...

--

### ... which is exactly what you need for collaboration.


---
# Branching

```sh
$ git branch topicA
$ git switch topicA
#> Switched to branch 'topicA'
```

--

### with one line 

```sh
$ git switch -c topicA
#> Switched to branch 'topicA'
```

---
# Branching

```sh
$ git status
#> On branch topicA
#> nothing to commit, working tree clean
```

--

```sh
$ git log --oneline
#> cb1eba0 (HEAD -> topicA, main) Improve the documentation
#> 630c33e Add seq_nrow()
#> 0f2ea9b Add our README
```

---
# A commit on the new branch 

```sh
$ echo "seq_ncol <- function(x) seq_len(NCOL(x))" > seq_ncol.R
$ git add seq_ncol.R
$ git commit -m "Add seq_ncol()"
```


---
# A commit on the new branch 

```sh
$ git log --oneline
#> 97832ed (HEAD -> topicA) Add seq_ncol()
#> cb1eba0 (main) Improve the documentation
#> 630c33e Add seq_nrow()
#> 0f2ea9b Add our README
```

---
# What happened?

### A new pointer, `topicA`, has been created.

--

### The `HEAD` now points to `topicA`.

--

### A new commit has been created, its parent is the last commit on `main`.



---
# How `r gt()` works

.center[![:scale 90%](img/part2/com_1.png)]

---
# How `r gt()` works

.center[![:scale 90%](img/part2/com_2.png)]

---
# How `r gt()` works

.center[![:scale 90%](img/part2/com_3.png)]

---
# How `r gt()` works

.center[![:scale 90%](img/part2/com_4.png)]

---
# How `r gt()` works

.center[![:scale 90%](img/part2/com_5.png)]


---
# How `r gt()` works 

.center[![:scale 90%](img/part2/br_1.png)]


---
# How `r gt()` works - branch

.center[![:scale 90%](img/part2/br_2.png)]


---
# How `r gt()` works - switch 

.center[![:scale 90%](img/part2/br_3.png)]


---
# How `r gt()` works - commit

.center[![:scale 90%](img/part2/br_4.png)]



---
# Merging `git merge`

```sh
$ git switch main 
$ git merge topicA 
#> Updating 64ee016..aadf541
#> Fast-forward
#>  seq_ncol.R | 1 +
#>  1 file changed, 1 insertion(+)
#>  create mode 100644 seq_ncol.R
```



---
# How `r gt()` works - commit

.center[![:scale 90%](img/part2/br_4.png)]


---
# How `r gt()` works - switch 

.center[![:scale 90%](img/part2/br_5.png)]


---
# How `r gt()` works - merge (fast forward)

.center[![:scale 90%](img/part2/br_6.png)]

???
now let's use references (refs) for pointers and objects for objets

---
# Not always as simple! 

.center[![:scale 90%](img/part2/br2_1.png)]

---
# How `r gt()` works - commit

.center[![:scale 90%](img/part2/br2_2.png)]

---
# How `r gt()` works - merge

.center[![:scale 90%](img/part2/br2_3.png)]




---
# Merge commit

```sh
$ git switch -d HEAD~2
$ git switch -c topicB
```

--

```sh
$ echo "one more line" >> README.md
$ git add README.md
$ git commit -m "Improve documentation"
```

--

```sh
$ git switch main
```

--

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

### `r tr()` Interactive merge `r tr()`

---
# Interactive merging 


```sh
# check what to do
$ git status
```

--

```sh
# stop merging
$ git merge --abort
```

--

```sh
# add file for which conflict has been resolved.
$ git add README.md
```

--

```sh
# end conflicts resolution/ end merging
$ git commit -m "merge commit"
```

--

```sh
# go next step
$ git merge --continue
```



---
# `r lc()` Let's do this 

## Merge a branch. 

### List your branches 

```sh
$ git branch 
#> * main
#>   topicA
```

### Delete a branch 

```sh
$ git branch -d topicA
#> Deleted branch topicA (was 015e4d0).
```



---
# Accept all changes `-X` - `ours` or `theirs`

Accept all changes on current branch (`ours`) or on the branch to be merged (`theirs`)"


```sh
$ git merge -Xours topicB
```

```sh
$ git merge -Xtheirs topicB
```

E.g

```sh
$ git merge -Xours topicB
#> Auto-merging README.md
#> Merge made by the 'ort' strategy.
```

???
'ort' used to 'recursive' and t is faster and defaut
https://www.spinics.net/lists/git/msg401416.html
"Ostensibly Recursive's Twin"


---
# Merging strategies 

### `r lk()` https://git-scm.com/docs/merge-strategies






---
# Rebasing 

### Let's rewind and use `git rebase` instead of `git merge`


---
# How `r gt()` works 

.center[![:scale 90%](img/part2/reb_1.png)]

---
# How `r gt()` works - rebase

.center[![:scale 90%](img/part2/reb_2.png)]

---
# How `r gt()` works - rebase

.center[![:scale 90%](img/part2/reb_3.png)]

---
# How `r gt()` works - merge (fast forward)

.center[![:scale 90%](img/part2/reb_4.png)]



---
# Rebasing 


```sh
$ git rebase main 
#> Auto-merging README.md
#> CONFLICT (content): Merge conflict in README.md
#> error: could not apply d8b6335... Improve documentation
#> 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 d8b6335... Improve documentation
```


### `r tr()` interactive mode `r tr()`


---
# `r lc()` Let's do this 

## Rebase a branch. 






---
class: inverse, center, middle

# Ignore, amend and stash

![:custom_hr]()


---
# Ignoring files 


```sh
$ echo "SECRET" > .oauth
$ git status -s
#> ?? .oauth
```

--

```sh
$ echo ".oauth" > .gitignore
$ git status -s
#> ?? .gitignore
$ git add .gitignore
$ git commit -m "Add .gitignore"
```
You no longer have to worry about `.oauth`

- `r gt()` https://github.com/github/gitignore


---
# Amend a commit

```sh
$ git log --oneline
#> 97832ed (HEAD -> topicA) Add seq_ncol()
#> cb1eba0 (main) Improve the documentation
#> 630c33e Add seq_nrow()
#> 0f2ea9b Add our README
```

## Oops! I forgot to add something to the last commit!


---
# Amend a commit

```sh
$ echo "one more line" >> README.md
$ git add README.md
```

--

```sh
$ git commit --amend
```

--

## `r tr()` Rewrites the last commit!


---
# Amend a commit

### Used to be

```sh
$ git log --oneline
#> 97832ed (HEAD -> topicA) Add seq_ncol()
#> cb1eba0 (main) Improve the documentation
#> 630c33e Add seq_nrow()
#> 0f2ea9b Add our README
```

--

### Now 

```sh
$ git log --oneline
#> 07af32e (HEAD -> topicA) Add seq_ncol()
#> cb1eba0 (main) Improve the documentation
#> 630c33e Add seq_nrow()
#> 0f2ea9b Add our README
```


---
# Stash

### An extra area where you can stash your last work

--

### Stash some of your modifications (workspace/staging area)

```sh
$ git stash
```

--

### Put it back

```sh
$ git stash pop
```

--

### Delete what was stashed  

```sh
$ git stash drop
```

---
# Stash


### Oops! that should be done in a different branch 

```sh
$ git stash branch topicC
```

--

- `r lk()` [stash tricks](https://www.freecodecamp.org/news/useful-tricks-you-might-not-know-about-git-stash-e8a9490f0a1a/)



---
# `r lc()` Let's do this 

## Amend and stash

- https://ndpsoftware.com/git-cheatsheet.html#loc=workspace