Tuto_git.Rmd

---
title: 'Using `r icons::fontawesome("git-square")` with `r icons::fontawesome("r-project")`'
#subtitle: "slides : [https://tinyurl.com/2s4antdy](https://tinyurl.com/2s4antdy)"
author: "Maxime Jaunatre"
institute: "LESSEM | INRAE" 
date: "2022-12-01 (updated: `r Sys.Date()`)"
output:
  xaringan::moon_reader:
    lib_dir: libs
    css: [default, metropolis, metropolis-fonts]
    nature:
      highlightStyle: github
      highlightLines: true
      highlightSpans: true
      countIncrementalSlides: false
---

```{r setup, include=FALSE}
library(emo)
library(icons)
options(htmltools.dir.version = FALSE, knitr.duplicate.label = 'allow')
knitr::opts_chunk$set(fig.align = "center", eval = FALSE)
```

```{r, eval = FALSE, include = FALSE}
# This are the dependencies to compile this rmd.
remotes::install_github("mitchelloharawild/icons")
icons::download_fontawesome()
remotes::install_github("hadley/emo")
```


exclude: true

class: inverse, center, middle

# Introduction

---
exclude: true

# Using git in R

**Abstract :** 

Git is a version control system independent from R, it provides a neat way to stop the spread of old scripts sent by e-mail, enhances scientific reproducibility and provides a framework to collaborate on writing code with other people. This software can be used by every R-User, within Rstudio or using a command line tool, at any step of a project or package development. This session will present the core principles when managing code files with Git, and why it may save you time when working in a team. At the end of this session you will be able to use Git for saving your work and share it easily online on GitHub/GitLab. This may even be your first step in understanding how to contribute to your most loved open-source package on GitHub/GitLab.

---

background-image: url(./CSU_RepRo_files/figure-html/phd101212s.png)
background-size: contain

# Why do we need a CVS ?

???

CVS control version system

The production of R code is incremental in nature and requires the accumulation of different versions. It quickly becomes complicated to find your way around.  

---
exclude:true

# Why do we need a CVS ?

Est-ce que vous avez déjà :

- **Fait un changement de code et voulu revenir en arrière ?**
- **Perdu du code ou une sauvegarde trop ancienne ?**
- Voulu voir la difference entre 2 versions ?
- Voulu vérifier l'historique d'un script ?
- **Voulu travailler sur un script a plusieurs ?**
- **Voulu partager votre code à quelqu'un ?**
- Voulu tester une nouveauté sans modifier du code déjà utile ?

Si oui, et dans plein de cas, un système de version control aurait pu vous simplifier la vie.

???

Diapo dite à l'orale avec le comic suivant.

---
# Why do we need a CVS ?

```{r, engine='tikz', fig.ext = 'png', engine.opts = list(template = "tex/gitdags.tex"), echo = FALSE, eval=TRUE, cache=TRUE}

\begin{tikzpicture}
  \matrix (m)
    [
      matrix of nodes,
      nodes in empty cells,
      column sep      = 3em,
      row sep         = 5ex,
      column 1/.style = { nodes = { empty } },
      column 2/.style = { nodes = { empty } },
      column 3/.style = { nodes = { empty } },
      column 4/.style = { nodes = { empty } },
    ]
    {
        &  &  &  \\
        File.txt &  & File.txt & \com \\  % \textit{7f21c09}
        File1.txt &  & File.txt & \com \\ % \textit{d39ac60}
        File2.txt &  & File.txt & \com \\ % \textit{c78c64d}
        File\_final.txt &  & File.txt & \com \\ % \textit{cbdac1e}
    };
    \node[fit=(m-1-1)(m-1-1)]{Saving copies};
    \node[fit=(m-1-3)(m-1-4)]{Git workflow};

  \foreach \i/\j in {2/3,3/4,4/5} {
    \draw [arrow] (m-\i-4) -- (m-\j-4);
    \draw [arrow] (m-\i-3) -- (m-\i-4);
    \pic at (m-\i-2) {file};
  }
  \draw [arrow] (m-5-3) -- (m-5-4);
  \pic at (m-5-2) {file};
  
\end{tikzpicture}
```


???

Comparison between a "classic" history and a history with git. The file name is not modified anymore and is therefore easier to find.

---
# Keeping a history with Git

## What is a commit ?

We have seen that it is a snapshot, but it contains more meta-data!

.pull-left[

- List of edited files

- Differences of edited lines

- Previous commit (parent)
]

.pull-right[
- Author and email

- Date

- Message
]

???

Git saves only different lines so it's useful for versioning a bit raw files, like code, csv or svg. Images change each time (like pdfs !)

Previous commit -> notion of tree and history !
--

And a HASH (or SHA) (unique identifier) 

**<u>a64bc14</u>da18e47629e62b8e54d33d429c4b824e0**

The underlined part is usually sufficient.

---
# Keeping a history with Git

## Anatomy of a commit : git log

You can find the log of all the history like that in the terminal.

```{bash}
$ git log
```

Example :

```{bash}
commit f36044df028b44352c293bafb0d6016b666c09c0
Author: Maxime <myveryownmail@mail.com>
Date:   Sun Nov 21 22:30:43 2021 +0100

    Time of deco stop near MN90 values

    Values are very close to MN90 tables, error should be due to different
    number and half life of compartments.
    Require to think how to set this in nice function so we can use them to
    plan dives but also represent saturations in later graphs !


```

---
# Keeping a history with Git

```{r, out.width="85%", echo = FALSE, eval=TRUE}
knitr::include_graphics("CSU_RepRo_files/figure-html/commit_mess.png")
```

.footnote[
xkcd comics, [CC BY-NC 2.5 license](https://xkcd.com/license.html)
]

???

On the usefulness of putting a comment that makes sense.


---
# Repository 

A repository is the **folder** in which git is used and the sum of all files tracked.

All git information is in **.git** and it's better to not touch it.

We just need to say to git : start tracking this file now with the keyword **ADD**

```{r pull_push_diag, engine='tikz', fig.ext = 'png', engine.opts = list(template = "tex/gitdags.tex"), echo = FALSE, eval=TRUE, cache = TRUE}
\begin{tikzpicture}[block/.style={draw,fill=strange,minimum height=2.5em},
    font=\sffamily,>=stealth]

    \begin{scope}[start chain=A going below,node distance=1em,
                  local bounding box=buffers]
        % \node[block,minimum width=6em](remote){Remote github};
        \node[block,minimum width=6em](local){Fichiers};
    \end{scope} 

    \node[right= 6em of buffers,align=center, block,minimum width=6em](repo){Repository \\Git local};

    \draw[->,thick](local) edge[bend left] node[midway, fill=white]{Add} (repo);
    \draw[->,thick](repo) edge[loop right] node[midway, fill=white]{Commit} (repo);
    
\end{tikzpicture}
```

### .gitignore

File to list all sensible files that we **don't** want to save. Like *data/* or temporary files *rmd.log*, *.Rhistory* etc...

---

```{r child='github.Rmd', eval=TRUE}
```


---

```{r child='git_exo.Rmd', eval=TRUE}
```


---
exclude: false

# Ressources Git

.pull-left[

- [Tutoriel ThinkR : R and Git](https://thinkr.fr/travailler-avec-git-via-rstudio-et-versionner-son-code/)

- [Advance R &#x1F4D4;, H. Wickham](https://adv-r.hadley.nz/)

- [Happy Git and GitHub for the useR](http://happygitwithr.com/)

- [Git cheatsheet](https://services.github.com/on-demand/downloads/github-git-cheat-sheet.pdf)

- [Quand ça part en vrille](https://github.com/k88hudson/git-flight-rules)

- [Réparer une erreur](http://ohshitgit.com/)

- [Créer une nouvelle branche avec git et merge des branches](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches)
]

.pull-right[
```{r, out.width="90%", eval = TRUE, echo = FALSE}
knitr::include_graphics("Tuto_git_files/figure-html/git.png")
```
]

.footnote[
xkcd comics, [CC BY-NC 2.5 license](https://xkcd.com/license.html)
]

???

Beaucoup d'information est disponible.
Encore une fois, il vaut mieux commencer sur un petit projet où l'on est à l'aise.

---
class: inverse, center, middle

# Merci! Des questions &#x2753;

Slides en ligne [https://gowachin.github.io/R_presentation/Tuto_git.html](https://gowachin.github.io/R_presentation/Tuto_git.html)

[Fichiers source `r icons::fontawesome("r-project")`](https://github.com/gowachin/R_presentation) <!-- &nbsp;&nbsp;|&nbsp;&nbsp; [Fichier pdf `r icons::fontawesome("file-pdf")`](https://github.com/gowachin/R_presentation/raw/main/Tuto_git.pdf) -->

`r icons::fontawesome("github")` [gowachin](https://github.com/gowachin) &nbsp;&nbsp;&nbsp;&nbsp; `r icons::fontawesome("stack-overflow")` [gowachin](https://stackoverflow.com/users/12501379/gowachin)

.footnote[
Slides created via the R package [**xaringan**](https://github.com/yihui/xaringan).
]