# GIT FOR THE DUMMIES !

## REQUIREMENTS

Please install git and configure ssh keys folowing tutorials found in this table :

| tutorial | link|
| -------- | -------------------- |
|install git | [part I.](https://hackmd.io/mHOA25TORbuFyfpCdkcBkg#) |
|ssh keys configuration | [ part II. ](https://hackmd.io/mHOA25TORbuFyfpCdkcBkg#) |
|git global setup | [ part III. ](https://hackmd.io/mHOA25TORbuFyfpCdkcBkg#) |

:::info
Install git and try to configure ssh key before practical section !
:::

---

## GIT in a nutshell


---

## What will be our working environment ?

#### We will work on several remote repositories hosted on the platform 

**URL** : forge.ird.fr

| Repository name | Status |
|--- | --- |
| diade/bioinfonair | public |
| diade/gitlab_practice/***PUT_YOUR_NAME***_project| private |
| diade/gitlab_practice/vieilles_branches | private |

---

# PRACTICE 1 - Let's try IRD Forge 

1. ***Open*** your web browser and go to the [IRD forge](forge.ird.fr)
2. Search for the bioinfonair project


3. We will clone this repository in a local git repository in the following exercises.


---
# PRACTICE 2 - Let's starting with the public repository `BIOINFONAIR`

## 2.1 - Download the repository on your computer - `git clone`

1. On your computer, go to the directory where you want to import the bioinfoair repository - `cd`, `mkdir`

2. Use the `git clone` command to download the remote repository (clone with https)

 git clone <URL_DISTANT_REPOSITORY_NAME>


:::spoiler
* command :

$ git clone [e-mail]:diade/bioinfonair.git

* output :

christine@christine-Precision-5540:~$ git clone [e-mail]:diade/bioinfonair.git
Clonage dans '/home/christine/tmp'...
remote: Enumerating objects: 26, done.
remote: Total 26 (delta 0), reused 0 (delta 0), pack-reused 26
Réception d'objets: 100% (26/26), 9.62 Mio | 6.47 Mio/s, fait.
Résolution des deltas: 100% (9/9), fait.

:::

<br/>

3. Check that the repo has be cloned locally - `ls`
:::spoiler

christine@christine-Precision-5540:~$ tree tmp/
tmp/
├── 1_bioinfOnAir-mapping.pdf
├── 2_533452a.pdf
├── 2_Git-CestPasSorcier.pdf
├── 2_science.354.6308.142.pdf
├── Planning-2023.png
└── README.md

:::

<br/>

## 2.2 - Updating `bioinfonair` repository

Changes will be applied from **a single local git repo** and then pushed to the remote repository. We will do this step for you in demo:

1. A new file `git-cheat-sheet-education.pdf` will be added to **`a local git repo`** - `git add`,`git commit`

2. A description of the `PRACTICE` directory content will be modified in the README file in **`the local git repo`** - `git commit`

3. Then, all changes will be pushed to **```the bioinfonair remote repository```**- `git push`

:::spoiler

cd bioinfonair
cp ~/Downloads/git-cheat-sheet-education.pdf .
nano Practice/README.md
git status
git add git-cheat-sheet-education.pdf
git add README.md
git status
git commit -m 'adding git cheat in repository'  git-cheat-sheet-education.pdf
git commit -m 'description of the PRACTICE directory content' README.txt
git status
git push

:::

<br/>

## 2.3 - Update your local repository - `git pull`

1. Check that the changes have been correctly commited on the IRD forge
(and that the changes have not been importated on your local repository).

2. Updating your local repo to import the last changes

 git pull <GIT_DISTANT_REPO> <branch name>

:::spoiler

$git pull [e-mail]:diade/bioinfonair.git 
Depuis forge.ird.fr:diade/bioinfonair
 * branch            HEAD       -> FETCH_HEAD
Déjà à jour.

:::

<br/>

------------
# PRACTICE 3 - Try version tracking for your own files using your own private repository

In this exercise, to familiarize yourself with git commands, you will use a private remote repository that only you can use. This private repository is empty for now and you'll use it to track versions of your own scripts or documents (and save them) during the rest of this session.

So in the `DIADE/gitlab_practice` shared subgroup, we created a private repository for everyone, starting with the first name as follows: `yourFirstName_project`


## 3.1 Clone your private repository

1. Log in to your account on the IRD forge (if you haven't done so already) and search for the `gitlab_practice` subgroup

2. Search for your private project in this subgroup and get the url to clone with ssh this private repository

3. Clone this remote repository on your local machine (in the "good" directory) - `git clone`

:::info
:information_source: Clone with **ssh protocol** as your project is private and SSH keys will be required.
:::

:::spoiler

git clone [e-mail]:diade/gitlab_practice/christine_project.git
Clonage dans 'christine_project'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Réception d'objets: 100% (3/3), fait.

:::

<br />

## 3.2 Adding your own files in your local repository and pushing them in the remote repository

1. Go into the directory downloaded on your computer - `cd yourname_project`
1. Copy several new files inside this directory - `cp`
1. View the status of your working directory and staging area - `git status`
1. Add that new files to the staging area - `git add <file>`
1. Save that changes in your local git repository using an explicit message `git commit -m "WRITE AN EXPLICTE MSG HERE" <file>`
1. Save that changes in the remote git repository - `git push`
1. Check that changes have been saved on the remote git server (on the forge website)

:::spoiler

$ ls -l
-rw-rw-r-- 1 orjuela orjuela   39 oct.  23 23:31 README.txt
-rwxrwxr-x 1 orjuela orjuela 1753 oct.  23 23:37 Singularity.report.def*

$ git status 
Sur la branche master
Votre branche est à jour avec 'origin/master'.

Fichiers non suivis:
  (utilisez "git add <fichier>..." pour inclure dans ce qui sera validé)
	Singularity.report.def

aucune modification ajoutée à la validation mais des fichiers non suivis sont présents (utilisez "git add" pour les suivre)


$ git add Singularity.report.def 


$ git commit -m 'adding a file for gitlab4dummies' Singularity.report.def 
[master 7b18c73] adding a file for gitlab4dummies
 1 file changed, 55 insertions(+)
 create mode 100755 Singularity.report.def
 
 
$ git status 
Sur la branche master
Votre branche est en avance sur 'origin/master' de 1 commit.
  (utilisez "git push" pour publier vos commits locaux)

rien à valider, la copie de travail est propre


$ git push 
Énumération des objets: 4, fait.
Décompte des objets: 100% (4/4), fait.
Compression par delta en utilisant jusquà 20 fils d exécution
Compression des objets: 100% (3/3), fait.
Écriture des objets: 100% (3/3), 1.03 Kio | 1.03 Mio/s, fait.
Total 3 (delta 0), réutilisés 0 (delta 0), réutilisés du pack 0

:::

<br />

## 3.3 Modifying files in your local git repository

1. Modify the contents of an existing file in your working directory (local repository) by adding a few lines to the README for example - `nano README.txt`.
1. Check the status of that file and the changes - `git status`, `git diff <file>`
1. Add that file into the staging area `git add README.txt`
1. Commit it using an explicit message `git commit -m 'modifying documentation' README.txt`
1. Push changes to the remote repository

:::spoiler

$ nano README.txt 

$ git diff README.txt

$ git status 

$ git add README.txt 

$ git commit -m "modyfing doc in readme" README.txt 

$ git status 

$ git push

:::

<br />

## 3.4 Back to the change just before the last commit without losing the work done

$ git log --oneline

# Revert the commit 
$ git revert 4c908f0

## 3.5 Remove a file using `git rm`

1. Remove the `README.txt` file by `git rm README.txt`
1. Commit changes
1. Push changes in the remote server and check that changes have been saved in the remote repository.

:::spoiler

$ git rm README.txt 
rm 'README.txt'

$ git status 
	supprime :        README.txt

$ git commit -m 'removing readme' README.txt 

$ git status 

$ git push

:::
<br />

-----

# 4. BONUS - Git Branching

## Why using branches ?

Branches are used to develop new features or modify codes isolated from each other :
* The _master_ branch is the "default" branch when a repository is created.
* Use other branches for development and merge them back to the master branch.

##### From https://www.atlassian.com/fr/git/tutorials/using-branches/git-merge

:::success
:reminder_ribbon: Changes made to a branch must be "homogeneous": same file, same modified functionality

:reminder_ribbon: The shorter the duration of the branch, the better.
:::

## Why torture trainees with branches in the following exercices ?

:::info
:bulb: The use of branches is very useful (yes!!!):
* if you share the same repository with colleagues, students, partners, you can protect the master branch !
* several of you can work simultaneaously without impacting each other
* numerous other cases and reasons to use branche

:warning: Using branch requires a good knowledge (and practice) of basic git commands
:::

The aims of the following exercices/commands is to manipulate branches and to understand the concept of 'merge'... let's give it a try!

* :warning: Everyone can clone and use the `DIADE/gitlab_practice/vieilles_branches` repository
* Everyone can work simultaneously on the same files in this repository but not in the same branch

:::info
:bulb: So, the best practice (and to preserve good relations with colleagues) is :
* to create a branch to work in parallel
* once you've finished working, you merge your branch with the "master" branch.
* If you've made changes on the same file on your branch and the branch you are merging with, git will ask you to validate the modifications or not.
:::

## 4.1 Viewing branches - ` git branch`

### only local branches - `git branch`, `git branch -v`

$ git branch
* master

\* indicates the branch you are currently used

### only remote branches - `git branch -r`

$ git branch -r
  origin/HEAD -> origin/master
  origin/master
  origin/picardtools-samtofastq
  origin/samtoolsBlocks
  origin/structuralVariant
  origin/tgicl
  origin/transabyss
  origin/trinity

### all branches that exist (local ) - `git branch -a`

$ git branch -a
  * master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/picardtools-samtofastq
  remotes/origin/samtoolsBlocks
  remotes/origin/structuralVariant
  remotes/origin/tgicl
  remotes/origin/transabyss
  remotes/origin/trinity

## 4.2 Create your own branch on your local repository, modify scripts and transfer it on remote server

### Create a new branch locally

git branch <new_branch_name>

:::spoiler

# List all branches (on the local and remote repository)
$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

# Create a new local branch called pangenome_graph
$ git branch pangenome_graph

# Check that the pangenome_graph branch has been created
$ git branch -a
* main
  pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

:::

### Switch to this new branch

git checkout <new_branch_name>

:::spoiler

# List all branches, we are working on the main branch
$ git branch -a
* main
  pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  
# We switch to pangenome_graph branch 
$ git checkout pangenome_graph 
Basculement sur la branche 'pangenome_graph'


# View the branches list and the branch we are currently working on 
$ git branch -a
  main
* pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

:::

### Modify a file, add the modified file in the stagging area then in the local git repository

git add <file>
git commit -m "my explicit commit message" <file>

:::spoiler

# List all branches
$ git branch -a
  main
* pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

# Modify the README.md file on the `pangenome_graph` branch
$ vi README.md 

# View the files state
$ git status
Sur la branche pangenome_graph
Modifications qui ne seront pas validées :
  (utilisez "git add <fichier>..." pour mettre à jour ce qui sera validé)
  (utilisez "git restore <fichier>..." pour annuler les modifications dans le répertoire de travail)
	modifié :         README.md

aucune modification n'a été ajoutée à la validation (utilisez "git add" ou "git commit -a")

# Check the changes within the two versions of the README file
$ git diff README.md
diff --git a/README.md b/README.md
index 36b89bf..29d6a1b 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ frangiPANe was developed as a modular and interactive application to simplify th
  * samtools (v1.10) : http://www.htslib.org/
  * assembly-stats : https://github.com/sanger-pathogens/assembly-stats
  * cd-hit : https://github.com/weizhongli/cdhit/blob/master/README
+ * ... 
 
 ### How to use FrangiPANe ?
 
@@ -46,4 +47,4 @@ tar zxvf data_test.tar.gz
 
 * Written by Clothilde Chenal and Christine Tranchant-Dubreuil
 
-* Copyright 2021
\ No newline at end of file
+* Copyright 2021


# Adding the modified file in the stagging area
$ git add README.md 

# Save the changes in the local git repository
$ git commit -m "adding item" README.md 
[pangenome_graph 45da600] adding item
 1 file changed, 2 insertions(+), 1 deletion(-)

:::

### Push this local branch (and changes) on the remote server

 git push <remote> <branch_name>

:::spoiler

# List all branches 
$ git branch -a
  main
* pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

# Push the local branch pangenome_graph to the repmote repository
$ git push origin pangenome_graph
Total 0 (delta 0), réutilisés 0 (delta 0), réutilisés du pack 0
remote: 
remote: 
remote: To create a merge request for pangenome_graph, visit:
remote:   https://forge.ird.fr/diade/frangipane/-/merge_requests/new?merge_request%5Bsource_branch%5D=pangenome_graph
remote: 
To forge.ird.fr:diade/frangipane.git
 * [new branch]      pangenome_graph -> pangenome_graph

# List all branches
$ git branch -a
  main
* pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/pangenome_graph

:::

### Check in the remote repository that your commits are correctly saved in the new branch.



## 4.3 Merge your branch into your active branch (e.g. main)

### Move into the "active" branch (e.g. main)

git checkout <branch_name>

:::spoiler

$ git branch -a
  main
* pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/pangenome_graph

$ git checkout main
Basculement sur la branche 'main'
Votre branche est à jour avec 'origin/main'.

$ git branch -a
* main
  pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/pangenome_graph

:::

### Update your local repository to the newest commit

git pull origin main

:::spoiler

$ git pull origin main
Depuis forge.ird.fr:diade/frangipane
 * branch            main       -> FETCH_HEAD
Déjà à jour.

:::

### Merging

git merge <branch_name_to_merge>

:::spoiler

$ git merge pangenome_graph 
Mise à jour 1d167e6..45da600
Fast-forward
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

:::

### If conflicts with the merging step, resolve them

You are responsible to merge those conflicts manually by editing the files shown by `git status` then use the commands `git add` and `git commit`.

 git status

###### Create the branch test_conflict and modify the file README to create a conflict with the main branch

:::spoiler

# Create the branch test_conflict and modify the file README to create a conflict with the main branch
$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

$ git branch test_conflict

$ git branch -a
* main
  test_conflict
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

$ git checkout test_conflict 
M	README.md
Basculement sur la branche 'test_conflict'

$ vi README.md 

$ git status
Sur la branche test_conflict
Modifications qui ne seront pas validées :
  (utilisez "git add <fichier>..." pour mettre à jour ce qui sera validé)
  (utilisez "git restore <fichier>..." pour annuler les modifications dans le répertoire de travail)
	modifié :         README.md

$ git add README.md 
$ git commit -m "Add vg" README.md 
[test_conflict af185c3] Add vg
 1 file changed, 1 insertion(+), 1 deletion(-)

$ git push origin test_conflict
Énumération des objets: 5, fait.
Décompte des objets: 100% (5/5), fait.
Compression par delta en utilisant jusqu'à 16 fils d'exécution
Compression des objets: 100% (3/3), fait.
Écriture des objets: 100% (3/3), 289 octets | 289.00 Kio/s, fait.
Total 3 (delta 2), réutilisés 0 (delta 0), réutilisés du pack 0
remote: 
To forge.ird.fr:diade/frangipane.git
 * [new branch]      test_conflict -> test_conflict

:::

###### On the main branch, modify the file README to create a conflict with the test_conflict branch
:::spoiler

$ git branch -a
  main
* test_conflict
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/test_conflict
  

# On the main branch, modify the file README to create a conflict with the test_conflict branch
$ git checkout main
Basculement sur la branche 'main'
Votre branche est en avance sur 'origin/main' de 1 commit.
  (utilisez "git push" pour publier vos commits locaux)

$ vi README.md 

$ git status
Sur la branche main
Votre branche est en avance sur 'origin/main' de 1 commit.
  (utilisez "git push" pour publier vos commits locaux)

Modifications qui ne seront pas validées :
  (utilisez "git add <fichier>..." pour mettre à jour ce qui sera validé)
  (utilisez "git restore <fichier>..." pour annuler les modifications dans le répertoire de travail)
	modifié :         README.md

aucune modification n'a été ajoutée à la validation (utilisez "git add" ou "git commit -a")

$ git add README.md 
$ git commit -m "Add girafe" README.md 
[main b64c2b7] Add girafe
 1 file changed, 2 insertions(+), 1 deletion(-)
$ git push 
Énumération des objets: 8, fait.
Décompte des objets: 100% (8/8), fait.
Compression par delta en utilisant jusqu'à 16 fils d'exécution
Compression des objets: 100% (6/6), fait.
Écriture des objets: 100% (6/6), 581 octets | 581.00 Kio/s, fait.
Total 6 (delta 4), réutilisés 0 (delta 0), réutilisés du pack 0
remote: 
remote: 
To forge.ird.fr:diade/frangipane.git
   1d167e6..b64c2b7  main -> main

:::

###### Merge the two branches and resolving conflicts

:::spoiler

$ git branch -a
  main
* test_conflict
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/test_conflict

$ git checkout main
Basculement sur la branche 'main'
Votre branche est à jour avec 'origin/main'.
christine@christine-Precision-5540:~/Documents/Dev/frangipane$ git branch -a
* main
  test_conflict
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/test_conflict

$ git merge test_conflict
Fusion automatique de README.md
CONFLIT (contenu) : Conflit de fusion dans README.md
La fusion automatique a échoué ; réglez les conflits et validez le résultat.

$ git status
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Vous avez des chemins non fusionnés.
  (réglez les conflits puis lancez "git commit")
  (utilisez "git merge --abort" pour annuler la fusion)

Chemins non fusionnés :
  (utilisez "git add <fichier>..." pour marquer comme résolu)
	modifié des deux côtés :  README.md

aucune modification n'a été ajoutée à la validation (utilisez "git add" ou "git commit -a")

:::

###### Resolve the conflicts by editing the file README on your text editor

:::spoiler

 ### Requirements

 * Docker : https://docs.docker.com/get-docker/
 * Python3 (v3.9.7) : https://www.python.org/
 * biopython : https://biopython.org/
 * panel : https://panel.holoviz.org/

 * abyss : https://github.com/bcgsc/abyss/blob/master/README.md
 * bwa (v. 0.7.17) : https://github.com/lh3/bwa/blob/master/README.md
 * ea-utils (fastq-stats, v 1.01) : https://expressionanalysis.github.io/ea-utils/
 * samtools (v1.10) : http://www.htslib.org/
 * assembly-stats : https://github.com/sanger-pathogens/assembly-stats
 * cd-hit : https://github.com/weizhongli/cdhit/blob/master/README
<<<<<<< HEAD
 * mnimap2
 * girafe 
=======
 * vg 
>>>>>>> test_conflict

### How to use FrangiPANe ?

:::

### Commit and push the changes and the merge on the distant server

 git commit -m "Branch merging <branch name> to master" 
 git push https://forge.ird.fr/diade/gitlab_practice/YOUR_project.git master

## 4.4 Remove merged branche

### on our local copy

git <name_branch_to_delete> -d

#### on the remote server

 git push <remote> -d <remote_branch_name_to_delete>

:::spoiler

# Switch to the main branch
$ git checkout main

# List all branches
$ git branch -a
* main
  pangenome_graph
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/pangenome_graph

$ git branch -d pangenome_graph 
Branche pangenome_graph supprimée (précédemment 45da600).

$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/pangenome_graph

# Deleting the remote branch rpangenome_graph
$ git push origin -d pangenome_graph
remote: 
To forge.ird.fr:diade/frangipane.git
 - [deleted]         pangenome_graph

# Checking that the branch has been deleted
$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

:::

## Cool links
> https://education.github.com/git-cheat-sheet-education.pdf (in the bioinfonair repo also)
> https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
> https://docs.gitlab.com/ee/topics/git/numerous_undo_possibilities_in_git/index.html
> https://www.conventionalcommits.org/en/v1.0.0/

## Authors

Christine Tranchant-Dubreuil & Julie Orjuela-Bouniol  &nbsp;&nbsp; 

## Git repo

https://forge.ird.fr/diade/bioinfonair

## License


This repository is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, [visit here](https://creativecommons.org/licenses/by-nc-sa/4.0/).