Débogue tes humanités

# 0. Introduction

Lorsque vous travaillez seul ou en équipe, vous risquez toujours de perdre une partie, voire l’entièreté de votre travail. Cela devient particulièrement critique lorsque vous avez accumulé des mois, voire des années de travail et que l’échéance approche : les conséquences d’une mauvaise sauvegarde peuvent être désastreuses !

Heureusement, un système simple mais fort robuste vous permet d’enregistrer l’historique de vos modifications et d’en faire une archive distribuée à différents endroits. Ce système est d’ailleurs fort utile lors de travaux réalisés à plusieurs : Git.

# 1. Qu’est-ce que Git ? Trois principes

Git est un logiciel de gestion de versions décentralisé : il met en place un système distribué de contrôle de versions (Distributed version control system).

• Système distribué
• Versionnement
• Contrôle

# 1.1. Un système distribué

• Git permet de copier des fichiers de son ordinateur vers un serveur tiers.
• Git permet d’avoir plusieurs emplacements de sauvegarde facilement.
• Git permet produire différentes versions sans effacer son travail en cours !
• Git permet de travailler à plusieurs personnes sur un même dossier.

# 1.2. Versionnement

Prenons un dossier de travail collaboratif sur un article :

# dossier de travail
.
├── article-michel-coquilles-corrigees.txt
├── article-relu-2021-12-09-final-ok-okok.txt
├── article-v1-relu-alice-bob-13fev.txt
├── article-v1-relu-alice-bob-VRAI.txt
└── article-vfinal-jeanne.txt

Quel fichier est le bon ? Quels fichiers contiennent les relectures de qui ?

# 1.2. Versionnement

Git permt de suivre un projet dans son ensemble (et pas forcément un fichier en particulier).

Il y a plusieurs principes inhérents à une bonne gestion collective de fichiers informatiques :

• ne pas centraliser la sauvegarde (à votre avis, pourquoi ?)
• la possibilité pour chacun d’obtenir une copie de l’historique complet du projet
• le travail hors connexion
• la création de versions parallèles d’un projet (les branches ! nous y reviendrons).

# 1.3. Contrôle

Git est un système de fichiers adressables en fonction de leur contenu.

# 1.5 Utilisations

Git est utilisé pour toutes sortes de projets: recherche scientifique, mémoires et doctorats, développement collaboratif de logiciels, archives personnelles, rédaction de documents en tous genres, publication de données, etc.

Exemples de projets utilisant Git :

• Programmes informatiques : Hugo
• Documentation : pandoc
• Projets éditoriaux : Mosaïques romaines (catalogue de musée)
• Données ouvertes : NY Times, données migratoires sur les enfants traversant la frontière américaine sans l’accompagnement d’un adulte
• Des ressources pour gérer ses références bibliographiques, par un certain bibliothécaire
• Rédaction universitaire : mémoire de maîtrise

# 2. Installation

# 2.1 En ligne de commande

Vous pouvez installer Git depuis son site web.

# 2. Installation

# 2.2 Avec une interface graphique (GUI)

Si la ligne de commande n’est pas encore votre tasse de thé, ne craignez rien ! Il existe des interfaces graphiques qui vous permettent d’utiliser Git de manière visuelle.

L’organisation qui chapeaute Git recense plusieurs logiciels dans cette catégorie. (Attention, la plupart de ces logiciels ne sont que des interfaces qui nécessitent l’installation de Git séparément !)

# 3. Créer un projet en utilisant Git

1. Créez un nouveau dossier pour votre projet.
2. Ajoutez des fichiers.
3. Commencez à versionner avec Git !

# 3. Créer un projet en utilisant Git

# Quelques définitions

• dépôt : C’est un dossier, tout simplement. Les fichiers sont versionnés dans un historique commun.
• commit : Une «  photo  » des fichiers à un instant donné ; un enregistrement atomique des changements dans un dépôt.
• conflit : Un conflit peut arriver lorsque l’on tente de fusionner deux versions d’un même projet. Par exemple : Alice et Bob ont tous les deux modifié le titre de l’article – mais lequel est le bon ?
• clone : Copier un projet chez soi. (Sur certaines platformes, on parle aussi de fork : une divergence d’un projet, une copie qui va vivre sa propre vie, ou presque.)

Exemple d’un fil de commits :

# Exercice (en ligne de commande)

Dans un dossier mon-projet/ :

1. git init pour initialiser un dépôt Git dans ce dossier.
2. Créez un nouveau fichier nommé article.md.
3. git status – qu’est-ce que vous voyez ?
4. git add article.md – vous indexez votre nouveau fichier dans les modifications à venir !
5. git commit -m "le message d'enregistrement" – validez votre enregistrement.
6. git log (touche q pour sortir) – qu’est-ce que vous voyez ?

Hourra ! Nous avons l’historique de notre projet localement, sur notre ordinateur. Cependant, il serait plus pratique d’ajouter une synchronisation externe.

# 4. Les plateformes d’hébergement Git (GitHub / GitLab / FramaGit / …)

Les plateformes comme GitHub ou GitLab sont des services en ligne qui permettent d’héberger vos projets versionnés avec le protocole Git.

Avec Git, vous pouvez facilement passer d’un fournisseur à l’autre, et même en utiliser plusieurs à la fois !

Nous commencerons avec GitHub, qui est un service populaire et gratuit.

Exemple de page d’accueil d’un dépôt Git, sur la plateforme GitHub :

# 4. Les plateformes d’hébergement Git (GitHub / GitLab / FramaGit / …)

# 4.1 Commencer avec GitHub

1. Créez un compte sur GitHub.com
2. Créez un dépôt nommé projet-debogue. N’initialisez pas le dépôt (décochez cette option).
3. Explorez l’interface : Qu’observez-vous de différent par rapport aux propriétés du logiciel Git ? Qu’est-ce qui est similaire ?
4. Copiez l’URL de clonage via le bouton Code.
5. Ajoutez une synchronisation, en ligne de commande ou via l’interface graphique.

• En ligne de commande : git remote add origin url-que-vous-avez-copié

… mais avant de pouvoir faire la synchronisation, il va falloir configurer Git sur votre poste !

# 5. Configurer Git

# 5.1. Configuration générale

Comme beaucoup d’outils, Git nécessite quelques réglages préalables ! Il est aussi possible de ajouter des configurations spécifiques pour un projet en particulier.

• De base : un nom et une adresse courriel
• Avancée : éditeur par défaut, branche par défaut
• Pour voir la configuration actuelle : git config --list
• Pour modifier la configuration globale depuis le terminal (recommandé la première fois) :
  git config --global user.name "Prénom Nom"
git config --global user.email "mon.addresse@umontreal.ca"

# 5. Configurer Git

# 5.2. Les clés SSH

• Secure Socket Shell
• Protocole de cryptage
• Pour faire interagir mon ordinateur (client) avec un serveur distant en sécurité
• Une clé publique (fichier avec le suffixe .pub, qui sera partagée) et une clé privée – celle-ci ne doit jamais quitter votre ordinateur !

Pour en savoir plus, lire la documentation fournie par GitHub.

# 5. Configurer Git

# 5.3. Générer une paire de clés SSH

• Pour générer une paire de clés avec l’algorithme ed25519 :

  ssh-keygen -t ed25519 -C "email@exemple.com"

• Pour générer une paire de clés avec l’algorithme RSA :

  ssh-keygen -t rsa -b 4096 -C "email@exemple.com"

• drapeau -t pour spécifier l’algorithme à utiliser
• drapeau -b pour spécifier la longer (bits) de la clé
• drapeau -C pour ajouter un commentaire

Pour en savoir plus, lire la documentation fournie par GitHub.

# 5. Configurer Git

# 5.4 Installer une clé SSH

Lorsque vous aurez généré votre paire de clés, il faudra ajouter votre clé publique (id_rsa.pub) à votre compte GitHub.

1. Sur GitHub, naviguez aux paramètres de votre compte (Settings).
2. Dans la section SSH keys, ajoutez une nouvelle clé SSH.
3. À l’écran de l’ajout d’une nouvelle clé, collez le contenu de votre clé publique (~/.ssh/id_rsa.pub) dans le champ Key.
4. Donnez un nom à cette clé (une clé est normalement associée à un ordinateur), par exemple Alice@portable-perso ou Bob@ordi-de-bureau.
5. Assurez-vous que la clé est de type Authentication Key.
6. Cliquez sur le bouton Add SSH Key.

Voilà ! Vous devriez maintenant avoir les droits d’accès depuis votre poste. Si vous avez trouvé cette étape complexe, n’ayez crainte : vous n’avez qu’à la faire la première fois !

# 6. Les commandes les plus usuelles

• git init : initialiser un dossier
• git status : voir l’état du projet
• git log : afficher l’historique de la branche actuelle
• git add : ajouter un fichier dans l’index avant de commiter
• git commit : déclarer des modifications
• git branch : créer une nouvelle branche
• git checkout : pour basculer sur une branche
• git push : envoyer les modifications sur un dépôt distant
• git fetch : récupérer les modifications d’un dépôt distant
• git pull : récupérer les modifications d’un dépôt distant et les fusionner avec le dépôt local

# 6.1. Quelques commandes avancées

• git merge – fusionner l’historique d’une branche sur une autre
• git rebase – harmoniser les historiques de deux branches (stratégie utile pour la fusion)
• git cherry-pick – récupérer une seule modification sur une autre branche
• git log – pour examiner l’historique des modifications

# Conclusion

Voilà ! Vous avez appris les rudiments de Git. Il ne vous reste plus qu’a l’employer dans vos propres projets.

Vous pouvez poursuivre la leçon pour des cas d’utilisation plus pointus (et tout à fait utiles !).

# 7. Conflits, merge, rebase, forks

• un conflit : il faut choisir
• forks : comment maintenir sa version à jour ?
• rebase : les bonnes pratiques difficiles à mettre en place

# 7. Conflits, merge, rebase, forks

# 7.1. Un conflit : choisir/arbitrer

• pour distinguer les portions : des signes typographiques sont utilisés
• certains éditeurs de texte facilitent la visualisation des conflits
• si le conflit n’est pas résolu : impossible de continuer

# 7. Conflits, merge, rebase, forks

# 7.2. Exercice : gestion d’un conflit

Suite à l’exercice 1, nous allons créer plusieurs modifications :

1. créer une nouvelle branche appelée modifs : git branch modifs et puis git checkout modifs
2. vous êtes désormais sur cette nouvelle branche
3. modifier le fichier, par exemple : echo "Autre texte hop là" >fichier-01.txt
4. enregistrer vos modifications dans Git : git commit -a -m "révision de la première ligne"

# 7. Conflits, merge, rebase, forks

# 7.3. Exercice pt 2 : gestion d’un conflit

5. retourner sur la branche principale : git checkout master (ou git checkout main selon votre configuration)
6. effectuer une nouvelle modification : echo "Ceci est mon texte" >fichier-01.txt
7. enregistrer vos modifications : git commit -a -m "réécriture"
8. tenter de fusionner les deux branches : git merge modifs

Vous devez avoir un conflit !

# 7. Conflits, merge, rebase, forks

# 7.4. Git merge

Source

# 7. Conflits, merge, rebase, forks

# 7.5. Git rebase

Source

# 7. Conflits, merge, rebase, forks

• git checkout -b modifs pour se positionner sur une nouvelle branche secondaire
• ajoutez et commitez deux fichiers sur cette branche
• git checkout master
• ajoutez et commitez un fichier sur cette branche
• git checkout modifs
• git rebase master : les commits dans la branche modifs sont positionnés à la suite des commits de la branche master
• git checkout master
• git rebase feature : les commits en plus dans ma branche modifs sont désormais ajoutez dans la branche master
  

# 7. Conflits, merge, rebase, forks

# 7.6. Forks : comment maintenir sa version à jour ?

1. Créer un Fork du projet sur votre compte GitHub.
2. Cloner le dépôt sur votre ordinateur (dans un autre dossier que le projet précédent).
3. Ajouter l’indication du fork en local : git remote add upstream git@gitlab.chemin-du/projet.
4. Pour récupérer les modifications du dépôt d’origine : git fetch upstream.
5. Pour synchroniser ces modifications avec votre dépôt : git rebase upstream/master.

# 7. Conflits, merge, rebase, forks

# 7.7. Rebase : les bonnes pratiques difficiles à mettre en place

Un tutoriel complexe à explorer si vous êtes motivé·e :

https://git-rebase.io

# Conclusion

Vous avez passé à travers une montagne d’information – ouf ! Ne soyez pas dur·e·s avec vous-mêmes : Git est un système complexe qui nécessite un apprentissage continu dans la durée. Même les experts ne connaissent généralement qu’une fraction de son fonctionnement.

Toutefois, tous peuvent l’utiliser, et nous espérons que vous saurez bénéficier de ce qu’il a à offrir.

Déb/u/o/gue tes humanités

CC BY-NC-SA Chaire de recherche du Canada sur les écritures numériques, Bibliothèque des lettres et des sciences humaines, Ouvroir d'histoire de l'art et de muséologie numérique. — giulia.ferretti@umontreal.ca ; louis-olivier.brassard@umontreal.ca