Un cadavre exquis pour découvrir Git

Les exercices suivants sont inspirés d’un cours de Git que j’ai participé à construire à l’Insee et dont les ressources sont disponibles ici. L’idée du cadavre exquis est inspirée de cette ressource et de celle-ci.

Cette partie part du principe que les concepts généraux de Git sont maîtrisés et qu’un environnement de travail fonctionnel avec Git est disponible. Un exemple de tel environnement est le JupyterLab ou l’environnement VSCode du SSPCloud où une extension Git est pré-installée :

Outre le chapitre précédent, il existe de nombreuses ressources sur internet sur le sujet, notamment une série de ressources construites pour l’Insee sur ce site et des ressources de la documentation collaborative sur R qu’est utilitR (des éléments sur la configuration et pratique sur RStudio). Toutes les ressources ne sont donc pas du Python car Git est un outil transversal qui doit servir quel que soit le langage de prédilection.

Git fait parti des pratiques collaboratives devenues standards dans le domaine de l’open-source mais également de plus en plus communes dans les administrations et entreprises de la data science.

Ce chapitre propose, pour simplifier l’apprentissage, d’utiliser l’ extension Git de JupyterLab ou de VSCode. Un tutoriel présentant l’extension JupyterLab est disponible ici. VSCode propose probablement, à l’heure actuelle, l’ensemble le plus complet.

Certains passages de ce TD nécessitent d’utiliser la ligne de commande. Il est tout à fait possible de réaliser ce TD entièrement avec celle-ci. Cependant, pour une personne débutante en Git, l’utilisation d’une interface graphique peut constituer un élément important pour la compréhension et l’adoption de Git. Une fois à l’aise avec Git, on peut tout à fait se passer des interfaces graphiques pour les routines quotidiennes et ne les utiliser que pour certaines opérations où elles s’avèrent fort pratiques (notamment la comparaison de deux fichiers avant de devoir fusionner).

Configuration du compte Github

Rappels sur la notion de dépôt distant

Comme expliqué dans le chapitre précédent, il convient de distinguer le dépôt distant (remote) et la copie ou les copies locales (les clones) d’un dépôt. Le dépôt distant est généralement stocké sur une forge logicielle (Github ou Gitlab) et sert à centraliser la version collective d’un projet. Les copies locales sont des copies de travail.

Git est un système de contrôle de version asynchrone, c’est-à-dire qu’on n’interagit pas en continu avec le dépôt distant (comme c’est le cas dans le système SVN) mais qu’il est possible d’avoir une version locale qui se différencie du dépôt commun et qu’on rend cohérente de temps en temps.

Bien qu’il soit possible d’avoir une utilisation hors-ligne de Git, c’est-à-dire un pur contrôle de version local sans dépôt distant, cela est une utilisation rare et qui comporte un intérêt limité. L’intérêt de Git est d’offrir une manière robuste et efficace d’interagir avec un dépôt distant facilitant ainsi la collaboration en équipe ou en solitaire.

Pour ces exercices, il est proposé d’utiliser Github, la forge la plus visible. L’avantage de Github par rapport à son principal concurrent, Gitlab, est que le premier est plus visible, car mieux indexé par Google et concentre, en partie pour des raisons historiques, plus de développeurs Python et R (ce qui est important dans des domaines comme le code où les externalités de réseau jouent).

Première étape: créer un compte Github

Les deux premières étapes se font sur Github.

Exercice 1 : Créer un compte Github

1. Si vous n’en avez pas déjà un, créer un compte sur https://github.com
2. Créer un dépôt en suivant les consignes ci-dessous.

• Créez ce dépôt privé, cela permettra dans l’exercice 2 d’activer notre jeton. Vous pourrez le rendre public après l’exercice 2, c’est comme vous le souhaitez.
• Créer ce dépôt avec un README.md en cliquant sur la case Add a README file
• Ajouter un .gitignore en sélectionnant le modèle Python

Connexion sur https://github.com > + (en haut de la page) > New repository > Renseigner le “Repository name” > Cocher “private” > “Create repository”

Deuxième étape: créer un token (jeton) HTTPS

Principe

Git est un système décentralisé de contrôle de version : les codes sont modifiés par chaque personne sur son poste de travail, puis sont mis en conformité avec la version collective disponible sur le dépôt distant au moment où le contributeur le décide.

Il est donc nécessaire que la forge connaisse l’identité de chacun des contributeurs, afin de déterminer qui est l’auteur d’une modification apportée aux codes stockés dans le dépôt distant. Pour que Github reconnaisse un utilisateur proposant des modifications, il est nécessaire de s’authentifier (un dépôt distant, même public, ne peut pas être modifié par n’importe qui). L’authentification consiste ainsi à fournir un élément que seul vous et la forge êtes censés connaître : un mot de passe, une clé compliquée, un jeton d’accès…

Plus précisément, il existe deux modalités pour faire connaître son identité à Github :

• une authentification HTTPS (décrite ici) : l’authentification se fait avec un login et un mot de passe ou avec un token (un mot de passe compliqué généré automatiquement par Github et connu exclusivement du détenteur du compte Github) ;
• une authentification SSH : l’authentification se fait par une clé cryptée disponible sur le poste de travail et que GitHub ou GitLab connaît. Une fois configurée, cette méthode ne nécessite plus de faire connaître son identité : l’empreinte digitale que constitue la clé suffit à reconnaître un utilisateur.

La documentation collaborative utilitR présente les raisons pour lesquelles il convient de favoriser la méthode HTTPS sur la méthode SSH.

Note

Depuis Août 2021, Github n’autorise plus l’authentification par mot de passe lorsqu’on interagit (pull/push) avec un dépôt distant (raisons ici). Il est nécessaire d’utiliser un token (jeton d’accès) qui présente l’avantage d’être révoquable (on peut à tout moment supprimer un jeton si, par exemple, on suspecte qu’il a été diffusé par erreur) et à droits limités (le jeton permet certaines opérations standards mais n’autorise pas certaines opérations déterminantes comme la suppression d’un dépôt).

À partir de mars 2023 et jusqu’à la fin de 2023, GitHub commencera progressivement à exiger que tous les utilisateurs de GitHub activent une ou plusieurs formes d’authentification à deux facteurs (2FA). Pour plus d’informations sur le déploiement de l’inscription 2FA, consultez cet article de blog. Concrètement, cela signifie que vous devrez au choix :

• Renseigner votre numéro de portable pour valider certaines connexions grâce à un code que vous recevrez par sms ;
• Installer une application d’authentification (Ex : Microsoft Authenticator) installée sur votre téléphone qui génèrera un QR code que vous pourrez scanner depuis github, ce qui ne nécessite pas que vous ayez à fournir votre numéro de téléphone
• Utiliser une clef USB de sécurité

Pour choisir entre ces différentes options, vous pouvez vous rendre sur Settings > Password and authentication > Enable two-factor authentication.

Note

Il est important de ne jamais stocker un token, et encore moins son mot de passe, dans un projet. Il est possible de stocker un mot de passe ou token de manière sécurisée et durable avec le credential helper de Git. Celui-ci est présenté par la suite.

S’il n’est pas possible d’utiliser le credential helper de Git, un mot de passe ou token peut être stocké de manière sécurisé dans un système de gestion de mot de passe comme Keepass.

Ne jamais stocker un jeton Github, ou pire un mot de passe, dans un fichier texte non crypté. Les logiciels de gestion de mot de passe (comme Keepass, recommandé par l’Anssi) sont simples d’usage et permettent de ne conserver sur l’ordinateur qu’une version hashée du mot de passe qui ne peut être décryptée qu’avec un mot de passe connu de vous seuls.

Créer un jeton

La documentation officielle comporte un certain nombre de captures d’écran expliquant comment procéder.

Nous allons utiliser le credential helper associé à Git pour stocker ce jeton. Ce credential helper permet de conserver de manière pérenne un jeton (on peut aussi faire en sorte que le mot de passe soit automatiquement supprimé de la mémoire de l’ordinateur au bout, par exemple, d’une heure).

L’inconvénient de cette méthode est que Git écrit en clair le jeton dans un fichier de configuration. C’est pour cette raison qu’on utilise des jetons puisque, si ces derniers sont révélés, on peut toujours les révoquer et éviter les problèmes (pour ne pas stocker en clair un jeton il faudrait utiliser une librairie supplémentaire comme libsecrets qui est au-delà du programme de ce cours).

Si vous désirez conserver de manière plus durable ou plus sécurisée votre jeton (en ne conservant pas le jeton en clair mais de manière hashée), est d’utiliser un gestionnaire de mot de passe comme Keepass (recommandé par l’Anssi). Néanmoins, il est recommandé de tout de même fixer une date d’expéritation aux jetons pour limiter les risques de sécurité d’un token qui fuite sans s’en rendre compte.

Exercice 2.0 : Créer un service sur le SSPCloud

En amont de l’exercice 2, pour les utilisateurs du SSPCloud, il est recommandé d’ouvrir un service Jupyter en suivant les consignes suivantes :

• Dans la page Mes services, cliquer sur le bouton Nouveau service ;
• Choisir Jupyter-Python ;
• Cliquer sur Configuration Jupyter-Python. ⚠️ ne pas lancer le service tout de suite !
• Faire défiler les onglets pour arriver sur l’onglet Git ;
• Remplacer la valeur sous Cache par un nombre important, par exemple 36000 pour que le jeton que vous utiliserez soit valable 10 heures ;
• Lancer le service.

Exercice 2 : Créer et stocker un token

1️⃣ Suivre la documentation officielle en ne donnant que les droits repo au jeton (ajouter les droits workflow si vous désirez que votre jeton soit utilisable pour des projets où l’intégration continue est nécessaire).

Pour résumer les étapes devraient être les suivantes :

Settings > Developers Settings > Personal Access Token > Generate a new token > “My bash script” > Expiration “30 days” > cocher juste “repo” > Generate token > Le copier

2️⃣ Ouvrir un terminal depuis Jupyter (par exemple File > New > Terminal) ou VSCode (Terminal > New Terminal).

3️⃣ [Optionnel] Taper dans le terminal la commande qui convient selon votre système d’exploitation pour activer le credential helper:

# Sous mac et linux et le datalab
git config --global credential.helper store

# Sous windows
git config --global credential.helper manager-core

4️⃣ Récupérer, sur la page d’accueil de votre dépôt, l’url du dépôt distant. Il prend la forme suivante

https://github.com/<username>/<reponame>.git

Vous pouvez utiliser l’icone à droite pour copier l’url.

5️⃣ Retournez dans le Terminal. Taper

git clone repo_url

où repo_url est l’url du dépôt en question (vous pouvez utiliser MAJ+Inser pour coller l’url précédemment copié)

Tapez Entrée. Dans le cas d’un répertoire privé et sans credential helper, renseignez ensuite votre identifiant, faites Entrée, puis votre personal access token, Entrée. Si vous n’avez pas d’erreur, cela signifie que l’authentification a bien fonctionné et donc que tout va bien. Sinon, il vous suffit de réécrire l’instruction git clone et de retenter de taper votre personal access token. Normalement, si vous avez créé un dépôt vide dans l’exercice 1, vous avez un message de Git:

warning: You appear to have cloned an empty repository.

Ce n’est pas une erreur mais il est préférable de suivre la consigne de l’exercice 1 et de créer un projet non vide. Le dossier de votre projet a bien été créé.

Si vous avez une erreur, suivez la consigne présentée ci-après pour réinitialiser votre credential helper

6️⃣ Si vous le désirez, vous pouvez changer la visibilité de votre dépôt en le rendant public.

7️⃣ Stocker le token sur le SSP Cloud (ou un gestionnaire de mot de passe) :

Mon Compte -> Services externes -> Jeton d’accès personnel GitHub

Note

Si vous avez fait une faute de frappe dans le mot de passe ou dans le jeton, il est possible de vider la mémoire de la manière suivante, sous Mac ou Linux :

git config --global --unset credential.helper

Sous Windows, si vous avez utilisé l’option manager-core évoquée ci-dessus, vous pouvez utiliser une interface graphique pour effacer le mot de passe ou jeton erroné. Pour cela, dans le menu démarrer, taper Gestionnaire d'identification (ou Credential Manager si Windows ne trouve pas). Dans l’interface graphique qui s’ouvre, il est possible de supprimer le mot de passe ou jeton en question. Après cela, vous devriez à nouveau avoir l’opportunité de taper un mot de passe ou jeton lors d’une authentification HTTPS.

Premier commit

A ce stade, nous avons configuré Git pour être en mesure de s’authentifier automatiquement et nous avons cloné le dépôt pour avoir une copie locale de travail.

On n’a encore ajouté aucun fichier à Git en supplément de ceux créés en même temps que le dépôt. Nous allons créer ces premiers fichiers

Exercice 3 : Indexer des modifications

1. Créer un dossier 📁 scripts depuis l’interface de Jupyter
2. Y créer les fichiers script1.py et script2.py, chacun contenant quelques commandes Python de votre choix (le contenu de ces fichiers n’est pas important).

Sur la session Jupyter d’Onyxia, si le Clic Droit > rename ne fonctionne pas, vous pouvez faire : File > New > Text file après vous être assurés que vous vous situez bien dans le dossier de l’arborescence. Un fichier untitled.txt se crée. Vous pouvez le renommer, en n’oubliant pas de changer l’extension en .py.

3. Se rendre dans l’extension Git de Jupyter ou de VSCode. Vous devriez retrouver un cadre ayant cet aspect (à gauche pour Jupyter et à droite pour VSCode).

Figure 2.1: Interface graphique Git sous Jupyter (à gauche) et VSCode (à droite)

En ligne de commande, c’est l’équivalent de

git status

2. Sur Jupyter, en passant votre souris au dessus du nom des fichiers script1.py et script2.py, vous devriez voir un + apparaître. Cliquez dessus. Sur VSCode, un bouton + figure à droite du nom du fichier .script1.py et .script2.py.

Si vous aviez privilégié la ligne de commande, ce que vous avez fait est équivalent à :

git add scripts/script1.py
git add scripts/script2.py

Pour se remémorer ce que signifie git add, vous pouvez vous rendre sur ce cours dédié à Git.

3. Observer le changement de statut du fichier après avoir cliqué sur +. Il est désormais dans la partie Staged En gros, vous venez de dire à Git que vous allez rendre publique une évolution du fichier, mais vous ne l’avez pas encore fait (Staged est une liste d’attente).

Si vous étiez en ligne de commande vous auriez ce résultat après un git status

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   .gitignore

Les nouvelles modifications (en l’occurrence la création du fichier et la validation de son contenu actuel) ne sont pas encore archivées. Pour cela, il va falloir faire un commit (on rend publique une modification)

4. Avant cela, regardons les modifications qu’on va prochainement valider. Pour cela, passez la souris au dessus du nom du fichier .gitignore et cliquer sur le bouton Diff this file (+ -). Une page s’ouvre et met en regard la version antérieure avec les ajouts en vert et les suppressions en rouge. Nous retrouverons cette visualisation avec l’interface Github, plus tard.

En l’occurrence, comme le fichier n’existait pas, normalement nous n’avons que des ajouts.

Il est également possible d’effectuer cela avec la ligne de commande mais c’est beaucoup moins pratique. Pour cela, la commande à appeler est git diff et il est nécessaire d’utiliser l’option cached pour lui dire d’inspecter les fichiers pour lesquels on n’a pas encore effectué de commit. En vert apparaîtront les modifications et en rouge les suppressions mais, cette fois, les résultats ne seront pas mis côte-à-côte ce qui est beaucoup moins pratique.

git diff --cached

Il est temps de valider notre modification. Cette opération s’appelle commit en langage Git et, comme son nom l’indique, il s’agit d’une proposition de modification sur laquelle, en quelques sortes, on s’engage.

Un commit comporte un titre et éventuellement une description. A ces informations, Git ajoutera automatiquement quelques éléments supplémentaires, notamment l’auteur du commit (pour identifier la personne ayant proposé cette modification) et l’horodatage (pour identifier le moment où cette modification a été proposée). Ces informations permettront d’identifier de manière unique le commit auquel sera ajouté un identifiant aléatoire unique (un numéro SHA) qui permettra de faire référence à celui-ci sans ambiguïté.

Le titre est important car il s’agit, pour un humain, du point d’entrée dans l’histoire d’un dépôt (voir par exemple l’histoire du dépôt du cours. Les titres vagues (Mise à jour du fichier, Update…) sont à bannir car ils nécessiteront un effort inutile pour comprendre les fichiers modifiés.

N’oubliez pas que votre premier collaborateur est votre moi futur qui, dans quelques semaines, ne se souviendra pas en quoi consistait le commit Update du 12 janvier et en quoi il se distingue du Update du 13 mars.

Exercice 4 : Premier commit (enfin !)

Sur Jupyter, tout se passe dans la partie inférieure de l’interface graphique.

Sur VSCode, il faut au contraire regarder en haut.

1️⃣ Entrer le titre Initial commit et ajouter une description Création des premiers fichiers 🎉. Sur VSCode, le titre du commit correspond à la première ligne du message de commit, les lignes suivantes correspondent à la description.

Le fait de nommer le premier commit “Initial commit” est une habitude, vous n’êtes pas obligé de suivre cette convention si elle ne vous plaît pas.

2️⃣ Cliquer sur Commit. Le fichier a disparu de la liste, c’est normal, il n’a plus de modification à valider. Pour le retrouver dans la liste des fichiers Changed, il faudra le modifier à nouveau

3️⃣ Sur Jupyter, cliquer sur l’onglet History ou sur VSCode cliquer sur l’icône View Git Graph. Votre commit apparaît à ce niveau. Si vous cliquez dessus, vous obtenez des informations sur le commit.

❓ Question : à ce stade, le dépôt du projet sur GitHub (remote) a-t-il été modifié ?

Note

Si vous utilisiez la ligne de commande, la manière équivalente de faire serait

git commit -m "Initial commit" -m "Création des premiers fichiers 🎉"

L’option m permet de créer un message, qui sera disponible à l’ensemble des contributeurs du projet. Avec la ligne de commande, ce n’est pas toujours très pratique. Les interfaces graphiques permettent des messages plus développés (la bonne pratique veut qu’on écrive un message de commit comme un mail succinct : un titre et un peu d’explications, si besoin).

Le fichier .gitignore

Lorsqu’on utilise Git, il y a des fichiers qu’on ne veut pas partager ou dont on ne veut pas suivre les modifications (typiquement les grosses bases de données).

C’est le fichier .gitignore qui gère les fichiers exclus du contrôle de version. Lors de la création du projet sur GitHub, nous avons demandé la création d’un fichier .gitignore, qui se situe à la racine du projet. Il spécifie l’ensemble des fichiers qui seront toujours exclus de l’indexation faite par Git.

Exercice 5 : Le fichier .gitignore

1️⃣ Par défaut, le fichier .gitignore n’est pas affiché car les fichiers .* sont des fichiers de configuration. Il faut activer une option pour l’afficher. Tout en haut de Jupyter, cliquer sur View -> Show Hidden Files

2️⃣ Ouvrir ce fichier maintenant qu’il s’affiche et observer quelques règles écrites dedans

3️⃣ Créer un dossier data à la racine du projet et créer à l’intérieur de celui-ci un fichier data/raw.csv avec une ligne de données quelconque

4️⃣ Ajouter au .gitignore le dossier data/

5️⃣ Vérifier que toutes les règles ajoutées précédemment fonctionnent comme attendu

❓ Question : que se passe-t-il lorsque l’on ajoute au .gitignore des fichiers qui ont déjà été commit sur le projet Git ?

Premières interactions avec Github depuis sa copie de travail

Jusqu’à présent, après avoir cloné le dépôt, on a travaillé uniquement sur notre copie locale. On n’a pas cherché à interagir à nouveau avec Github.

Cependant, il existe bien une connexion entre notre dossier local et le dépôt Github. Si on utilise la ligne de commande, on peut s’en assurer en tapant dans un terminal

git remote -v

Le dépôt distant s’appelle remote en langage Git. L’option -v (verbose) permet de lister le(s) dépôt(s) distant(s). Le résultat devrait avoir la structure suivante :

origin  https://github.com/<username>/<projectname>.git (fetch)
origin  https://github.com/<username>/<projectname>.git (push)

Plusieurs informations sont intéressantes dans ce résultat. D’abord on retrouve bien l’url qu’on avait renseigné à Git lors de l’opération de clonage. Ensuite, on remarque un terme origin. C’est un alias pour l’url qui suit. Cela évite d’avoir, à chaque fois, à taper l’ensemble de l’url, ce qui peut être pénible et source d’erreur.

fetch et push sont là pour nous indiquer qu’on récupère (fetch) des modifications d’origin mais qu’on envoie également (push) des modifications vers celui-ci. Généralement, les url de ces deux dépôts sont les mêmes mais cela peut arriver, lorsqu’on contribue à des projets opensource qu’on n’a pas créé, qu’ils diffèrent¹.

Envoyer des modifications sur le dépôt distant: push

Exercice 6 : Interagir avec Github

Il convient maintenant d’envoyer les fichiers sur le dépôt distant.

1️⃣ L’objectif est d’envoyer vos modifications vers origin. On va passer par la ligne de commande car les boutons push/pull de l’extension Jupyter ne fonctionnent pas de manière systématique.

Taper

git push origin main

Cela signifie: “git envoie (push) mes modifications sur la branche main (la branche sur laquelle on a travaillé, on reviendra dessus) vers mon dépôt (alias origin)”

Remarque : Si vous obtenez l’erreur suivante error: src refspec hello does not match any, c’est probablement que vous avez indiqué le mauvais nom de branche. La confusion se fait souvent entre le nom main ou master (ancienne norme de branche par défaut).

Normalement, si vous avez utilisé le credential helper, Git ne vous demande pas vos identifiants de connexion. Sinon, il faut taper votre identifiant Github et votre mot de passe correspond au personal access token nouvellement créé !

2️⃣ Retournez voir le dépôt sur Github, vous devriez maintenant voir le fichier .gitignore s’afficher en page d’accueil.

La fonctionnalité pull

La deuxième manière d’interagir avec le dépôt est de récupérer des résultats disponibles en ligne sur sa copie de travail. On appelle cela pull.

Pour le moment, vous êtes tout seul sur le dépôt. Il n’y a donc pas de partenaire pour modifier un fichier dans le dépôt distant. On va simuler ce cas en utilisant l’interface graphique de Github pour modifier des fichiers. On rapatriera les résultats en local dans un deuxième temps.

Exercice 7 : Rapatrier des modifs en local

1️⃣ Se rendre sur votre dépôt depuis l’interface https://github.com

• Se placer sur le fichier README.md et cliquer sur le bouton Edit this file, qui prend la forme d’un icône de crayon.

2️⃣ L’objectif est de donner au README.md un titre en ajoutant, au début du document, la ligne suivante :

# Mon oeuvre d'art surréaliste 

Sautez une ligne et entrez le texte que vous désirez, sans ponctuation. Par exemple,

le chêne un jour dit au roseau

3️⃣ Cliquez sur l’onglet Preview pour voir le texte mis en forme au format Markdown

4️⃣ Rédiger un titre et un message complémentaire pour faire le commit. Conserver l’option par défaut Commit directly to the main branch

5️⃣ Editer à nouveau le README en cliquant sur le crayon juste au dessus de l’affichage du contenu du README.

Ajouter une deuxième phrase et corrigez la ponctuation de la première. Ecrire un message de commit et valider.

Le Chêne un jour dit au roseau :
Vous avez bien sujet d'accuser la Nature

6️⃣ Au dessus de l’aborescence des fichiers, vous devriez voir s’afficher le titre du dernier commit. Vous pouvez cliquer dessus pour voir la modification que vous avez faite.

7️⃣ Les résultats sont sur le dépôt distant mais ne sont pas sur votre dossier de travail dans Jupyter ou VSCode. Il faut re-synchroniser votre copie locale avec le dépôt distant :

• Sur VSCode, cliquez simplement sur ... > Pull à côté du bouton qui permet de visualiser le graphe Git.
• Avec l’interface Jupyter, si cela est possible, appuyez tout simplement sur la petite flèche vers le bas, qui est celle qui a désormais la pastille orange.
• Si cette flèche n’est pas disponible ou si vous travaillez dans un autre environnement, vous pouvez utiliser la ligne de commande et taper

git pull origin main

Cela signifie : “git récupère (pull) les modifications sur la branche main vers mon dépôt (alias origin)”

8️⃣ Regarder à nouveau l’historique des commits. Cliquez sur le dernier commit et affichez les changements sur le fichier. Vous pouvez remarquer la finesse du contrôle de version : Git détecte au sein de la première ligne de votre texte que vous avez mis des majuscules ou de la ponctuation.

L’opération pull permet :

1. A votre système local de vérifier les modifications sur le dépôt distant que vous n’auriez pas faites (cette opération s’appelle fetch)
2. De les fusionner s’il n’y a pas de conflit de version ou si les conflits de version sont automatiquement fusionnables (deux modifications d’un fichier mais qui ne portent pas sur le même emplacement).

Même tout seul, ne pas se limiter à main

Au début d’une tâche particulière ou d’un projet, il est recommandé d’ouvrir des issues. Prenant la forme d’un espace de discussion, elles correpondront à la fin à des nouvelles fonctionnalités (en anglais, features). Les issues permettent également de signaler des bugs constatés, de se les répartir et d’indiquer s’ils sont réglés ou s’ils ont avancés. Une utilisation intensive des issues, avec des labels adéquats, peut même amener à se passer d’outils de gestion de projets comme Trello.

La branche main est la branche principale. Elle se doit d’être “propre”. Si on veut être rigoureux, on ne pousse pas des travaux non aboutis sur main.

Il est possible de pousser directement sur main dans le cas de petites corrections, de modifications mineures dont vous êtes certains qu’elles vont fonctionner. Mais sachez que dans le cadre de projets sensibles, c’est strictement interdit. N’ayez pas peur de fixer comme règle l’interdiction de pousser sur main, cela obligera l’équipe projet à travailler professionnellement.

Au moindre doute, créez une branche. Les branches sont utilisées pour des travaux significatifs :

• vous travaillez seul sur une tâche qui va vous prendre plusieurs heures ou jours de travail (vous ne devez pas pousser sur main des travaux non aboutis);
• vous travaillez sur une fonctionnalité nouvelle et vous souhaiterez recueillir l’avis de vos collaborateurs avant de modifier main;
• vous n’êtes pas certain de réussir vos modifications du premier coup et préférez faire des tests en parallèle.

Warning

Les branches ne sont pas personnelles : Toutes les branches sont publiées, le rebase est interdit. Le push force est également interdit.

Il faut absolument bannir les usages de push force qui peuvent déstabiliser les copies locales des collaborateurs. S’il est nécessaire de faire un push force, c’est qu’il y a un problème dans la branche, à identifier et régler sans faire push force.

Tous les merges dans main doivent se faire par l’intermédiaire d’une pull request dans Github. En effet, il est très déconseillé de merger une branche dans main localement.

Exercice 8: Créer une nouvelle branche et l'intégrer dans main

1️⃣ Ouvrir une issue sur Github. Signaler qu’il serait bien d’ajouter un emoji chat dans le README. Dans la partie de droite, cliquer sur la petite roue à côté de Label et cliquer sur Edit Labels. Créer un label Markdown. Normalement, le label a été ajouté.

2️⃣ Retournez sur votre dépôt local. Vous allez créer une branche nommée issue-1

Avec l’interface graphique de JupyterLab, cliquez sur Current Branch - Main puis sur le bouton New Branch. Rentrez issue-1 comme nom de branche (la branche doit être créée depuis main, ce qui est normalement le choix par défaut) et cliquez sur Create Branch.

Sur VSCode, cliquez sur ... > Branch > Create Branch et entrez le nom issue-1.

Si vous n’utilisez pas l’interface graphique mais la ligne de commande, la manière équivalente de faire est²

git checkout -b issue-1

3️⃣ Ouvrez README.md et ajoutez un emoji chat (:cat:) à la suite du titre. Faites un commit en refaisant les étapes vues dans les exercices précédents. N’oubliez pas, cela se fait en deux étapes:

1. Ajoute les modifications à l’index en déplacant le fichier README dans la partie Staged
2. Validation des modifications avec un commit

Si vous passez par la ligne de commande, cela donnera :

git add .
git commit -m "ajout emoji chat"

4️⃣ Faire un deuxième commit pour ajouter un emoji koala (:koala:) puis pousser les modifications locales.

Cela peut être fait avec l’interface de JupyterLab grâce au bouton avec une flêche montante (il doit apparaître en orange maintenant). Sur VSCode, cliquez sur le bouton Publish Branch.

Sinon, si vous utilisez la ligne de commande, vous devrez taper

git push origin issue-1

5️⃣ Dans Github, devrait apparaître

issue-1 had recent pushes XX minutes ago.

Cliquer sur Compare & Pull Request. Donner un titre informatif à votre pull request Dans le message en dessous, taper

- close #1

Le tiret est une petite astuce pour que Github remplace le numéro de l’issue par le titre.

Cliquez sur Create Pull Request mais ne validez pas la fusion, on le fera dans un second temps.

Le fait d’avoir mis un message close suivi d’un numéro d’issue #1 permettra de fermer automatiquement l’issue 1 lorsque vous ferez le merge. En attendant, vous avez créé un lien entre l’issue et la pull request

Au passage, vous pouvez ajouter le label Markdown sur la droite.

6️⃣ En local, retourner sur main. Dans l’interface Jupyter, il suffit de cliquer sur main dans la liste des branches. Sur VSCode, la liste des branches apparaît en cliquant sur le nom de la branche actuelle (issue-1 en théorie à ce stade). Si vous êtes en ligne de commande, il faut faire

git checkout main

checkout est une commande Git qui permet de naviguer d’une branche à l’autre (voire d’un commit à l’autre).

Ajouter une phrase à la suite de votre texte dans le README.md (ne touchez pas au titre !). Vous pouvez remarquer que les emojis ne sont pas dans le titre, c’est normal vous n’avez pas encore fusionné les versions

7️⃣ Faire un commit et un push. En ligne de commande, cela donne

git add .
git commit -m "ajoute un troisième vers"
git push origin main

8️⃣ Sur Github, cliquer sur Insights en haut du dépôt puis, à gauche sur Network (cela n’est possible que si vous avez rendu public votre dépôt).

Vous devriez voir apparaître l’arborescence de votre dépôt. On peut voir issue-1 comme une ramification et main comme le tronc.

L’objectif est maintenant de ramener les modifications faites dans issue-1 dans la branche principale. Retournez dans l’onglet Pull Requests. Là, changer le type de merge pour Squash and Merge, comme ci-dessous (petit conseil : choisissez toujours cette méthode de merge).

Une fois que cela est fait, vous pouvez retourner dans Insights puis Network pour vérifier que tout s’est bien passé comme prévu.

9️⃣ Supprimer la branche (branch > delete this branch). Puisqu’elle est mergée, elle ne servira plus. La conserver risque d’amener à des push involontaires dessus.

L’option de fusion Squash and Merge permet de regrouper tous les commits d’une branche (potentiellement très nombreux) en un seul dans la branche de destination. Cela évite, sur les gros projets, des branches avec des milliers de commits.

Je recommande de toujours utiliser cette technique et non les autres. Pour désactiver les autres techniques, vous pouvez aller dans Settings et dans la partie Merge button ne conserver cochée que la méthode Allow squash merging

Un cadavre exquis pour découvrir le travail collaboratif

Jusqu’à présent, nous avons découvert les vertus de Git dans un projet individuel. Nous allons maintenant aller plus loin dans un projet collectif.

Le workflow adopté

Nous allons adopter le mode de travail le plus simple, le Github Flow. Il correspond à cette forme caractéristique d’arbre:

1. La branche main constitue le tronc
2. Les branches partent de main et divergent
3. Lorsque les modifications aboutissent, elles sont intégrées à main ; la branche en question disparaît :

Il existe des workflows plus complexes, notamment le Git Flow que j’utilise pour développer ce cours. Ce tutoriel, très bien fait, illustre avec un graphique la complexité accrue de ce flow :

Cette fois, une branche intermédiaire, par exemple une branche development intègre des modifications à tester avant de les intégrer dans la version officielle (main).

Hint

Vous pourrez trouvez des dizaines d’articles et d’ouvrages sur ce sujet dont chacun prétend avoir trouvé la meilleure organisation du travail (Git flow, GitHub flow, GitLab flow…). Ne lisez pas trop ces livres et articles sinon vous serez perdus (un peu comme avec les magazines destinés aux jeunes parents…).

La méthode de travail la plus simple est le Github flow qu’on vous a proposé d’adopter. L’arborescence est reconnaissable : des branches divergent et reviennent systématiquement vers main.

Pour des projets plus complexes dans des équipes développant des applications, on pourra utiliser d’autres méthodes de travail, notamment le Git flow. Il n’existe pas de règles universelles pour déterminer la méthode de travail ; l’important c’est, avant tout, de se mettre d’accord sur des règles communes de travail avec votre équipe.

Méthode pour les merges

Les merges vers main doivent impérativement passer par Github (ou Gitlab). Cela permet de garder une trace explicite de ceux-ci (par exemple ici), sans avoir à chercher dans l’arborescence, parfois complexe, d’un projet.

La bonne pratique veut qu’on fasse un squash commit pour éviter une inflation du nombre de commits dans main: les branches ont vocation à proposer une multitude de petits commits, les modifications dans main doivent être simples à tracer d’où le fait de modifier des petits bouts de code.

Comme on l’a fait dans un exercice précédent, il est très pratique d’ajouter dans le corps du message close #xx où xx est le numéro d’une issue associée à la pull request. Lorsque la pull request sera fusionnée, l’issue sera automatiquement fermée et un lien sera créé entre l’issue et la pull request. Cela vous permettra de comprendre, plusieurs mois ou années plus tard comment et pourquoi telle ou telle fonctionnalité a été implémentée.

En revanche, l’intégration des dernières modifications de main vers une branche se fait en local. Si votre branche est en conflit, le conflit doit être résolu dans la branche et pas dans main. main doit toujours rester propre.

Mise en pratique

Exercice 9 : Interactions avec le dépôt distant

Cet exercice se fait par groupe de trois ou quatre. Il y aura deux rôles dans ce scénario :

• Une personne aura la responsabilité d’être mainteneur
• Deux à trois personnes seront développeurs.

1️⃣ Le mainteneur crée un dépôt sur Github. Il/Elle donne des droits au(x) développeur(s) du projet (Settings > Manage Access > Invite a collaborator).

2️⃣ Chaque membre du projet, crée une copie locale du projet grâce à la commande git clone ou avec le bouton Clone a repository de JupyterLab.

Pour cela, récupérer l’url HTTPS du dépôt en copiant l’url du dépôt que vous pouvez trouver, par exemple, dans la page d’accueil du dépôt, en dessous de Quick setup — if you’ve done this kind of thing before

En ligne de commande, cela donnera :

git clone https://github.com/<username>/<reponame>.git

3️⃣ Chaque membre du projet crée un fichier avec son nom et son prénom, selon cette structure nom-prenom.md en évitant les caractères spéciaux. Il écrit dedans trois phrases de son choix sans ponctuation ni majuscules (pour pouvoir effectuer une correction ultérieurement). Enfin, il commit sur le projet.

Pour rappel, en ligne de commande cela donnera les commandes suivantes à modifier

git add nom-prenom.md
git commit -m "C'est l'histoire de XXXXX"

4️⃣ Chacun essaie d’envoyer (push) ses modifications locales sur le dépôt:

git push origin main

5️⃣ A ce stade, une seule personne (la plus rapide) devrait ne pas avoir rencontré de rejet du push. C’est normal, avant d’accepter une modification Git vérifie en premier lieu la cohérence de la branche avec le dépôt distant. Le premier ayant fait un push a modifié le dépôt commun ; les autres doivent intégrer ces modifications dans leur version locale (pull) avant d’avoir le droit de proposer un changement.

Pour celui/celle/ceux dont le push a été refusé, faire

git pull origin main

pour ramener les modifications distantes en local.

6️⃣ Taper git log et regarder la manière dont a été intégré la modification de votre camarade ayant pu faire son push

Vous remarquerez que les commits de vos camarades sont intégrés tels quels à l’histoire du dépôt.

7️⃣ Faire à nouveau

git pull origin main

Le dernier doit refaire, à nouveau, les étapes 5 à 7 (dans une équipe de quatre il faudra encore le refaire une fois).

Warning à nouveau: ne JAMAIS FAIRE git push force

Quand on fait face à un rejet du push, on est tenté de faire passer en force le push malgré la mise en garde précédente.

Il faut immédiatement oublier cette solution, elle crée de nombreux problèmes et, en fait, ne résout rien. L’un des risques est de réécrire entièrement l’historique rendant les copies locales, et donc les modifications de vos collaborateurs, caduques. Cela vous vaudra, à raison, des remontrances de vos partenaires qui perdent le bénéfice de leur historique Git qui, s’ils ont des versions sans push depuis longtemps peuvent avoir diverger fortement du dépôt maître.

Exercice 10 : Gérer les conflits quand on travaille sur le même fichier

Dans la continuité de l’exercice précédent, chaque personne va travailler sur les fichiers des autres membres de l’équipe.

1️⃣ Les deux ou trois développeurs ajoutent la ponctuation et les majuscules du fichier du premier développeur.

2️⃣ Ils sautent une ligne et ajoutent une phrase (pas tous la même).

3️⃣ Valider les résultats (git add . et commit) et faire un push

4️⃣ La personne la plus rapide n’a, normalement, rencontré aucune difficulté (elle peut s’arrêter temporairement pour regarder ce qui va se passer chez les voisins). Les autres voient leur push refusé et doivent faire un pull.

💥 Il y a conflit, ce qui doit être signalé par un message du type :

Auto-merging XXXXXX
CONFLICT (content): Merge conflict in XXXXXX.md
Automatic merge failed; fix conflicts and then commit the result.

5️⃣ Etudier le résultat de git status

6️⃣ Si vous ouvrez les fichiers incriminés, vous devriez voir des balises du type

<<<<<<< HEAD
this is some content to mess with
content to append
=======
totally different content to merge later
>>>>>>> new_branch_to_merge_later

7️⃣ Corriger à la main les fichiers en choisissant, pour chaque ligne, la version qui vous convient et en retirant les balises. Valider en faisant:

git add . && git commit -m "Résolution du conflit par XXXX"

Remplacer XXXX par votre nom. La balise && permet d’enchaîner, en une seule ligne de code, les deux commandes.

8️⃣ Faire un push. Pour la dernière personne, refaire les opérations 4 à 8

Git permet donc de travailler, en même temps, sur le même fichier et de limiter le nombre de gestes manuels nécessaires pour faire la fusion. Lorsqu’on travaille sur des bouts différents du même fichier, on n’a même pas besoin de faire de modification manuelle, la fusion peut être automatique.

Git est un outil très puissant. Mais, il ne remplace pas une bonne organisation du travail. Vous l’avez vu, ce mode de travail uniquement sur main peut être pénible. Les branches prennent tout leur sens dans ce cas.

Exercice 11 : Gestion des branches

1️⃣ Le mainteneur va contribuer directement dans main et ne crée pas de branche. Chaque développeur crée une branche, en local nommée contrib-XXXXX où XXXXX est le prénom:

git checkout -b contrib-XXXXX

2️⃣ Chaque membre du groupe crée un fichier README.md où il écrit une phrase sujet-verbe-complément. Le mainteneur est le seul à ajouter un titre dans le README (qu’il commit dans main).

3️⃣ Chacun push le produit de son subconscient sur le dépôt.

4️⃣ Les développeurs ouvrent, chacun, une pull request sur Github de leur branche vers main. Ils lui donnent un titre explicite.

5️⃣ Dans la discussion de chaque pull request, le mainteneur demande au développeur d’intégrer le titre qu’il a écrit.

6️⃣ Chaque développeur, en local, intègre cette modification en faisant

# Pour être sûr d'être sur sa propre branche
git checkout branche-XXXX
git merge main

Régler le conflit et valider (add et commit). Pousser le résultat. Le mainteneur choisit une des pull request et la valide avec l’option squash commits. Vérifier sur la page d’accueil le résultat.

7️⃣ L’auteur (si 2 développeurs) ou les deux auteurs (si 3 développeurs) de la pull request non validée doivent à nouveau répéter l’opération 6.

8️⃣ Une fois le conflit de version réglé et poussé, le mainteneur valide la pull request selon la même procédure que précédemment.

9️⃣ Vérifier l’arborescence du dépôt dans Insights > Network. Votre arbre doit avoir une forme caractéristique de ce qu’on appelle le Github flow:

Footnotes

1. Ce cas de figure arrive lorsqu’on contribue à des projets sur lesquels on n’a pas de droit d’écriture. Il est alors nécessaire d’effectuer un fork, une copie de ce dépôt sur laquelle on dispose de droits. Dans ce cas de figure, on rencontre généralement un nouvel alias à côté d’origin. nommé upstream (cf. le tutoriel Github pour mettre à jour un fork et qui pointe vers le dépôt source à l’origine du fork. La création du bouton Fetch upstream par Github facilite grandement la mise en cohérence d’upstream et origin et constitue la méthode recommandée.

2. La commande checkout est un couteau-suisse de la gestion de branche en Git. Elle permet en effet de basculer d’une branche à l’autre, mais aussi d’en créer, etc.

Citation

BibTeX citation:

@book{galiana2023,
  author = {Galiana, Lino},
  title = {Python Pour La Data Science},
  date = {2023},
  url = {https://pythonds.linogaliana.fr/},
  doi = {10.5281/zenodo.8229676},
  langid = {en}
}

For attribution, please cite this work as:

Galiana, Lino. 2023. Python Pour La Data Science. https://doi.org/10.5281/zenodo.8229676.