# Git/Version imprimable

* Si vous imprimez cette page, choisissez « Aperçu avant impression » dans votre navigateur, ou cliquez sur le lien Version imprimable dans la boîte à outils, vous verrez cette page sans ce message, ni éléments de navigation sur la gauche ou en haut.
* Cliquez sur Rafraîchir cette page pour obtenir la dernière version du wikilivre.
* Pour plus d'informations sur les version imprimables, y compris la manière d'obtenir une version PDF, vous pouvez lire l'article Versions imprimables.
Une version à jour et éditable de ce livre est disponible sur Wikilivres, une bibliothèque de livres pédagogiques, à l'URL : https://fr.wikibooks.org/wiki/Git

# Principes

Git est un logiciel de gestion de versions parmi les plus populaires. Il a été conçu pour gérer les projets de très grande envergure.
C'est un logiciel libre créé par Linus Torvalds qui a souhaité remplacer l'outil propriétaire qui était utilisé pour le développement du noyau Linux.
Git respecte les principes typiques Unix. Ce n'est pas un logiciel monolithique mais un ensemble de petits composants exécutant chacun une tâche unique. Par exemple dans Git v1.5.3, la suite d'utilitaires est constituée de 143 commandes spécialisées, dont une bonne fraction doit être appelée en Bash.
Ce logiciel en ligne de commande est disponible sur les Unix-like, Mac OS et Windows et est distribué selon les termes de la licence publique générale GNU version 2.
L'objectif du présent livre est de permettre au lecteur de se familiariser avec les concepts fondamentaux de Git et de prendre en main git afin de pouvoir gérer un projet de développement logiciel de façon décentralisée, de façon sûre et respectueuse des bonnes pratiques de développement.
Git est un logiciel de gestion de versions décentralisé (ou DVCS), c'est-à-dire qu'il n'y a pas de serveur central, chaque client a un dépôt complet en local, ainsi que l'historique intégral du projet.
Dans Git, tout tourne autour des versions et non pas des fichiers. Alors que dans les autres SCM, on gère des fichiers et les modifications effectuées sur ces fichiers au cours du temps, dans Git, les données sont gérées comme des flux d’instantanés du contenu de l'espace de travail.
Les principales commandes et différents types de dépôt Git sont résumés dans le schéma suivant :

# Avant de commencer

Cette première étape est incontournable, nous allons voir comment installer et configurer Git sur votre machine. Suivez les instructions selon votre environnement de travail.
Il est à noter que l'architecture étant décentralisée, ces installations peuvent jouer le rôle du client ou du serveur, qui utilise le port 9418 mais passe en réseau par les services qui écoutent au port 22 (SSH), 80 (HTTP) ou 433 (HTTPS).

## Installation
### Linux

Sur la plupart des distributions, vous pouvez utiliser votre gestionnaire de paquet.
Vous pouvez aussi installer git depuis les sources.

### Mac OS

Une installateur graphique est disponible sur Google. Sinon avec MacPorts lancer :

### Windows

Git pour Windows est téléchargeable sous forme de binaires précompilés sur msysGit ou encore Git Bash. Cela inclut l’utilitaire en lignes de commande, une interface graphique, et un client SSH.
De plus, le setup Cygwin le propose également.

### Intégré dans un IDE

Plusieurs environnements de développement intégré incluent déjà des clients Git complets, comme NetBeans ou PhpStorm.

## Configuration minimaliste de l'environnement

Avant d'aller plus loin, il est indispensable de configurer Git a minima.
Dans Git, les contributeurs à un projet sont identifiés par leur nom et leur adresse courriel, il faut donc fournir à Git ces deux informations.
Pour voir la configuration :

## Éviter de retaper son mot de passe

Git propose un mécanisme pour stocker temporairement votre mot de passe en mémoire et ainsi vous éviter d'avoir à le retaper à chaque push, pull ou toute opération impliquant un repo distant.
Si cela ne fonctionne pas après l'avoir retapé au moins une fois sur Linux, compléter le fichier suivant :
En ajoutant le nom du serveur. Exemple :
Depuis septembre 2021, GitHub n'accepte plus les mots de passe mais demande à la place un token généré sur https://github.com/settings/tokens.
Si cela ne fonctionne toujours pas, vérifier que vous êtes dans le répertoire racine du projet, et que votre fichier .git/config est de la forme :

## Obtenir de l'aide

Git gère très bien l'auto-complétion. Au fur et à mesure que vous saisissez vos commandes, utilisez la touche tabulation ↹ pour que git vous propose des options.
À tout moment vous pouvez consulter le manuel de git avec
Pour obtenir de l'aide sur une commande en particulier, utilisez (exemple pour la commande branch)
Lorsque vous lisez des documentations, vérifiez qu'elles s'appliquent bien à la version que vous utilisez :

# Création de votre dépôt local

Maintenant que Git est installé, nous allons voir comment créer un dépôt sur notre machine. Un dépôt Git correspond à un projet de développement logiciel : chaque logiciel peut avoir un dépôt Git qui lui est réservé.
Nous allons voir trois cas d'utilisation différents :
* La création d'un dépôt git pour démarrer un projet vierge
* La création d'un dépôt git pour un projet existant, les fichiers se trouvant sur votre machine
* La création d'un dépôt afin de travailler sur un projet existant qui est déjà dans un dépôt git distant, c'est le cas le plus courant.

## Création d'un dépôt git pour démarrer un projet vierge

Rendez-vous dans le répertoire dans lequel vous souhaitez créer votre dépôt (dans notre exemple, nous avons utilisé le répertoire temporaire cd /tmp), puis
Vous pouvez ensuite vous placer dans le dossier "mon-projet" et travailler avec git.

## Création d'un dépôt git avec une base de code existante

C'est tout aussi simple. Il faut d'abord se rendre dans le répertoire où se trouvent les sources et faire un git init
Dès lors, vous êtes prêt à travailler avec git dans ce répertoire.

## Création d'une copie locale d'un dépôt distant (clone)

Cette fois-ci, les sources ne sont pas sur notre machine mais sur un dépôt distant qui existe déjà. C'est le cas d'utilisation le plus typique, vous souhaitez rejoindre un projet pour développer des fonctionnalités, corriger des anomalies et publier vos modifications. Pour cela, vous aurez besoin de l'adresse du dépôt distant.
Contrairement à ce qu'on a vu plus haut, nous n'allons pas utiliser init mais clone en se plaçant dans le répertoire dans lequel on souhaite placer son dépôt.
Lorsque vous faites un clone, vous copiez l'intégralité du dépôt, il est donc normal que cette opération prenne longtemps pour les projets qui ont un long historique de contribution. Par exemple, pour le dépôt officiel du logiciel MediaWiki (git clone https://git.wikimedia.org/git/mediawiki/core.git), il faudra télécharger pas moins de 200 Mo.
Dans notre exemple (toujours en travaillant dans le répertoire temporaire /tmp), nous allons nous créer une copie locale d'un dépôt officiel qui représente un exemple d'extension MediaWiki :
Si le dépôt cloné appartient à un tiers, il se peut que l'on ne puisse pas lui soumettre directement une version. Il faut en passer par une pull-request pour que la modification soit relue par le mainteneur.
Si le dépôt cloné demande une authentification forte, il faut créer une clé SSH et l'ajouter sur la forge.

#### Cloner un dépôt privé

Il faut spécifier en plus son login dans la commande, suivi d'un arobase, et elle demandera le mot de passe :

### Créer un fork

Il est possible de créer un fork (aka bifurcation), c'est-à-dire une copie d'un dépôt dans un autre (historique inclus) en changeant l'URL du dépôt cloné :
Puis vérifier :
Pour synchroniser le fork avec sa source :
Sinon on ne veut pas tout synchroniser, on peut faire un cherry-pick.

## Références

* ↑ https://help.github.com/en/github/using-git/changing-a-remotes-url

# Visualiser le contenu de votre dépôt local

Avant de commencer à travailler vraiment sur le projet, nous allons déjà voir comment connaître l'état de notre dépôt.
Un dépôt est complexe, entre les commits, les branches, les tags, l'espace, les dépôts distants, le HEAD, le stash... Il est impératif de savoir comment, à tout moment, savoir où Git en est.
Dans ce chapitre, nous allons voir les différents outils qui sont à votre disposition pour comprendre dans quel état est votre dépôt local. Pour expérimenter les exemples que nous donnons, nous vous recommandons de travailler sur une copie d'un dépôt distant qui a déjà un historique fourni. En effet, ça sera bien plus représentatif qu'avec un dépôt vide où à peine créé.
Nous allons travailler suite à un

## git log

Git log est la principale commande à connaître. Commençons par son utilisation la plus simple
Par défaut, git utilise less pour vous permettre d'afficher les logs pages par pages. Ici, nous voyons 4 commits faits par 4 contributeurs différents. L'historique s'affiche dans l'ordre chronologique inversé : les modifications récentes sont au dessus des modifications anciennes.
Essayez d'ajouter de la couleur avec
Vous pouvez voir l'historique des branches et des fusions avec
Vous pouvez voir l'historique en version réduite (une ligne par commit)
Nous verrons plus tard comment utiliser log pour obtenir les informations qu'on souhaite. N'hésitez pas à combiner les options.

### Rechercher une branche depuis un commit

Pour retracer l'historique des évènements il est parfois nécessaire de retrouver la branche (et la pull request) qui contenait un code. Or, l'historique (git blame) ne contient que des commits.
Pour recherche la pull request qui contenait un commit donné (ex : 0eccb68) :
Pour obtenir le nombre de lignes ajoutées et supprimées d'un contributeur donné :

### Rechercher une chaine de caractères ajoutée ou supprimée dans tous les diffs
## git gui

Il existe une extension git qui vous permet de visualiser votre dépôt local à l'aide d'un outil graphique. La plupart du temps, cette extension doit être installée en plus de git.
Une fenêtre s'ouvre, elle présente peu d'informations car nous n'avons pas encore de modifications à publier.
Ouvrez le menu « Dépôt » puis sélectionnez « Voir l'historique de toutes les branches ».
La fenêtre qui s'ouvre nous donne l'arborescence graphique qui nous permet de voir, dans l'ordre chronologique, toutes les modifications qui ont été faites.

## gitweb

Gitweb est l'interface web officielle intégrée dans git. Elle permet de visualiser le contenu d'un dépôt git depuis tout navigateur web.
Votre navigateur devrait s'ouvrir automatiquement à l'adresse http://127.0.0.1:1234

## Références

* ↑ https://stackoverflow.com/questions/1265040/how-to-count-total-lines-changed-by-a-specific-author-in-a-git-repository

# Premiers pas
## Préalable

Nous allons maintenant entrer dans le vif du sujet et faire une première modification dans le code source d'une application.
Cette première expérience va nous permettre de découvrir plusieurs notions importantes : l'espace de travail et l'index.
On reprend l'exemple précédent.
Faisons d'abord un
qui va nous répondre
Git nous indique qu'il existe une seule branche appelée master et que c'est sur cette branche que nous travaillons comme l'indique l'astérisque en face de master.
Cela nous est confirmé par
qui nous répond
Vous pouvez faire un
Pour voir quel est l'auteur et la date de la dernière modification : cela nous servira de repère pour la suite.

## Ajouter un fichier dans la zone de transit

Commençons par une modification simple : l'ajout d'un fichier dans la staging area (la zone de transit vers la sauvegarde). Cela peut être une première étape si vous avez créer un dépôt vide.
Par exemple, créons un fichier mon_nouveau_fichier.txt avec un petit texte dedans.
Voyons la façon dont git perçoit ce nouveau fichier
Il nous indique qu'on est toujours sur la branche master, qu'il y a un fichier mon_nouveau_fichier.txt mais qu'il n'est pas suivi (« untracked ») par git.
Comme nous voulons intégrer ce fichier au projet, on ne peut pas encore faire le commit, car commit n'envoie que les fichiers qui sont *tracked*, c'est à dire dans l'index (*staging*). Ajoutons le fichier, comme git nous le suggère, avec add
On refait un
Et, cette fois, git nous répond
Le fichier mon_nouveau_fichier.txt sera bien intégré dans notre prochain commit. Allons-y :
Remarquons ici qu'avec -m, nous avons choisi de préciser le message de commit directement sur la ligne de commande. En lançant git commit tout court, l'éditeur de texte ($EDITOR) s'ouvre automatiquement pour inviter à saisir un commentaire de soumission.
Constatons immédiatement l'effet de ce commit :
Notre dernier commit apparaît, en premier de la liste (c'est le plus récent).
Avec
On voit clairement que notre commit est lié au commit précédent.

## Modifier un fichier

Faisons une autre modification. Par exemple, modifions le fichier mon_nouveau_fichier.txt en ajoutant une ligne.
Voyons ce que git nous dit :

### diff

Git nous indique bien que le fichier a été modifié, voyons le résumé de ces modifications telles qu'elles sont perçues par git :
Git nous montre la ligne qui a été ajoutée (le « + » en début de ligne).
Pour comparer une branche distante avec une locale, utiliser ".." :
sinon :

### add

On va maintenant faire le commit. Comme précédemment, il faut ajouter le fichier au *staging* :
Si vous voulez ajouter au staging tous les changements qui ont été effectués (fichiers ajoutés, modifiés, supprimés), il vous suffit de faire
ou

### commit

Remarquez le code « 5556307 » : il s'agit d'une abréviation de l'identifiant unique de l'objet Git (en l'occurrence une soumission). Chaque objet est haché en SHA-1. L'identifiant complet est en fait 5556307824d8d0425b38c9da696b84430e30f09f, mais généralement les huit premiers caractères suffisent à l'identifier à coup sûr.
On voit bien que nos deux commits se succèdent.

## Supprimer un fichier

Il n'est pas nécessaire de faire un add.

### Annuler une suppression

Certains outils comme PyCharm sont dotés d'un historique local (en plus de celui de Git) qui permet d'annuler un "git rm". Il est accessible via un clic droit sur le dossier à restaurer.

## Regrouper des modifications

Il est possible de fusionner une soumission avec la dernière révision, via l'argument amend, sans avoir à réécrire leur résumé avec no-edit :
Généralement on l'utilise pour mettre à jour un commit :
Si la cible n'est pas la dernière révision, on peut annuler les intermédiaires (via git reset) jusqu'à ce qu'elle le devienne, puis ensuite, replacer les commits annulés avec :
* git cherry-pick xxx (où xxx est l'ID du commit)
Par ailleurs, certains logiciels clients Git permettent de rassembler plusieurs révisions sélectionnées depuis une liste, comme la fonction cherry-pick de SmartGit ou NetBeans qui permet de sélectionner des commits existant pour les intégrer à sa branche, ou git blame pour afficher les auteurs de chaque passage.
En console, annuler ou modifier un commit peut être réalisé de plusieurs manières :
* git commit --amend --no-edit
* git reset HEAD~1
* git rebase -i (puis squash)
En cas de réécriture d'historique, le hash du commit change, ce qui ne pose pas de problème en local mais complexifie considérablement les rebases des branches issues de celle réécrite, car Git voit des conflits entre le commit original et celui réécrit.
Pour modifier le résumé d'un ancien commit (xxx) : git rebase --interactive 'xxx^'
Il faut donc éviter de les multiplier : ne pas en enchainer plusieurs avec le même résultats, ou en créer des “fix” du précédent. Il faut les casser et les regrouper. Ainsi les rebase auront moins de conflit, les git blame seront parlant et les git revert de feature deviendront possibles. Dans cette optique, il faut d'ailleurs préférer les rebases aux merges pour éviter l'ajout d'un commit de merge inutile nuisant à la lisibilité et à la taille du dépôt.

## Recherche dans l'historique

Pour rechercher un mot dans tous les historiques de tous les fichiers (du répertoire et des sous-répertoires du script) :
Par ailleurs, git bisect permet de rechercher dans l'historique des révisions en définissant les mauvais et bon commits.

## Continuer

Vous maîtrisez désormais le strict minimum pour travailler avec git. Vous pouvez ajouter, modifier et supprimer des fichier et enregistrer les changements dans votre dépôt local ainsi que consulter l'historique des modifications. Cela reste toutefois une vision simpliste de la gestion de projet et nous verrons dans la suite comment exploiter les branches locales et comment partager votre travail avec d'autres contributeurs en publiant vos modifications sur un dépôt distant et en récupérant les modifications des autres contributeurs.

## Références

* ↑ http://git-scm.com/docs/git-add
* ↑ « Rewriting Git History », Git’s now confused
* ↑ https://git-scm.com/docs/git-bisect
* https://learngitbranching.js.org/ : explications schématisées

# Branches

Précédemment, nous avons vu comment apporter des modifications à une branche telles que ajouter, modifier ou supprimer un fichier et commit nos modifications. Cela fonctionne parfaitement et cela peut suffire pour travailler seul sur un petit projet. Toutefois, ce n'est pas la meilleure façon de procéder sous git qui propose des mécanismes plus élaborés pour développer sur un projet.
L'approche de git est de favoriser l'utilisation de branche pour toute modification du code de l'application.
Ainsi, il ne faut jamais travailler directement sur la branche *master* : cette branche doit rester stable et ne doit être utilisée que pour baser son travail dans d'autres branches.
Pour mieux comprendre, nous allons refaire, pas à pas, exactement les mêmes modifications que celles que nous avons faites précédemment mais, cette fois, nous allons utiliser une branche afin de nous familiariser avec ce concept.
Reprenons notre dépôt d'exemple :

### Créer une première branche

D'abord, demandons à git de nous indiquer où nous en sommes au niveau des branches :
Git nous indique qu'il existe une seule branche appelée master et que c'est sur cette branche que nous travaillons comme l'indique l'astérisque en face de master.
Créons une nouvelle branche que nous allons appeler ma-branche.
Constatons les effets :
Il y a maintenant deux branches : *master* et *ma-branche*. Actuellement, nous travaillons toujours sur *master* comme l'indique toujours l'astérisque.
On peut voir, sur la première ligne que *master* et *ma-branche* sont au même niveau, sur le même commit. Nous allons maintenant demander à git de nous basculer sur *ma-branche* afin de pouvoir travailler sur celle-ci et non sur *master*.
On a basculé, et git branch nous le confirme.
git checkout . supprime le code non commité.

### Faire les modifications

On peut désormais faire les modifications dans ma-branche que l'on peut développer, sans prendre le risque de modifier master.
Faisons les mêmes modifications que précédemment :
Et ainsi de suite. Vous pouvez commiter et faire autant de commits que vous voulez dans ma-branche.
L'idée est que pour chaque évolution du logiciel développé, il faut créer une branche. Ainsi, on peut garder la branche aussi longtemps que nécessaire et continuer de travailler dessus tant qu'on a pas fini la fonctionnalité.
Regardons le log que cela produit :
Examinons ce graphique : master est en retard tandis que ma-branche est en avance de trois commits.

### Fusionner la branche dans master (merge)

Supposons que nous sommes satisfaits du travail réalisé dans notre branche. Nous avons fait plusieurs commits, nous avons vérifié que nous n'avons pas créé de bogue, etc. Supposons que notre branche est prête et qu'on peut intégrer les modifications dans master.
D'abord, se placer sur master :
Puis demander à git de fusionner la branche ma-branche, sans fast forward pour éviter de perdre la topologie de la branche :
Git va faire un commit pour intégrer les changements. Comme précédemment, nous avons choisi d'utiliser -m pour préciser le message de commit mais on aurait pu ne rien mettre et git nous aurait ouvert l'éditeur de texte.
Examinons
On retrouve bien quatre commits nous appartenant (symbolisés par une * dans le graphe). On retrouve les trois premières modifications et un quatrième commit pour le merge. On voit que les branches ont convergé sur le graphique et que master est de nouveau sur la première ligne tout en haut du graphe. Nos changements ont bien été intégré à master.

### Effacer une branche
#### Locale

Nos changements sont intégrés à master, la branche est désormais inutile. Supprimons-la :
La suppression de la branche peut échouer si la branche à supprimer n'a pas été fusionnée dans master :
Git se prémunit donc d'effacer des changements potentiellement non vérifiés. Comme git l'indique, on peut forcer la suppression malgré tout :
NB : une branche ne peut pas être supprimée si on n'a pas fait le dernier commit.

#### Supprimer les veilles branches

Lorsque l'on tape "git branch" après un certain temps, la branche active apparait au milieu d'une multitude d'anciennes branches généralement fusionnées, et donc inutile de conserver en local. Pour les nettoyer on utilise donc :
Mais parfois il reste encore un paquet de branches locales qui ont été mergées sur le serveur. Pour éviter d'avoir à les supprimer une par une :
Sinon, nommer la branche dans laquelle elles furent fusionnées. Par exemple, pour supprimer les branches mergées dans "master" :

## Renommer une branche

Il faut renommer la locale, supprimer la distante, puis pusher la locale :
L'option --set-upstream (alias -u) s'utilise uniquement à la création de la branche sur le serveur distant. Elle doit ensuite être mise à jour avec push tout court.

## Continuer

Vous pouvez à tout moment créer des nouvelles branches depuis master et ce, à chaque nouvelle fonctionnalité ou nouvelle modification qu'il faudrait apporter au projet. Git vous permet de gérer plusieurs branches en parallèle et ainsi de cloisonner vos travaux et d'éviter de mélanger des modifications du code source qui n'ont rien à voir entre elles.
En gardant une branche master saine, vous vous laissez la possibilité de créer de nouvelles branches simplement et vous conservez ainsi une version du logiciel prête à être livrée à tout instant (puisqu'on ne merge dedans que lorsque le développement est bien terminé.
git log vous permet de retrouver dans l'historique les branches qui ont été créées, et les différents commits réalisés pour une même fonctionnalité sont bien regroupés entre eux.

## Références

* ↑ http://stackoverflow.com/questions/9069061/what-is-the-difference-between-git-merge-and-git-merge-no-ff

# Synchroniser le dépôt local avec le dépôt distant

Dans le chapitre précédent, nous avons vu comment vous pouviez travailler seul dans votre dépôt local. Nous allons maintenant nous pencher sur l'aspect distribué de git et voir comment travailler de façon collaborative en communiquant avec d'autres dépôts. Nous allons voir comment publier vos modifications et recevoir les modifications des autres développeurs.

## Simulons un environnement de travail distribué

Nous allons faire travailler ensemble deux personnages, dont la réputation n'est plus à faire, Alice et Bob. Nous allons supposer que Alice et Bob vont chacun créer leur dépôt local sur leur machine avec git clone. Bien évidemment, ils vont utiliser clone en indiquant l'adresse du dépôt principal du projet : http://, https://, git:// ou file:////.
Pour créer un dépôt HTTP(s), il faut qu'il soit lisible par un serveur web (ex : Apache).

### Créons un faux dépôt distant pour nos tests

Il serait prématuré d'expliquer ici comment créer un dépôt sur le réseau. Aussi, pour travailler, nous allons créer un faux dépôt distant en local.
Placez-vous dans un dossier qui ne risque rien (par exemple /tmp), nous allons créer le faux dépôt distant.
Les fichiers d'un dépôt --bare sont cryptés dans le sous-répertoire objects, ils ne sont donc pas accessibles par d'autres programmes que Git.

### Simulons deux utilisateurs utilisant le dépôt distant

Le faux dépôt distant est créé. Maintenant, Alice et Bob vont créer leur copie locale avec clone.

### Alice commence à travailler

En tant qu'Alice, créons quelques modifications.
Alice a maintenant quelques modifications dans son dépôt local, nous allons voir comment elle peut échanger avec Bob.

## Commencer à travailler avec un dépôt distant

Dès que vous voulez faire une opération qui concerne le dépôt distant (publication ou récupération d'informations), commencez toujours par
Cela met à jour les informations sur les dépôts distants auxquels est rattaché votre dépôt local, si vous oubliez de le faire, vous risquez d'être faussé par le fait que l'historique des modifications que vous voyez (par exemple) n'est pas complet.
Ainsi, dès que vous voulez faire une opération qui implique le dépôt distant, souvenez-vous de toujours faire un git fetch.

## Publier les modifications locales sur le dépôt distant

Alice a fait plusieurs modifications sur master, elle voudrait les partager avec Bob, elle doit donc publier ses derniers commits sur le dépôt distant.
Git nous indique que la branche master a été créée sur le dépôt distant.

## Récupérer les modifications d'un dépôt distant

Voyons comment Bob peut récupérer le travail d'Alice.
Git nous indique qu'une nouvelle branche a été créée sur le dépôt distant. On va essayer de la récupérer.
On a bien récupéré les modifications faites par Alice. Si vous ouvrez le fichier mon_nouveau_fichier.txt, vous retrouverez toutes les modifications d'Alice.
À notre tour, faisons une modification :
Le résultat de ce git log ne devrait pas vous surprendre. Néanmoins, cette sortie ne montre pas l'état du dépôt distant. Pour cela, nous allons utiliser l'option --decorate.
Là, on voit bien que notre branche master locale (master) est en avance de un commit sur la branche master distante (origin/master). HEAD indique simplement le commit sur lequel nous nous trouvons. Cela est confirmé par git status :
Publions nos modifications comme git nous le propose :
On retourne chez Alice :
La copie d'Alice semble à jour. Mais où est passé la modification de Bob ? Nous avons oublié le git fetch !
Cette fois-ci, git nous indique que nous sommes en retard de 1 commit, en effet nous n'avons pas récupéré les modifications de Bob. Voyons ce que donne git log. Cette fois-ci, nous allons utiliser l'option --all pour indiquer à git que nous voulons voir toutes les branches, c'est à dire que nous voulons voir origin/master et pas seulement master.
On voit bien notre retard sur le commit de Bob puisque origin/master est plus haut que master. Demandons à git de récupérer les modifications distantes et de les fusionner avec notre master local.
Et ainsi de suite. Chacun peut localement faire plusieurs commits et faire régulièrement git push (« pousser » en anglais) pour publier ses propres modifications et des pull (« tirer » en anglais) pour récupérer les modifications des autres.

## Continuer

Vous maîtrisez maintenant l'essentiel de git pour pouvoir travailler collaborativement sur un projet.
Évidemment, dans notre exemple, nous avons utilisé un faux dépôt distant. Dans la réalité, il faudra créer un dépôt central (régulièrement sauvegardé pour ne pas perdre le projet !) sur une machine réseau pour que tout le monde puisse faire le clone.

# Étiquetage (tags)
## Principe

Git permet d'ajouter des étiquettes (tags en anglais), parfois appelées "balises" (par exemple sur Bitbucket), pour spécifier des versions dans les historiques :
ou :
Pour lister les tags :
Se positionner sur un tag :
Envoyer les tags sur le serveur distant :
Supprimer un tag local :
Supprimer un tag sur le serveur :
Il est déconseillé de supprimer les tags pour tracer l'historique des codes déployés.
Pour recréer un tag :
Ou plus rapidement en gardant son message :

## Étiquettes vs branches

Les étiquettes comme les branches pointent vers une soumission, la différence est que la branche pointe toujours en haut de la ligne de développement et est remplacée par les soumissions postérieures, alors que l'étiquette demeure inchangée.
En pratique, les tags sont donc utilisés pour désigner les versions du programme, et sont donc nommés avec des numéros, si possible selon la SemVer (ex : v1.0.2).

## Références

* ↑ http://git-scm.com/book/fr/Les-bases-de-Git-%C3%89tiquetage
* ↑ https://semver.org/lang/fr/
* ↑ https://stackoverflow.com/questions/8044583/how-can-i-move-a-tag-on-a-git-branch-to-a-different-commit

# Remise (stash)
## Remiser des changements

Cette fonctionnalité permet de remiser des modifications locales quand vous souhaitez changer de branches et que vous ne souhaitez pas les indexer ("git add") ou les ajouter à votre dépôt local ("git commit").
Remiser des modifications (fichiers suivis ou indexés) :
La remise se comporte comme une pile ; les dernières modifications remisées sont placées au sommet de la pile.
Vous pouvez visualiser le contenu de votre remise avec la commande :
Remiser des modifications et des créations (fichiers non suivis ou non indexés) :
Annuler un merge suite à un stash conflictuel :

## Appliquer une remise

Pour appliquer les dernières modifications remisées en les supprimant de la remise :
Note : cette commande est équivalente à "git stash pop stash@{0}".
Pour appliquer les dernières modifications remisées en les laissant dans la remise :
Note : cette commande est équivalente à "git stash apply stash@{0}".
   Il est possible d'appliquer ces commandes à n'importe quelles modifications remisées (par exemple "git stash apply stash@{2}").

## Inspecter le contenu d'une remise

Pour inspecter les dernières modifications remisées :
Pour comparer le contenu de la remise avec le commit tel qu'il était lorsque le remisage a été effectué :
   Il est possible d'appliquer ces commandes à n'importe quelles modifications remisées (par exemple "git stash show -p stash@{1}").

## Supprimer toutes les remises
# Recombinaison (rebase)
## Recombinaison (rebase)

Le rebase permet de mettre à jour sa branche par-dessus une autre. Généralement on rebase une branche par rapport à la branche principale (main) :
En cas de conflit, c'est-à-dire si une même ligne a été modifiée à la fois sur "main" et sur la branche à rebaser, le rebase s'arrête et on doit modifier le fichier pour déterminer le résultat final du commit déplacé. Puis on reprend le rebase avec :
Si on ne veut pas passer du temps à régler manuellement chaque conflit, on peut le faire automatiquement :
* En conservant les modifications de la branche de départ :
* En conservant celles de la branche rebasée :

### rebase -i

Pour changer les messages des soumissions, leur ordre ou leur nombre, on peut utiliser le mode interactif (-i). Exemples :
* sur la branche "main" :
* sur les trois derniers commits :
On peut effacer et fusionner des soumissions en choisissant l'option "s" (squash) ou changer leur ordre.
Pour annuler le rebase en cours :

# Sous-modules et Super-projets

Le super-projet est un concept apparu avec Git depuis v1.5.3, ayant pour but de mieux gérer de nombreux dépôts, en distinguant ceux qui sont hors du super-projet, de ceux à l'intérieur que l'on appelle les sous-modules.

## Super-projets

Un super-projet est un dépôt Git, que l'on crée via git init dans le répertoire, puis git submodule add suivi des archives à inclure :
La structure résultante est de la forme suivante :
Si quelqu'un récupère le super-projet, il trouvera une série de répertoire vide pour chaque sous-module. Pour les utiliser, il faut lancer git submodule init pour chacun.

## Sous-modules

Une archive Git est considérée comme sous-module après avoir exécuté git submodule add dans un autre dépôt.

## Workflow

Le flux de travail des super-projets et des sous-modules dit généralement adhérer à l'ordre :
* Changement du sous-module.
* git commit du sous-module
* git commit du super-projet
* git submodule update pour envoyer les changements aux différents dépôts antérieurs au super-projet.

# Structure interne
## Structure de Git brute

Le schéma suivant représente un dépôt Git v1.5.2.5.

## Fichiers
### HEAD

HEAD indique le code actuellement vérifié. Généralement le point de la branche sur lequel on travaille.
Il est possible d'ajouter un état "HEAD détaché", en dehors de la branche locale. Dans ce cas la tête pointe sur une soumission et non sur une branche.

### config

Le fichier de configuration pour ce dépôt Git. Il peut contenir les paramètres permettant de gérer et stocker les données dans le dépôt local, les distants connus, et les informations sur les utilisateurs (local et autres).

### description

Utilisé par les outils du navigateur de dépôt, contient une description du projet, généralement inchangée dans les dépôts non partagés.

## Dossiers
### hooks

Contient les scripts à lancer quand des évènements particuliers surviennent dans le dépôt Git.
Ces points d'entrée sont utilisés par exemple pour lancer des tests avant chaque soumission, filtrer le contenu uploadé, et implémenter ce genre de personnalisations.

#### Exemple
### objects

Stocke les listes de répertoires, fichiers et soumission.
Il y a les objets non compressés des nombreux répertoires, et les "packs" d'objets compressés. Les premiers sont régulièrement collectés via git gc.

### refs

Contient les informations où les branches pointent. Inclut normalement des répertoires "heads" pour les branches locales, et "remotes" pour les copies des branches distantes. Toutes les branches ne figurent pas dans ces répertoires. Celles qui n'ont pas changé récemment sont listées dans le fichier .git/packed-refs.

## Fichiers Git hors dossier .git
### .gitkeep

Placé dans un dossier, il garantit qu'il sera commité même vide.

### .gitignore

Liste les fichiers et dossiers à exclure du versioning. Ex :

### .gitattributes

Contient des attributs. Par exemple pour ignorer .gitattributes et .gitignore des exports effectués par "git archive" :

## Références

* ↑ Généré avec la commande tree v1.5.1.1 : tree -AnaF.
* ↑ https://www.viget.com/articles/two-ways-to-share-git-hooks-with-your-team/
* ↑ https://git-scm.com/docs/gitattributes

# pull-request
## Principe

Une fois un dépôt distant cloné en local, il est facile de mettre régulièrement à jour sa version, à l'aide de la commande git pull depuis le répertoire du dépôt (via crontab par exemple).
Par contre pour envoyer ses versions développées localement sur le dépôt distant, cela nécessite une pull request (alias PR, ou merge request, MR, voire demande de tirage).

### Intérêt

* Déclencher une notification que le code est prêt à être fusionné, ce qui n'est pas le cas à chaque fois qu'on modifie une branche. Celle-ci a lieu généralement par email mais selon le serveur on peut configurer un hook vers du tchat ou autre.
* S’assigner la traitement de la PR.
* Joindre du texte non versionné dans Git, dans la description de la PR (ex : les cas de test). Et lister les retours de relecture / test de la branche. Ces retours peuvent même être configurés comme bloquant automatiquement le merge tant que pas résolus.
* Bloquer le merge si le résultat des pipelines CI sont en erreur.
* Voir les conflits dans la liste des PR à traiter.
* Supprimer les branches automatiquement après merge.

### Mise à jour

Si la branche a été mise à jour depuis un autre client, git gère la fusion automatiquement si les fichiers modifiés sont différents. Par contre s'il y en a en commun, il faut procéder manuellement avec un rebase interactif :
Pour éviter cela, il faut bien vérifier que la branche sur laquelle on commence à travailler est bien la dernière version, avec :
* Ne pas lancer de pull après un rebase sous peine d'inclure dans sa branche locale, les commits effectués entre-temps sur la branche principale.
* Ne pas lancer un push après un reset total de la branche, car une PR sans commit sera automatiquement fermée.

## Références

* https://git-scm.com/docs/git-request-pull

# Recettes
## Supprimer un fichier du dépôt tout garder le fichier

git rm fichier.txt supprime le fichier du dépôt mais supprime aussi le fichier local.
Pour ne l'enlever que du dépôt, utiliser git rm --cached fichier.txt.
Ajouter "-r" pour les dossiers.

## Annuler une soumission

Quand on ne peut pas réécrire l'historique (par exemple en production) mais qu'il faut annuler un commit, on utilise git revert avec HEAD pour désigner la dernière soumission effectuée :
Pour signifier d'autres soumissions que la dernière :
* git revert HEAD^ : l'avant dernière.
* git revert HEAD~5 : la cinquième moins récente.
* git revert e6337879 : la soumission n°e6337879.
Ensuite, il est recommandé de vérifier que le rollback a bien fonctionné en s'assurant de l'absence de différence entre le code actuel et celui de n-1 (où n est le nombre de commits annulés)

### Annuler un merge

On ne peut pas annuler un merge comme un commit, il faut indiquer le nombre reverté (où réverter un seul merge de plusieurs commits reverte tous les commits) :

## Nettoyer les changements non soumis

Pour annuler les modifications de fichiers non soumises (discard) :
Pour annuler les créations de fichiers non soumises :

## Annuler les changements soumis
### reset

Par ailleurs, il existe plusieurs niveaux de reset :
* soft : ne touche pas à l'index ni au répertoire de travail. Les fichiers en reset retournent juste de la liste des commités à celle à commiter.
* hard : efface l'index et le répertoire de travail. Cette option équivaut à un reset + clean.
* mixed : celui par défaut, mélange des deux précédents. Il laisse les fichiers du répertoire de travail, mais annule l'index.
* merge
* keep
Pour effacer les changements en cours, en rétablissant les états de la dernière soumission :
ou
Pour ne toucher qu'un seul fichier :
* Pour effacer les deux derniers commits sans toucher aux fichiers : git reset 'HEAD~2'.
* Pour effacer les deux derniers commits et leurs modifications dans les fichiers : git reset HEAD~2 --hard.
* Pour revenir deux opérations en arrière sur la branche : git reset HEAD@{2} (utilise la liste des opérations visible dans git reflog). Cela peut donc permettre d'annuler un reset malencontreux.

### restore

git restore revient à la version du fichier spécifié en paramètre.
Par exemple, pour restaurer tous les fichiers du dossier courant :
Pour annuler des "git add" (donc retirer un fichier de la zone de transit) :

## Récupérer une version de fichier

Il faut d'abord récupérer l'identifiant de la version avec git log :
Ensuite pour lire la version, utiliser git show :

## Créer et appliquer un patch

Créer un patch génère un texte de toute la série des changements entre les branches origines et master.
Pour appliquer un patch :
Le patch est aussi le mode de transfert entre dépôts.

## Références

* ↑ http://serebrov.github.io/html/2014-01-04-git-revert-multiple-recent-comments.html
* ↑ https://git-scm.com/docs/git-reset
* ↑ https://git-scm.com/docs/git-restore
* ↑ https://git-scm.com/docs/git-format-patch

# Exclure des fichiers du dépôt
## Principe

Souvent il y a des fichiers dans l'espace de travail qui ne sont pas souhaitables dans le dépôt :
* Les fichiers générés temporairement. Par exemple, emacs crée automatiquement une copie des fichiers édités avec, avec un suffixe tilde, comme fichier1~. Il faut donc éviter manuellement de les soumettre.
* Les fichiers de secours (backup) comme, par exemple, les fichiers .bak générés par les outils de comparaison de fichiers après des opérations de fusion.
* Les fichiers générés lors de la compilation,
Certains fichiers (notamment ceux générés lors de la compilation) sont en général situés dans un répertoire particulier, qu'il est possible d'exclure des dépôts Git.

## .gitignore

Pour dire à Git d'ignorer certains fichiers, il est possible de créer un fichier .gitignore. Chaque ligne y représente une spécification (avec wildcards) des fichiers ou répertoires à ignorer. Des commentaires peuvent être ajoutés dedans sur les lignes débutant par un blanc ou un dièse :
Ce fichier sera ensuite automatiquement proposé pendant les commits, de sorte que tous les développeurs du dépôt auront la même liste de fichiers à ignorer.
De plus, certains caractères sont interprétés, comme le "!" en début de ligne qui signifie "sauf" (ex : exclure un dossier sauf un de ses fichiers).
Si un fichier a déjà été commité, l'ajouter dans .gitignore ne changera rien : il faut d'abord le supprimer de la branche.

## exclude

Pour n’ignorer des fichiers que sur son propre poste, il faut les placer dans .git/info/exclude. Ainsi, ils ne seront jamais proposés pendant les commits.

## Recherche

Pour déterminer les fichiers ignorés d'un dossier ou pourquoi un fichier est ignoré, utiliser "check-ignore". Exemple :

## Références

* ↑ https://www.atlassian.com/git/tutorials/saving-changes/gitignore

# Écrire des messages de commit
## Rédaction

Les bonnes pratiques sont :
* 50 caractères maximum pour le titre, résumant les changements.
* Selon le contexte, la première ligne est traitée comme le sujet d'un email et le reste séparé par une ligne blanche, comme le corps du message.
* Utiliser le présent des verbes.
* Les listes à puces sont autorisées, typiquement avec un moins ou une astérisque.
* Le corps du message doit comprendre des lignes de 72 caractères maximum pour plusieurs raisons :
** git format-patch --stdout convertit une série de soumission en une série d'emails.
** Le log Git ne revient pas automatiquement à la ligne, sans retour chariot il est donc étalé sur une seule ligne donc difficile à lire. Le nombre 72 est le résultat du calcul des 80 du terminal (selon la nétiquette des mails), moins les 4 de l'indentation et les 4 de sa symétrie à droite.
Les utilisateurs de Vim peuvent rencontrer ce prérequis lors de l'installation de vim-git, ou bien en le définissant dans la configuration des messages de soumission Git :
Ceux de TextMate peuvent ajuster l'option colonne "Wrap" du menu "view", puis utiliser ^Q pour revenir à la ligne des paragraphes (s'assurer qu'il y a une ligne blanche après pour éviter le mélange avec les commentaires). Voici une commande shell pour ajouter 72 au menu afin de ne pas avoir à le faire glisser à chaque fois :

## Consultation

Ces résumés peuvent ensuite être lus via :
* git log --pretty=oneline affiche une courte liste des historiques avec identifiants et résumés.
* git rebase --interactive fournit les résumés de ses propres soumissions.
* Si l'option de configuration merge.summary est définie, les sommaires de toutes les soumissions seront fusionnés.
* git shortlog n'affiche que les résumés des précédentes soumissions.
* git format-patch, git send-email.
* git reflog, un historique local est accessible pour aider à retrouver d'éventuels erreurs.
* git blame
* Des interfaces graphiques :
** gitk, une interface qui a une colonne résumé.
** Gitweb
** Les interfaces web de la forge qui héberge le dépôt affichent également les résumés (ex : GitHub, Bitbucket ou GitLab).
La distinction sujet/corps de texte de Git permet donc un confort de recherche d'historique par rapport à d'autres logiciels similaires comme Subversion.

## Références

* ↑ http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
* ↑ https://www.midori-global.com/blog/2018/04/02/git-50-72-rule

# Intégration dans les IDEs

Git est intégré avec la plupart des IDEs, soit nativement, soit par installation d'extensions.

## Eclipse

Eclipse intègre Git avec l'extension EGit (https://www.eclipse.org/egit/). Cette extension fournit une vue du dépôt Git. La configuration de Git est accessible dans la fenêtre des préférences sous le nœud "Team".
Parmi les opérations possibles :
* Cloner un dépôt Git,
* Créer un dépôt local,
* Commiter les changements,

## Visual Studio Code

Visual Studio Code a une vue permettant de voir les fichiers modifiés, supprimés et ajoutés, de commiter les changements, et de synchroniser le dépôt local avec le dépôt distant (pull et push), l'extension « Git Graph » permet de visualiser le log des changements et les branches.

## PhpStorm

PhpStorm possède un plugin "Git" permettant de voir l'historique des modifications des fichiers en couleur. On y accède par un onglet en bas, côté du terminal, ou par un clic droit sur un dossier ou fichier dans le menu de navigation à gauche, ou encore avec un clic droit dans la marge d'un fichier versionné ouvert puis afficher des annotations. Ce dernier chemin lance un "git blame" pour retrouver l'auteur de chaque ligne du fichier, et on peut ensuite réitérer l'opération en affichant les annotations précédentes pour remonter tout l'historique.
De plus, quand on regarde le différentiel des fichiers modifiés depuis le dernier commit (onglet "Version Control" en bas, "resolve", puis "merge..."), en cas de conflit il propose un outil de résolution à trois colonnes très ergonomique.
Enfin, il est recommandé d'ajouter le dossier .idea/ créé par PhpStorm dans le fichier .gitignore car il n'est pas censé être le même sur toutes les machines.

# Améliorer sa productivité en configurant Git

Dans ce chapitre, nous allons voir comment vous pouvez adapter git à vos propres besoins.

## Apprendre à configurer git

Vous pouvez intervenir à trois niveaux :

### Au niveau system

    dans ce cas, la configuration s'appliquera à tous les utilisateurs de votre système.

### Au niveau global

    dans ce cas, la configuration sera appliquée à vous seul utilisateur et pour tous les dépôts. C'est l'option la plus courante.

### Au niveau local

    dans ce cas, la configuration sera appliquée uniquement à ce dépôt.
Vous avez deux possibilités :

### Travailler avec la commande git config

    Vous devrez donc utiliser respectivement --system, --global ou ne pas mettre d'argument (git appliquera la commande au dépôt).

### Modifier le fichier de configuration de git (avec un éditeur de texte)

    Vous devrez donc modifier respectivement les fichiers /etc/gitconfig, ~/.gitconfig ou le fichier .git/config qui se trouve dans le dépôt.
Dans les exemples qui suivent, nous travaillerons sur le niveau global car c'est ce que le développeur souhaite la plupart du temps.
Pour voir, à tout moment, votre configuration :

## Activer la coloration de la sortie par défaut

Par défaut, git doit colorer la sortie de vos commandes sur le terminal. Si ce n'est pas le cas, vous utilisez une version trop ancienne de git.
Vous pouvez toutefois configurer git pour forcer ce comportement par défaut.

## Créer des alias pour vos commandes les plus courantes

La création d'alias peut se faire dans le fichier de configuration : vim ~/.gitconfig. Les alias sont alors utilisables comme les autres commandes de Git, comme premier argument de la commande git.
* Exemple pour afficher les logs à un certain format :
Un alias peut aussi se créer en ligne de commande :
* Retrouver la branche d'un commit en le plaçant en paramètre $1 (Pull Request). Ex : git pr 0eccb68 :
* Ouvrir les fichiers modifiés sur une branche dans un IDE (par exemple pour reprendre le travail après un checkout) :

## Références

* ↑ https://coderwall.com/p/kxb7kg/find-a-pull-request-given-the-commit-sha

# Linux

Nous allons maintenant voir comment, lorsque vous travaillez sous Linux, vous pouvez travailler au mieux avec Git et augmenter votre productivité.

## Installer un prompt git

Si vous travaillez sur un projet plusieurs heures d'affilée, vous avez probablement une console qui reste ouverte en permanence pour commiter régulièrement. Autant éviter de taper « git » à chaque fois, et de passer son temps à faire des « git branch » pour savoir sur quelle branche on travaille.
Pour gagner du temps, vous pouvez installer un prompt git, et pour commencer à travailler, taper
Cela nous ouvre un prompt git. Désormais, l'invite de commande vous indique le répertoire dans lequel vous vous trouvez mais aussi la branche courante. Toutes les commandes sont automatiquement préfixées par "git", vous pouvez taper directement la commande git à appliquer.
Ctrl+D vous permet de quitter le prompt à tout moment.
Ce shell intègre également beaucoup de raccourcis, consulter git sh --help pour avoir la liste. Quelques exemples :
Si vous tapez dans commande système telles que rm (pour supprimer un fichier) ou reset (pour purger l'affichage dans le terminal), ce sera git rm et git reset qui seront appelées ! Ce n'est pas ce que vous voulez.

## Configurer plusieurs comptes vers la même forge

Par exemple pour utiliser un compte Git personnel et un professionnel sur GitLab sur le même PC, cela comporte deux étapes :
* Générer et ajouter les clés SSH sur https://gitlab.com/-/profile/keys (pas rsa car incompatible)
* Ajouter le mapping des clés avec les dépôts avec vim ~/.ssh/config

# Windows
## Configuration

Après installation, trois raccourcis sont accessibles dans le menu démarrer :
* Git Bash : langage Unix.
* Git CMD : langage DOS.
* Git GUI : interface graphique.
Pour que Git se positionne par défaut dans le répertoire de votre choix à chaque ouverture, sous Windows faire un clic droit sur son raccourci, puis modifier le chemin du champ "démarrer dans".

## TortoiseGit

TortoiseGit est un client pour Git qui permet de gérer ses dépôts depuis l'explorateur Windows.
* Options (clic droit d'un dossier)
* Clone
* Commit
* Push
La vue des synchronisations permet de consulter la liste des fichiers modifiés (Out ChangeList) avec le différentiel dans chacun si on double-clique dessus (dans une fenêtre TortoiseGitMerge par défaut).
Elle permet aussi d'ouvrir l'option Settings en cliquant sur Manage. Pour enregistrer une connexion dans ces paramètres, cliquer sur le sous-menu de Git appelé Remote (s'il n’apparaît pas, sortir et sélectionner un répertoire avant d'y retourner). L'URL du dépôt peut être de la forme :
* ssh://depot@depot.example.com/home/depot/. Mot de passe à entrer chaque connexion, ou utilisation d'une clé SSH.
* http://depot.example.com/home/depot/. Mot de passe à entrer chaque connexion, ou configuration de netrc over HTTP avec cURL.
En cas d'erreurs SSH, se reporter au wikilivre Le système d'exploitation GNU-Linux/Le serveur de shell distant SSH#Problèmes connus.
Une fois installé, le processus TortoiseGit se lance à chaque démarrage et est susceptible de bloquer la suppression de fichiers par l'explorateur.

## Modifier les permissions d'un fichier

Windows ne gère pas les permissions unix/linux des fichiers, permettant notamment de rendre exécutable un script bash. Cependant, il est possible de modifier les permissions des fichiers au niveau staged de Git, de deux manières différentes. Dans les deux cas, comme tout changement au niveau staged, il faudra ensuite commiter les changements, et potentiellement pousser la modification sur le dépôt distant.

### Avec TortoiseGit installé

Si TortoiseGit est installé, les permissions sont modifiables dans la boîte de dialogue standard des propriétés du fichier par un clic droit sur le fichier, menu "Propriétés", onglet "Git".

### En utilisant Git Bash

Dans un terminal Git Bash :
* Changer le répertoire courant pour celui contenant les fichiers dont les permissions doivent être modifiées.
* Entrer la commande suivante pour voir les permissions actuelles :
    git ls-files --stage
* Entrer la commande suivante pour modifier les permissions d'un fichier, en les spécifiant avec l'option --chmod :
    git update-index --chmod=+x script.sh

## Références

* ↑ https://medium.com/uncaught-exception/setting-up-multiple-gitlab-accounts-82b70e88c437
* ↑ http://www.mavetju.org/unix/netrc.php
* ↑ https://curl.haxx.se/docs/manual.html

# GitLab

GitLab est une forge logicielle open-source lancée en 2011.
Elle fournit une interface graphique pour créer des branches, des tags, des pull requests (appelées merge requests), les relire et les fusionner.
GitLab ne permet pas de créer de nouveaux groupes d'utilisateurs (les quatre possibles sont ceux par défaut), mais on peut inviter une personne sur un dépôt avec un autre groupe que celui qu'elle a ailleurs. Et il gère aussi des groupes d'applications dans lesquels un utilisateur peut avoir les mêmes droits.

## CI/CD

GitLab CI/CD est un outil d'intégration continue et de déploiement continue, fourni avec la forge logicielle Gitlab.
Un pipeline est un ensemble de jobs déclenché automatiquement après différentes actions manuelles (git push, création de merge request, merge de branche, création de tag, ou clique sur le job à lancer).
Ces jobs peuvent être lancés dans un certain ordre ou en parallèle, selon les étapes (stages) auxquelles ils appartiennent.

### IHM

Dans le menu de gauche de GitLab, cliquer sur :
* "Build" pour voir les tâches qui se lancent sur les serveurs "runners" :
** Pipelines : liste des groupes de jobs déjà lancés sur le dépôt.
** Jobs : liste de tous les jobs.
** Pipeline editor : éditeur en ligne du fichier .gitlab-ci.yml du dépôt. Il s'agit du fichier versionné contenant la configuration des pipelines.
** Pipeline schedules : gestion des tâches planifiées.
** Artifacts
* Settings : accessible uniquement aux propriétaires du repo, pour configurer par exemple les branches protégées ou les conditions de fusion des merge requests.

### .gitlab-ci.yml

Pour qu'un pipeline se lance par hook dans un dépôt, il doit contenir un fichier .gitlab-ci.yml à la racine.

#### before_script

Script à exécuter avant chaque job.

#### variables

Variables appelables plusieurs fois au sein du .gitlab-ci.yml. Certaines permettent de configurer le comportement de GitLab CI. Exemple :

##### GIT_STRATEGY

Politique de clonage :
* none : pas de clone (ex : si on utilise une image Docker).
* fetch : clone différentiel depuis le dernier.
* clone : clone à partir de zéro.
La valeur par défaut est définie dans l'IHM : /settings/ci_cd.

##### GIT_DEPTH

Définit la profondeur lors du clone du dépôt : shallow clone.

##### CI_PIPELINE_SOURCE

Origine du pipeline (ex : push, merge, tâche planifiée, clic sur le job...).

#### Dans un job
##### stage

Étape qui lancera le job.

##### script

Script à lancer.

##### rules

Conditions pour déclencher ou interdire le job courant.
Cette clause est préconisée car plus complète, par rapport à "only" et "except" qui servent lister des branches où le job peut s'exécuter ou pas (lors des merges).

##### dependencies

Définit les jobs ont on récupère les artefacts pour le courant.

##### needs

Noms des étapes obligatoires avant.

##### parallel: matrix

Type de needs définissant des jobs à exécuter en parallèle.

##### parent et child

Jobs à exécuter dans un sous-graphe.

##### include

Inclut un .yaml de CI (local ou distant). Ce qui permet par exemple de le construire avant de l'exécuter depuis un autre job.

##### trigger

Pour déclencher une action, par exemple un "include" ou un job d'un autre projet.

#### Exemple complexe

Voici le squelette d'un pipeline complet, dans lequel il faudrait remplacer les echo par les vraies opérations :

#### Debug

Vérifier les valeurs des variables :

#### Importation

Il est possible d'incorporer des tâches de GitLab dans le pipeline, par exemple pour la sécurité :

### Déploiements
#### Lancement de tests à chaque Merge Request

À chaque Merge Request (alias Pull Request, ou PR, ou MR), un job est créé pour lancer les instructions du .gitlab-ci.yml dans l'ordre. Mais avant de se lancer, il doit attendre la disponibilité d'un serveur de test sur lequel s'exécuter, appelé "runner".
Les runners peuvent être fournis par GitLab ou installés soi-même. Dans ce cas leur configuration se trouve dans un fichier .toml.
Une fois l'évènement GitLab déclenché, la commande pour déployer dépend de l'environnement cible. Par exemple pour Kubernetes, un curl peut-être utilisé.

#### À partir d'une image Docker du registre

Le principe consiste à envoyer une image Docker dans le registre GitLab pour que les conteneurs puissent l'utiliser ensuite sans avoir à le reconstruire.
$CI_REGISTRY_IMAGE représente l'URL du registre, ex : https://registry.gitlab.com/mon_espace.

##### Via Docker-compose

Utile en cas de communication entre plusieurs conteneurs.

##### Via Kaniko

Si les conteneurs déployés le sont dans un autre conteneur, cela peut occasionner des problèmes de performances. Kaniko est un système pour éviter cela.

## Références

* ↑ https://docs.gitlab.com/ee/ci/
* ↑ https://docs.gitlab.com/ee/ci/runners/configure_runners.html#git-strategy
* ↑ https://docs.gitlab.com/ee/ci/large_repositories/
* ↑ https://docs.gitlab.com/ee/ci/variables/#list-all-environment-variables
* ↑ https://docs.gitlab.com/runner/
* ↑ https://docs.gitlab.com/ee/ci/docker/using_kaniko.html

## Voir aussi

* Jenkins

# GitHub

GitHub est une forge logicielle lancée en 2008, puis rachetée par la société Microsoft en 2018.
Contrairement à GitLab, il ne peut y avoir qu'un seul admin par repo, mais on peut créer des groupes d'utilisateurs pour son organisation. Donc s'il y a plusieurs mainteneurs de prévu, mieux vaut créer le dépôt dans l'organisation au lieu de le faire dans un profil personnel.

## Interface

GitHub est utilisable 100 % en ligne, possède aussi un client lourd pour générer des commandes Git.
Dans la vue de comparaison, ajouter "w=1" (white spaces) à l'URL permet de masquer les modifications d'espaces et retours à la ligne.

## CI/CD

Les pipelines ont été ajoutés en 2019 dans GitHub Actions.
Ils sont configurés en cliquant sur "Actions", et sauvegardés dans des .yml du dossiers .github/worflows/ de l'application.

### Exemple simple

Pipeline avec deux étapes successives en Python, dans le fichier .github/worflows/python_app.yml :

## Migrer de GitHub vers GitLab

L'interface graphique de GitLab permet d'importer un dépôt GitHub dont on est admin mais cela ne change pas la configuration des PCs et serveurs qui pointaient vers GitHub.
Pour ce faire, depuis chacun d'eux :

## Références

* ↑ Repositories owned by personal accounts have one owner. Ownership permissions can't be shared with another personal account
* ↑ https://github.com/account/organizations/new?plan=free
* ↑ https://docs.github.com/en/organizations/organizing-members-into-teams/creating-a-team
* ↑ https://rtask.thinkr.fr/transform-a-folder-as-git-project-synchronized-on-github-or-gitlab/

# Bitbucket

Bitbucket est une forge logicielle de la société Atlassian, lancée en 2008.

## CI/CD

La configuration des pipelines se trouve dans bitbucket-pipelines.yml.
Un éditeur / validateur en ligne existe sur https://bitbucket-pipelines.atlassian.io/validator.
Les variables spécifiques aux pipelines (qui ne doivent être versionnées dans le dépôt) sont configurables dans l'interface sur /admin/addon/admin/pipelines/repository-variables.

### Runners

La version gratuite permet de lancer 50 min de pipelines par mois.
Pour éviter cela, on peut lancer les builds sur ses propres serveurs (runners), définis dans /admin/addon/admin/pipelines/runners.

### Exemple simple

Voici un pipeline avec deux étapes parallèles PHP :

# Passer de Subversion à Git

Si vous maîtrisez subversion, vous aller sûrement être perturbé dans votre passage à git. En effet, l'écart entre gestion de version centralisée et gestion de version décentralisée est important et ces deux outils ne s'utilisent pas du tout de la même façon même s'il y a des similitudes.
Ce chapitre s'adresse aux personnes qui utilisent subversion et il vise à lever les ambiguité et les confusions qui surgissent quand on découvre git.

## Quelques confusions habituelles
### Les tags ne sont pas des branches

    Dans subversion, on crée un tag par copie du trunk dans un nouveau dossier qui porte le nom du tag. On recrée ainsi toute l'arborescence du trunk dans un dossier (en fait, une branche puisque c'est une dérivation du tronc) du dépôt. Dans git, les tags ne sont pas des branches. Un tag désigne simplement un commit précis du dépôt.

### L'opération commit n’envoie aucune information vers le dépôt distant

    Dans subversion, commit envoie toutes les modifications réalisées sur votre copie locale vers le dépôt distant. Dans git, commit enregistre les modifications dans votre dépôt local.

### L'opération checkout ne récupère pas un dépôt distant mais change la branche courante.
## Équivalences entre les commandes git et les commandes subversion

La principale différence entre Git et Subversion (Svn) est que Git possède un dépôt local intermédiaire entre la copie de travail où les fichiers sont modifiables directement et le dépôt distant. Il peut aussi n'y avoir pas de dépôt distant, surtout en début de projet. Cette section suppose qu'un dépôt distant existe, si ce n'est pas le cas, il suffit de ne pas exécuter les commandes le concernant.

### Récupérer un dépôt distant

Pour Svn, cela crée une copie de travail. Pour Git, cela crée une copie de travail et un dépôt local.
| Svn | Git |
| svn checkout repositoryurl | git clone repositoryurl |

### Soumettre les modifications locales

| Svn | Git |
| svn commit -m message | git add files... git commit -m message git push |

### Mettre à jour son dépôt local / sa copie de travail

Soumettez vos modifications locales avant de mettre à jour pour éviter les conflits et la perte des modifications locales.
| Svn | Git |
| svn update | git pull |

## Ressources externes

* svn crash course

# Travailler avec Git local et un dépôt Subversion distant

Git permet de participer à de nombreux autres systèmes de contrôle de version, comme git-svn ou git-cvsimport.

## SVN

La compatibilité entre Git et Subversion est assurée par git-svn qui autorise un utilisateur à accéder et participer à un dépôt SVN. Les utilisateurs peuvent générer des patchs locaux pour les envoyer par liste de diffusion, ou soumettre leurs changements aux dépôts d'origine.

### Premiers pas

Pour commencer à utiliser Git avec des projets sur des serveurs Subversion, il faut créer un dépôt local, et configurer git-svn :
Le paramètre "première révision" peut être "1", mais pour gagner du temps il est possible de ne prendre que les 10 dernières révisions. svn info indique alors ces révisions.
Généralement quand on travaille avec des dépôts Subversion, on communique l'URL du projet complète. Pour déterminer l'URL du dépôt racine :
Une ligne du résultat indique le dépôt racine. Le chemin du tronc est simplement le reste de l'URL qui suit.
Il est possible de simplement donner à git-svn l'URL complète du projet, mais cela peut stopper la possibilité de travailler sur des branches SVN.

#### Exemples

Obtenir Pywikipedia :
Récupérer AWB (AutoWikiBrowser) :
Cette opération de téléchargement peut prendre une heure.

### Interagir avec le dépôt

L'avantage de travailler avec Git sur des dépôts SVN est l'utilisation en local. Dans ce cas :
* Ne pas lancer git pull
* Dans une branche mieux vaut éviter de lancer git-svn dcommit car les soumissions fusionnées ont tendance à embrouiller git-svn. Par contre, combiner les changements avec ceux de Subversion en amont est équivalent à svn update :
La première et la dernière ligne ne sont pas nécessaires si l'arbre est propre.
Le git rebase trunk laisse les soumissions locales au dessus du HEAD SVN.

### Changements locaux

Pour éviter de propager des modifications locales indésirables (débogages, tests...), avec git svn dcommit, sans les perdre peut passer par deux approches.
Premièrement, maintenir une branche locale pour chacune qui devra contenir des changements locaux. Par exemple faire un rebase sur "branche1" au-dessus de "branche1-locale". Exemple :
Deux choix sont ensuite possibles, effectuer directement les changements sur la branche locale, ce qui est plus rapide que de les soumettre à la branche distante avant de les récupérer dans la locale. Ensuite il est possible d'utiliser git reset pour les retirer de la branche distante.
Comme une alternative à l'approche centrée recombinaison, il existe une méthode basée sur la fusion. Tout en conservant les changements sur une branche locale, mais sans avoir à conserver la branche au dessus de la branche locale par recombinaison.
C'est un avantage car :
* Sinon il y a plus à écrire.
* Historiquement, la recombinaison a souvent demandé de résoudre le même conflit deux fois, s'il survient pendant la première recombinaison.
Donc à la place des recombinaisons, on crée une nouvelle branche servant à la construction. Il faut la démarrer avec la soumission à tester. Ensuite git merge fusionne la branche locale, apportant tous les changements dans un seul arbre. La raison de cette fusion dans une branche reconstruction est pour dissuader l'utilisation de git-svn dcommit (qui soumettrait les tests indésirables sur le serveur).
Cette approche peut même rendre facultative la recombinaison quotidienne la branche avec le tronc. En cas de branches multiples, les recombinaisons permanentes peuvent s'avérer chronophages :
La construction contient ensuite les changements du tronc, branche1 et branche1-locale !
Il est possible de conserver plusieurs branches locales dont une avec les tests. Cette approche peut être développée avec une branche par sujet dans un arbre :
Malheureusement, la fusion de cette pieuvre ne résout pas les conflits. Dans ce cas il faut appliquer les fusions une par une :

### Envoyer des changements en amont

Éventuellement, pour soumettre au serveur des branches sujet avec un accès commit, on peut lancer git-svn dcommit. Cela prendra chaque soumission locale dans la branche courante et le soumettra à subversion. Par exemple avec trois soumissions locales, après dcommit il y aura trois nouvelles soumissions dans subversion.
Sans accès commit, le patch devra probablement être soumis via une liste de diffusion ou un logiciel de suivi de problèmes (bug tracker). Pour cela on peut utiliser git-format-patch. Par exemple pour trois soumissions locales :
Le résultat sera trois fichiers en $PWD, 0001-commit-name.patch, 0002-commit-name.patch, et 0003-commit-name.patch, qui pourront être attachés à des emails ou joint à Bugzilla. Remarque : il existe git-send-email pour envoyer les emails directement :
Si les séries de patchs ne sont pas dans l'ordre, voir git rebase -i.

## Références

* ↑ git-rebase
* ↑ http://www.kernel.org/pub/software/scm/git/docs/git-reset.html

# Participer au développement de Wikimédia
## Prérequis
### Clé SSH

Les soumissions effectuées par Git doivent être authentifiées par Gerrit. Pour ce faire il faut ajouter une clé publique dans son compte https://gerrit.wikimedia.org/r/#/settings/ssh-keys (nommé login dans les exemples ci-dessous).

### git-review

git-review est un outil en mode ligne de commande pour Git / Gerrit permettant de soumettre une modification, ou de récupérer une modification existante.
ou :

## Site Mediawiki

Le dépôt examples.git existe pour s'entraîner.
Le fichier test1.php est maintenant présent sur le dépôt de la fondation.

## Module quiz
# Problèmes connus
## Impossible de cloner un dépôt

Plusieurs erreurs possibles :
* fatal: Authentication failed for... : l'identifiant de la forge n'est pas le bon.
* Host key verification failed : la clé SSH du dépôt à cloner ne correspond pas à la locale. Par exemple si le clonage a lieu dans un Docker, ce dernier doit avoir accès une clé connue du dépôt (au moyen d'un volume partagé avec l'hôte).
* fatal: Could not read from remote repository / Impossible de lire le dépôt distant : si le git clone est refusé en SSH, essayer en HTTPS. Sinon, créer une clé d'authentification sur le dépôt.
* fatal: repository 'http://MonServeur/MonDepotEnLigne.git' not found / remote: The project you were looking for could not be found or you don't have permission to view it : si le dossier existe et est accessible en HTTP, mais que le clone, pull ou push ne le trouve pas :
** Vérifier que l'utilisateur a les droits d'écriture (pour Windows avec IIS, c'est II_IUSRS).
** Si le dépôt est sur le LAN, éviter HTTP : git clone file:////MonServeur/c$/inetpub/wwwroot/MonDepotEnLigne.git.
** Dans le cas d'un clone d'un dépôt privé, vous devez faire partie des invités.
** Si c'est en SSH, se loguer avant. Ex : ssh -T git@gitlab.com.
*** Si cette commande renvoie "error in libcrypto", c'est peut-être que le rsa n'est pas supporté. Auquel cas il faut regénérer une clé par exemple en ed25519.
** Si c'est en HTTP, tester en ajoutant en nom d'utilisateur dans l'URL. Ex : https://mon_login_gitlab@gitlab.com/mon_login_gitlab/mon_repo.git.
** Dans le cas d'un clone de GitHub, ce site n'accepte plus les mots de passe depuis 2022, mais demande à la place un token généré sur https://github.com/settings/tokens.
** Si vous avez deux comptes Git sur la même forge (ex : pro et perso), les ajouter tous les deux dans ~/.ssh/config.

## Un fichier du .gitignore apparait malgré tout dans ceux à commiter

C'est certainement que le fichier avait été commité avant d'être ajouté au .gitignore. Il faut donc le supprimer dans un commit (sans qu'il soit dans .gitignore sinon sa suppression sera ignorée) puis regarder à nouveau s'il apparait. Si c'est le cas le faire disparaitre avec git rm --cached nom_du_fichier.

## Un fichier ou un dossier n'est pas commité avec les bonnes majuscules

Problème propre à Windows :
Ne pas changer cette configuration avant de faire un rebase sur une branche créée sans elle, sous peine de ne pas pouvoir rebaser sur les commits de configuration différente.

## cannot checkout in the current repository state

Il y a des fichiers créés qui doivent être supprimés ou archivés avant de pouvoir créer une nouvelle branche :

## error: droits insuffisant pour ajouter un objet à la base de données .git/objects du dépôt

Recloner pour que le dépôt fonctionne.

## error: bad index file sha1 signature, fatal: index file corrupt

Recloner pour que le dépôt fonctionne (le dépôt a certainement été copié manuellement au lieu d'être cloné).

## error: ... Permission denied

Un problème de permissions est survenu. Si elles sont bien définies pour le compte utilisé, et que le projet utilise Docker, relancer les conteneurs.

### error: could not open '.git/rebased-patches' for reading: Permission denied

Erreur lors d'un rebase. Cela peut survenir avec Docker Desktop, dans ce cas :
* Lancer rebase -i débloque la situation.
* Sinon, lancer le rebase dans un conteneur où le volume du dépôt est partagé.
* Sinon, recréer la branche à partir de celle de base, soit par cherry-pick, soit "stash -u" sur le contenu de la branche à rebaser, la supprimer, puis "stash pop" sur une nouvelle branche du même nom.
* Sinon, remplacer le rebase par un merge.

### error: opening .git/config: Permission denied

Lors du clonage, au pire on peut télécharger le dépôt.

### error: permission denied (publickey)

Utiliser HTTPS au lieu de SSH.
Ou initialiser SSH. Ex : ssh -vT git@github.com.

## error: could not restore untracked files from stash

Se produit lors d'un git stash pop ou git stash apply vers des fichiers en conflit. Pour que le stash les remplace :

## error: failed to push some refs to ...

Il y a plusieurs solutions :
* git reset HEAD~1 && git pull && git add -A && git commit -m "Mon commit" && git push.
* git pull && git push : plus simple à faire mais ajoute un merge local pouvant polluer l'historique de la branche.
* git pull --rebase && git push : plus propre mais avec risque de conflits.

## error: impossible de restaurer les fichiers non-suivis depuis le remisage

Forcer l'application du stash avec :

## error: le commit cc636d99b0ac37ba8a5c14a70ce69cb223055deb est une fusion mais l'option -m n'a pas été spécifiée.

Pour annuler un merge, il faut rajouter "-m 1" :

## error: pathspec 'MaBranche1' did not match any file(s) known to git

Il faut récupérer les nouvelles branches du serveur avec :

## error: src refspec master does not match any

Il faut faire un git add * avec au moins un changement.

## error: The branch 'ma-branche' is not a strict subset of your current HEAD.

Voir Git/Branches.

## error: Your local changes to the following files would be overwritten by merge

Pour sauvegarder le travail local :
Pour supprimer le travail local :
On peut mélanger les deux si on supprime d'abord quelques fichiers avant de sauvegarder le reste :

## failed to create a new commit

Reconfigurer :

## failed to create a pull request

Faire un "git push" avant, pour que le serveur connaisse la branche.

## failed to push some refs to 'MonDepot1.git' hint: Updates were rejected because the tip of your current branch is behind

voire

## failed to sync this branch because due to unmerged files

Le dépôt distant possède certains fichiers qui sont plus à jour que le local, et vice-versa.
Si le message provient d'une interface graphique, essayer de la fermer et de lancer la synchro en shell, avec git push. Cela peut donner un message plus précis, ex :
Dans ce cas, on peut modifier le fichier "config" du serveur distant en ajoutant "bare=true".
Sinon, il faut créer une nouvelle branche pour faire un "pull request".
Sinon, copier les fichiers locaux dans un autre dossier (parent), et recloner avant de les replacer.

## fatal: index-pack failed

git pull n'a pas été lancé depuis le répertoire du dépôt.

## fatal: remote origin already exists

Pour redéfinir origin il faut le supprimer d'abord :

## fatal: This operation must be run in a work tree

Lors d'un git add sur un dépôt initialisé avec -- bare, il faut soit uniquement lui soumettre ses modifications (sans possibilité de le cloner, avec git remote add origin), soit définir un répertoire de branche avec --work-tree.

## fatal: unable to access 'https://MonServeur/MonDepotEnLigne.git/': SSL certificate problem: self signed certificate

Lors du clonage, remplacer HTTPS par HTTP, ou bien désactiver la vérification du certificat SSL :

## File mode changed from 100644 to 100755

Si certains fichiers apparaissent dans les diff car leurs métadonnées ont été modifiées (et pas leur contenu), c'est qu'une application a changé leurs inodes. Pour éviter cela :

## Please, commit your changes or stash them before you can merge

Précéder le pull d'un stash :

## This file is empty

Si un fichier apparait comme modifié, mais que son diff affiche ce message, c'est que seules ses métadonnées ont changé (ex : date de mise à jour).

## You must edit all merge conflicts and then mark them as resolved using git add

Survient lors d'un :
non précédé d'un :
Bien sûr les fichiers en conflit doivent faire partie de cet ajout.

## you need to resolve your current index first

Cela sert aussi à annuler un merge demandé par "git stash pop".

## Your branch is behind 'xxx' by y commits, and can be fast-forwarded

Dans ce cas il peut être préférable d'effacer la veille branche du serveur pour ne garder que la locale, qui sera synchronisée sur le serveur ensuite.

## Références

* ↑ Ex : https://github.com/mon_repo/settings/access
* ↑ https://medium.com/uncaught-exception/setting-up-multiple-gitlab-accounts-82b70e88c437
* ↑ https://git-scm.com/book/fr/v1/Git-sur-le-serveur-Mise-en-place-du-serveur

# Ressources externes
## Guides pour démarrer

* « Gérez vos codes source avec Git » sur Open Classroom
* git immersion
* Le git tutorial officiel

## Documentations

* La documentation officielle
* Le livre Pro Git
* Git Magic montre énormément de choses inattendues que l'on peut faire avec git
* Une documentation proposée sur le site d'Atlassian qui est en français et qui propose notamment une partie consacrée au différents workflows Git
* Beaucoup d'astuces dans la page consacrée à Git du wiki de kernel.org

## Aide-mémoires

Il n'est pas évident de se souvenir des toutes les commandes git. Aussi, il peut vous être utile d'avoir, sous la main, un aide-mémoire dédié :
* une fiche réalisée par l'équipe GitHub (format 2 × A4)
* une référence rapide interactive, elle est organisée selon le niveau où on souhaite travailler (stash, index, remote...). Elle a l'avantage d'être disponible en français.

## Vidéos

* Les vidéos officielles

## Extensions git pour le développeur

* git-extras est une extension qui se propose d'ajouter des commandes à git pour faire quelques manipulation récurrentes.

## Outils de visualisation des dépôts git

Une liste d'outils qui peuvent représenter des alternatives intéressantes à gitweb qui est livré par défaut :
* gitolite
* gitblit
* gitbucket
* gogs
* kallithea
Certains projets ont pour objectif d'être des alternatives open-source à GitHub :
* gitlab
* gitorious
Enfin, gerrit est un outil spécialisé pour la revue de code.