git-training.qmd

# Presentation of the Git Software

## What is Git?

::: {.content-hidden when-format="pdf"}
![](https://git-scm.com/images/logos/downloads/Git-Logo-2Color.svg){height=75 fig-align="center"}
:::

::: {.content-visible when-format="pdf"}
![](https://git-scm.com/images/logos/downloads/Git-Logo-2Color.png){height=75 fig-align="center"}
:::

-   The most popular **Version Control Software** (VCS)
-   **Free** and **open source**
-   **Light** and **local** use (without internet)
-   Manages and **tracks versions** of a project (code, manuscript, data)
-   Can be linked with **remote server** (GitHub, Gitlab)

## What is Git for?

-   **Track changes** (*commits*) over time with information
    - **who**, **when** and **what** are the changes

-   Eventually go **back in time**

-   **Highlight a specific version** of the project (*tags*).
    - For example, new software versions.

-   **Synchronize** the project in the **cloud** with remote servers (GitHub, Gitlab)

-   **Resolve version conflict** when simultaneous changes

-   Create **derivates** of a project (*branches*):
    -   production, development, feature

-   **Publish** the project (open science)

## In short...

::: {layout-ncol="2" layout-valign="bottom"}
![Without Git](img/phd_comics.png){#fig-version-1 width="361"}

![With Git](img/git-flow.jpg){#fig-version-2 width="600"}
:::

# Installation and configurations

## Installing Git

**Windows and Mac**

Download and install Git from <https://git-scm.com/downloads>.

When done, open `Git Bash`

**Linux**

Open a `Terminal` window and type:

`sudo apt install git`

## A bit of Unix

To use Git on Git Bash or Terminal, we need to learn some basic Unix commands:

-   Change directory: `cd my/new/directory`
-   Go to parent directory: `cd ..`
-   Find current directory: `pwd`
-   List directory content: `ls`
-   Create new folder: `mkdir -p folder_name`
-   Create an empty file: `touch file.txt`
-   Copy a file: `cp file.txt save_file.txt`
-   Remove a file/folder: `rm -r file.txt`
-   Rename/Move a file: `mv file.text my/dest/renamed.txt`

## Git configuration

On `Git Bash` or in the `Terminal`:

-   Type `git config --global user.name "Firstname Lastname"`
-   Type `git config --global user.email "myadresse@ird.fr"`

::: callout-note
These two lines identify you in the history of a project.
:::

-   Type `git config --global --list` to see the global git configuration.

## Git configurations: aliases

To create Git aliases (i.e. shortcuts):

-   Type ```git config --global alias.tree "log --graph --decorate --pretty=oneline --abbrev-commit"```
-   Type `git config --global alias.br "branch -vv"`
-   Type `git config --global alias.re "remove -vv"`

You can now call the `git tree`, `git br` and `git re` commands.

# Getting started with Git in local

## Git architecture

```{mermaid}
%%|label: local-arch
%%| fig-width: 6
%%| fig-align: center
flowchart LR
    idw(Workspace)
    idi(Index)
    idl(Local)

    idw -->|git add| idi
    idi -->|git commit| idl

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;

```

-   `Workspace`: your working directory $\rightarrow$ your computer
-   `Local`: the local repository $\rightarrow$ contains the history of your project
-   `Index`: a buffer between `Workspace` and `Local` $\rightarrow$ list of the files that will be sent from `Workspace` to `Local`
-   `git add` : the command to add the file(s) in the `Index`
-   `git commit`: the command to validate the changes (moves the files from `Index` to `Local`)

::: callout-tip
To help understand, think of moving house. Workspace=old house; Local repository=new house; Changes=boxes; Index=moving truck
:::

## Getting started

-   Move to the folder where you want to work by using the `cd` command
-   Create a folder called `training-git` by typing `mkdir training-git`
-   Move to the folder by typing `cd training-git`
-   Type `ls -alrt`. What do you see?
-   Type `git init`. Read the console output
-   Type again `ls -alrt`. What is new?

::: callout-note
A `.git` folder has appeared. It contains the full history of your project (`Local` repository)
:::

-   Type `git status` and `git log`. What does it tell you?

## First commit

-   Create a `README.md` file by typing `touch README.md`

-   Type `git status` $\rightarrow$ what does it tell you about `README.md` ?

-   Type `git add README.md` and `git status`  $\rightarrow$ what is the new status of the file?

```{mermaid}
%%|label: fig-add
%%| fig-height: 0.8
%%| fig-align: center
flowchart LR
  idw(Workspace) -->|git add| idi(Index)
classDef workspace fill:lightgray,stroke:black,color:black
classDef index fill:lightblue,stroke:black,color:black
classDef local fill:lightgreen,stroke:black,color:black
classDef remote fill:yellow,stroke:black,color:black

class idw workspace;
class idi index;
```

-   Type `git commit -m "First commit"` and type `git status` and `git log`

```{mermaid}
%%|label: commit
%%| fig-height: 0.8
%%| fig-align: center
flowchart LR
  idw(Index) -->|git commit| idl(Local)
classDef workspace fill:lightgray,stroke:black,color:black
classDef index fill:lightblue,stroke:black,color:black
classDef local fill:lightgreen,stroke:black,color:black
classDef remote fill:yellow,stroke:black,color:black

class idw index;
class idl local;
```

```{mermaid}
%%|label: graph1
%%| fig-height: 1
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
   commit id: "0f0e96a"
```

::: callout-note
`0f0e96a` is a short version of the identifier of the commit
:::

## Second commit

-   Open the `README.md` file, add `# Git training` and save
-   Type `git status`  $\rightarrow$ what is the status of the file?
-   Type `git diff`  $\rightarrow$ what does this command do?

```{mermaid}
%%|label: diff
%%| fig-height: 1
%%| fig-align: center
flowchart LR
  idw(Local) -->|git diff| idl(Workspace)
classDef workspace fill:lightgray,stroke:black,color:black
classDef index fill:lightblue,stroke:black,color:black
classDef local fill:lightgreen,stroke:black,color:black
classDef remote fill:yellow,stroke:black,color:black

class idw workspace;
class idl local;
```

-   Type `git add README.md` and `git commit -m "Second commit"`
-   Type `git log`

```{mermaid}
%%|label: graph2
%%| fig-width: 5
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
```

## Reverting a commit

To revert a commit, i.e. to cancel changes done in a previous one:

- Type `git revert -n c6dc2bc` (replace `c6dc2bc` by your commit id)
- Type `git status`. What happens?
- The `README.md` file is now modified and staged (i.e. in the `Index`)
- To see what has been changed, type `git diff --staged`
- To commit this modification, type `git commit -m "Revert commit"`


```{mermaid}
%%|label: graph5
%%| fig-width: 5
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
```

::: {.callout-note}
The `-n` option is to prevent an automatic commit. Therefore you need to commit yourself
:::

## Ignoring files

It is possible to tell Git to ignore some files by using a [.gitignore](https://git-scm.com/docs/gitignore) file (for example `.Rdata` or `.tmp` files).

-   Create an empty `output.Rdata` file and type `git status`
-   Create a `.gitignore` file and write `*.Rdata`. Type again `git status`

The `output.Rdata` file does not appear as an `Untracked file` anymore

-   Type `git add .gitignore` and `git status`
-   Type `git commit -m "Fourth commit"`

```{mermaid}
%%|label: graph6
%%| fig-width: 5
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
    commit id: "9670a59"
```

::: callout-tip
To list the ignored files, type `git ls-files --others --ignored --exclude-from=.gitignore`
:::

## Creating tags

-   Open the `README.md` file and add `## Version v1.0.0`.
-   Type `git add README.md`
-   Type `git commit -m "Third commit"`
-   Type `git tag v1.0.0` and `git log`

```{mermaid}
%%|label: graph3
%%| fig-width: 5
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
    commit id: "9670a59"
    commit id: "07e8835" tag: "v1.0.0"
```

-   Type `git tag` to list all existing tags


## Moving in the history

-   Type `git checkout v1.0.0` $\rightarrow$ move to a tag

```{mermaid}
%%|label: graph8
%%| fig-width: 3
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
    commit id: "9670a59"
    commit id: "07e8835" tag: "v1.0.0" type:HIGHLIGHT
```

-   Type `git checkout 0f0e96a` $\rightarrow$ move to a specific commit

```{mermaid}
%%|label: graph8
%%| fig-width: 3
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a" type:HIGHLIGHT
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
    commit id: "9670a59"
    commit id: "07e8835" tag: "v1.0.0"
```

-   Type `git checkout main` $\rightarrow$ move at the latest commit

```{mermaid}
%%|label: graph9
%%| fig-width: 3
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a" type:HIGHLIGHT
    commit id: "c6dc2bc"
    commit id: "-c6dc2bc" type: REVERSE
    commit id: "9670a59"
    commit id: "07e8835" tag: "v1.0.0" type:HIGHLIGHT
```

::: callout-tip
`HEAD` is a symbolic reference pointing to wherever you are in your commit history, as shown in `git log`
:::

## Display differences

-   Type `git diff 0f0e96a v1.0.0` $\rightarrow$ compares a commit and a tag.

::: callout-warning
Order matters when using `git diff`. Differences are shown with the reference state considered to be the first argument.
:::

```{mermaid}
%%|label: graph10
%%| fig-width: 5
%%| fig-align: center
flowchart LR
  id1(0f0e96a)-->|git diff| id2(v1.0.0)
classDef workspace fill:lightgray,stroke:black,color:black
classDef index fill:lightblue,stroke:black,color:black
classDef local fill:lightgreen,stroke:black,color:black
classDef remote fill:yellow,stroke:black,color:black

class id1,id2 local;
```

-   Type `git diff 0f0e96a c6dc2bc` $\rightarrow$ compares two commits.

-   Type `git diff 0f0e96a HEAD` $\rightarrow$ compares where you are in the history (`HEAD`) with a given commit.

# Using Git with remote server

## Using remotes

In addition of saving the history, Git has other advantages. It allows to:

-   Save a project remotely
    -   Synchronization with different computers (laptop, HPCs)
-   Share a project (codes, packages) with the community
    -   Reproducible science

To do so, a $4^{th}$ component in the Git architecture must be considered: the `Remote` repository. It contains a **remote** version of the history of your project

```{mermaid}
%%|label: graph11
%%| fig-width: 5
%%| fig-align: center
flowchart LR
    idw(Workspace)
    idi(Index)
    idl(Local)
    idr(Remote)

    idw -->|git add| idi
    idi -->|git commit| idl
    idl -->|git push| idr
    idr --->|git pull| idw
    idr --->|git fetch| idl

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

## Remote hosts

There are several remote hosting possibilities:

**Commercial hosts**:

-   GitHub: <https://github.com/>
-   GitLab: <https://gitlab.com/>

**Institutional hosts**:

-   GitLab IRD: <https://forge.ird.fr/>
-   GitLab Ifremer <https://gitlab.ifremer.fr/>

In the following, we will use GitHub.

::: callout-tip
GitHub proposes extra-features for students, teachers and researchers. Visit <https://education.github.com/benefits> for more informations
:::

## Creation of a personal access token

To authentificate, you need to create an authentification token (see [GitHub authentification of details](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)).

To do so, click on your profile photo and then on `Settings`:

![](img/github-settings.png){height="500" fig-align="center"}

## Creation of a personal access token

-   In the left sidebar, click on `Developer settings`.
-   Under `Personal access tokens`, click `Tokens (classic)`.
-   Select `Generate new token` and `Generate new token (classic)`.

::: {layout-ncol="3" layout-valign="bottom"}
![](img/access-token-4.png){height="90" fig-align="center"}

![](img/access-token-1.png){height="80" fig-align="center"}

![](img/access-token-3.png){height="80" fig-align="center"}
:::

## Creation of a personal access token

-   Add a description note and **click on the "repo" box**, as shown below:

![](img/access-token-2.png){height="300" fig-align="center"}

-   Click on the `Generate token` box button.

-   Copy and save in a `.txt` file or in a Password manager tool (for example KeePassXC) your token: **this is your password to publish codes!** It should look like something like this:

```
ghp_***************************************
```

## Creation of a GitHub repository

-   On your GitHub page, click on `Repositories`
-   Click on the the green `New` button
-   Set the name of your remote repository. **Leave the other fields empty**
-   Click on `Create repository`

![](img/github_makeRepo.png){height="400" fig-align="center" layout-valign="center"}

## Linking Git local and remote

-   In `Terminal` or `Git Bash`, type the following line:

`git remote add origin https://github.com/barriern/git-train.git`

::: callout-warning
Replace `barriern` by your GitHub login and `git-train` by the name of your GitHub repository.
:::

::: callout-important
The URL must end by `.git`!
:::

-   It connects your `Local` repository with the `Remote` repository, called *origin*

```{mermaid}
%%|label: graph12
%%| fig-width: 3
%%| fig-align: center
flowchart LR

    idl(Local)
    idr("Remote<br>(origin)")

    idl-->idr
    idr-->idl

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

-   Type `git remote -vv`

## Linking Git local and remote

Now that the local and remote repositories are linked, the same thing must be done with the branches.

-  First, rename your local branch with the name expected by GitHub (either `main` or `master`):
    -    Type `git branch -M main`
- Push your branch on the remote server:
    - Type `git push -u origin main`

It connects the *local* and *remote* main branches (`-u` option stands for `--set-upstream`) and sends the local commits to the remote branch

```{mermaid}
%%|label: graph13
%%| fig-width: 3
%%| fig-align: center
flowchart LR

    idl("Main<br>(Local)")
    idr("Main<br>(Remote)")

    idl-->idr
    idr-->idl

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

-  Type `git branch -vv`
-  Refresh your repository webpage: what do you see? **what is missing?**

## Linking Git local and remote: tags

- To push tags to the remote, type `git push --tags`
- Refresh your repository webpage. Check whether the tags are properly pushed

```{mermaid}
%%|label: graph14
%%| fig-width: 3
%%| fig-align: center
flowchart LR

    idl(Local)
    idr("Remote")

    idl-->|git push|idr


    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

::: callout-note
No need to specify the `-u origin main` arguments here
:::


## Synchronization from the remote

-   In GitHub, click on the `README.md` file and then on the edit button

-   Add a `Update from Github` line and click on `Commit changes`

::: {layout-ncol="2" layout-valign="bottom"}
![](img/readme-edit.png){height="80" fig-align="center"}

![](img/readme-edit-2.png){height="80" fig-align="center"}
:::

- The `Remote` change of `README.md` is not yet visible in `Workspace`!

- In `Git Bash` or `Terminal`, type `git pull`

```{mermaid}
%%|label: graph15
%%| fig-width: 3
%%| fig-align: center
%%| fig-height: 1
flowchart RL

    idr(Remote)
    idw(Workspace)

    idr -->|git pull| idw

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

-   Look again at the `README.md` file on your computer. You should see the update.

## Synchronization: conflicts

-   On GitHub, add `x = 1` at the end of the `README.md` file. **Do not pull the changes!**
-   On your computer, edit the `README.md` and add `x = 2`.
-   Type `git add README.md`
-   Type `git commit -m "Fifth commit"`
-   Type `git push`. What do you see?
-   Type `git pull` and `git status`. An error occurs because there is a conflict in the `README.md` file that cannot be solved by Git.

```{mermaid}
%%|label: graph16
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch origin/main
    commit id: "x is 1"
    checkout main
    commit id: "x is 2"
```

## Synchronization: conflicts

-   Open the `README.md` file. You should see:

```
<<<<<<< HEAD
x = 2
=======
x = 1
>>>>>>> 70a4c105e377db282c0769606960f0afcccdd071
```

::: callout-important
These are conflicts markers. `Git` does't know whether to chose `x = 1` or `x = 2`. This is your job
:::

-  Open the file, remove the conflict markers and solve the value of x by setting `x = 3`
-  Add, commit and push the changes
- Refresh the GitHub page and look at the file

```{mermaid}
%%|label: graph17
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch origin/main
    commit id: "x is 1"
    checkout main
    commit id: "x is 2"
    merge origin/main tag: "x is 3"
```


::: callout-tip
To avoid conflicts, use `git pull` and `git push` extensively
:::

## Cloning an existing repository

The `git clone` command allows to synchronize locally an existing remote repository.

-  On GitHub, create a new repository as done previously.
-  **This time, include a `README.md` and eventually a `LICENCE` file**
- Copy the link to the new GitHub repository
- On Git Bash or Terminal, type `git clone https://github.com/barriern/new-repo.git` (replace the URL by the proper name)

```{mermaid}
%%|label: graph18
%%| fig-width: 6
%%| fig-align: center
flowchart RL

    idr(Remote)
    idw(Workspace)

    idr -->|git clone| idw

    classDef workspace fill:lightgray,stroke:black,color:black
    classDef index fill:lightblue,stroke:black,color:black
    classDef local fill:lightgreen,stroke:black,color:black
    classDef remote fill:yellow,stroke:black,color:black

    class idw workspace;
    class idi index;
    class idl local;
    class idr remote;

```

- Move to the cloned folder by typing `cd new-repo` (replace with the name of your cloned folder)
- Type `git branch -vv`, `git remote -vv` and `git log` to see the full history.

## Cloning an existing repository

::: callout-tip
To create a Git repository from scratch the easy way, create the repository on GitHub with a `README.md`.

Local and remote repositories and branches are automatically synchronized!

Then add your files on your local folder, add, commit, push
:::

::: callout-important
**Do not clone or initialize a Git repository in another Git repository!**
:::

## Conclusion: good practice

-   Before starting working on a project, do a `git pull`
-   Commit very often using `git commit` extensively
-   Push often as well using `git push`
-   Use `git status` extensively to know what you have done

![](img/funny.jpg){fig-align="center" height="300"}

# Git clients

## Git clients: what is it?

Git Clients are softwares that facilitate the use of Git (see [Git Guis](https://git-scm.com/downloads/guis) for a list).

Beside, most code editors include Git functionalities

## Git clients: VSCode

![VSCode](img/vscode.png){#fig-vscode}

## Git clients: RStudio

![RStudio](img/rstudio.png){#fig-rstudio width="350"}

## Git clients: Netbeans

![Netbeans](img/netbeans.png){width="350"}

# Git branches

## Git branches

Working with branches allows to create derivates for a project. For example:

- A `main` branch for the production version
- A `develop` branch for preparing the next release
- A `feature` branch for testing new features

```{mermaid}
%%|label: graph19
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch bugfix
    branch develop
    checkout develop
    commit id: "214e348"
    checkout main
    commit id: "69bbd79"
    merge develop
    checkout develop
    branch feature
    commit id: "0a9ba0c"
    checkout bugfix
    commit id: "d9d02608"
```

## Creating branches

-   Type `git checkout -b develop`
-   Type `git status`, `git br` and `git tree`
-   Open the `README.md` file, add some text and save.
-   Type `git add README.md`
-   Type `git commit -m "3rd commit"`
-   Type `git br` and `git tree`

```{mermaid}
%%|label: graph20
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch develop
    commit id: "214e348"
```

## Switching branch

-   Type `git checkout main` (or `git checkout master`)
-   Type `git br`
-   Open the `LICENCE` file and add some text in it
-   Type `git add LICENCE`
-   Type `git commit -m "Third commit"`
-   Type `git tree`

```{mermaid}
%%|label: graph21
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch develop
    checkout develop
    commit id: "214e348"
    checkout main
    commit id: "69bbd79"
```

## Merging branches

-   On the `main` branch, type `git merge develop -m "merge-develop"`
-   Type `git log` and `git tree`

```{mermaid}
%%|label: graph22
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch develop
    checkout develop
    commit id: "214e348"
    checkout main
    commit id: "69bbd79"
    merge develop
```

The `merge` command puts the commits from the argument branch (here `develop`) and puts them into the current branch (here `main`).

::: callout-note
During the merging process, another commit is created
:::

## Creating branch from another branch

-   Type `git checkout -b feature develop`
-   Create a `script.R` file
-   Type `git add script.R`
-   Type `git commit -m "Fourth commit"`

```{mermaid}
%%|label: graph23
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch develop
    checkout develop
    commit id: "214e348"
    checkout main
    commit id: "69bbd79"
    merge develop
    checkout develop
    branch feature
    commit id: "0a9ba0c"
```

## Creating branch from a commit

-   Type `git checkout -b feat-com 1831e4e` replacing `1831e4e` by an actual commit ID.
-   Create a `script.py` file
-   Type `git add script.py` and `git commit -m "Sixth commit"`

```{mermaid}
%%|label: graph24
%%| fig-width: 6
%%| fig-align: center
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
    commit id: "0f0e96a"
    commit id: "c6dc2bc"
    branch feat-com
    branch develop
    checkout develop
    commit id: "214e348"
    checkout main
    commit id: "69bbd79"
    merge develop
    checkout develop
    branch feature
    commit id: "0a9ba0c"
    checkout feat-com
    commit id: "d9d02608"
```

## Differences between branches

-   Type `git diff develop main`

::: callout-notes
You will see the text that has been added to the LICENCE file (69bbd79 commit)
:::

::: callout-warning
Order matters: it shows what has been added to `main` branch compared to the `develop` branch
:::

```{mermaid}
%%|label: graph25
%%| fig-width: 6
%%| fig-align: center
flowchart LR
  id1(Develop)-->|git diff| id2(Main)
classDef workspace fill:lightgray,stroke:black,color:black
classDef index fill:lightblue,stroke:black,color:black
classDef local fill:lightgreen,stroke:black,color:black
classDef remote fill:yellow,stroke:black,color:black

class id1,id2 local;
```

## Using branches on remote servers

To push a branch on a remote server

- Switch to the branch you want to push: `git checkout develop`
- Push the branch as follows: `git push -u origin develop`.

::: callout-important
On the `push` command, the last argument is the name branch on the remote server. Make it consistent with the local
branch
:::

::: callout-notes
Use `git branch -vv` extensively to check the links between local/remote branches.
:::

## Deleting a branch (locally)

-   Type `git checkout main`
-   Type `git branch -d develop`
-   Type `git br`
-   Type `git branch -d feat-com`

An error occurs! The suppression of `feat-com` implies the loss of the `d9d02608` commit. To force the suppression, use `-D` instead of `-d`.

-   Type `git branch -D feat-com`

::: callout-note
The suppression of `develop` was ok because the content of commit `3rd` is included in the merge.
:::

## Deleting a branch (remotely)

Deletion from the remote branch is not automatic. To delete branch remotely:

- `git push origin --delete develop`

::: callout-important
Make sure that the branch should be removed or has been merged. Delete locally first and then remotely
:::

::: callout-tip
For the lazy people, the [Git Flow](https://github.com/nvie/gitflow) extension, managing branches is very easy! Everything is almost done automatically!
:::

# Large file storage (LFS)

## What for?

To version (reasonably) large files (images, data samples) $\rightarrow$ Git with [LFS](https://git-lfs.github.com/) extension.

::: callout-warning
Make sure that the remote host is compatible with LFS (GitHub is compatible)
:::

::: callout-important
Do not use for data that change extensively. It can be used for example to store toy datasets to show how a package work (vignettes, documentation)
:::


## LFS install

- LFS is automatically installed with Git on Windows.
- On Linux, it can be installed using `sudo apt install git-lfs`
- When it is installed, you need to activate it. To do so, type `git lfs install`

## Tracking files with LFS

-   Create a `data.csv` file and add `Year,Size,Species`
-   Type `git lfs track "*.csv"`

A `.gitattributes` file has appeared, which list all the file extensions managed by Git LFS.

-   Type `git add .gitattributes data.csv`
-   Type `git commit -m "Using LFS"`
-   Type `git push`
-   On GitHub, click on your file `data.csv` file.

# Remainder

## Basic commands

-   `git init`: initialise a git project (create .git folder)
-   `git add [files]`: add files to list of tracked files
-   `git commit -m ”message”`: validate locally a version of the project
-   `git status`: see the unvalidated and untracked changes
-   `git checkout [commit]`: load the project version corresponding to the index
-   `git pull`: import the changes from remote project to local
-   `git push`: export the changes from local project to the remote server

## Git configuration (mandatory)

-   Configure your identity: `git config --global user.name "Firstname Lastname"`
-   Configure your e-mail: `git config --global user.email "myadresse@ird.fr"`

## Branch handling

-   `git branch [branch_name]`: create a new branch (but you remain on the previous branch)
-   `git branch -b [branch_name]`: create a new branch and move to this newly created branch
-   `git checkout [branch_name]`: move to the corresponding branch
-   `git merge [branch_name1] [branch_name2]`: merge two different branch, you may need to resolve version conflict.
-   `git branch -d [branch_name1]`: delete a branch (safe mode)
-   `git branch -D [branch_name1]`: delete a branch (unsafe mode)

## Linking with remote

-   `git clone [URL]`: Import an existing project from remote server.
-   `git remote add origin [URL]`: link directly the local repository with a remote

## Authentication of your computer and the remote server

-   SSH key: easy way on Linux distributions
    -   Tuto here: <https://jdblischak.github.io/2014-09-18-chicago/novice/git/05-sshkeys.html>
-   Authentication Token
    -   Tuto here: <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>

## Good practices

-   Pull before any work on the project
-   Commit as frequently as possible
-   Write explicit commit message
-   Push regularly

## IDE (graphical user interface) with Git

-   R
    -   RStudio
    -   Visual Studio Code
-   Python
    -   Spyder
    -   Visual Studio Code
    -   Pycharm (all JetBrain softwares)

## Sources

-   Plateau bioinformatique, Montpellier: Formation Git(Lab) (05/04/2018)
-   UMR AMAP (Atelier MAIA P3M), Montpellier: Introduction à GIT (04/04/2019)