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 vide. 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.

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).

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 Jupyter. 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.

Ceci est normal, ce n’est pas une erreur. 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.

Exercice 3 : 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.

1️⃣ Créer un fichier nommé .gitignore (⚠️ ne pas changer ce nom, et s’assurer que celui-ci n’a pas d’extension) via le bloc note ou votre IDE.

Sur la session Jupyter d’Onyxia, après vous être assurés que vous vous situez bien dans le dossier <nom_du_projet> de l’arborescence, vous pouvez faire : File > New > Text file. Un fichier untitled.txt se crée, que vous pouvez renommer en faisant un mv untitled.txt .gitignore dans le terminal.

2️⃣ Aller sur le site https://www.toptal.com/developers/gitignore. Vous pouvez dans la barre de recherche taper Python, Pycharm, JupyterNotebooks. Copier-coller dans votre .gitignore le contenu de la page.

3️⃣ Quand on crée de la documentation, on veut exclure les extensions .pdf et .html qui sont des résultats à partager et non des fichiers source à suivre. Pour cela, ajouter au début du fichier .gitignore, les extensions:

.pdf
.html

4️⃣ Quand on fait de l’analyse de données, on peut se retrouver avec des fichiers sources de données (par exemple des csv). On désire généralement les exclure pour deux raisons:

• ce sont des fichiers très volumineux pour lesquels le contrôle de version, ligne à ligne, est compliqué
• ils peuvent révéler une information confidentielle ou stratégique qu’on ne désire pas révéler à un concurrent ou un inconnu

Pour cela, ajouter au début du fichier .gitignore, les extensions suivantes

.csv
.xls
.xlsx

Cette suite d’extensions est à enrichir selon vos projets et les formats de données que vous utilisez.

5️⃣ On a aussi les checkpoints sont créés que l’on ne désire pas utiliser. Pour les exclure, ajouter la ligne suivante dans le fichier .gitignore

*-checkpoint

Exercice 4 : Indexer des modifications

1️⃣ Se rendre dans l’extension Git de Jupyter. Vous devriez retrouver un cadre ayant cet aspect

2️⃣ En passant votre souris au dessus du .gitignore, vous devriez voir un + apparaître. Cliquez dessus.

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

git add .gitignore

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

3️⃣ Observer le changement de statut du fichier .gitignore. Il est désormais dans la partie Staged En gros, vous venez de dire à Git que vous allez rendre publique une évolution du fichier.

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

On branch master

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

Exercice 5 : Premier commit (enfin !)

Tout se passe dans la partie inférieure de l’interface graphique.

1️⃣ Entrer le titre Initial commit et ajouter une description Création du fichier .gitignore : tada : (sans les espaces autour des :). : tada : (sans les espaces) sera converti en emoji 🎉 par Github quand on voudra afficher la description du commit².

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️⃣ Cliquer sur l’onglet History. Votre commit apparaît à ce niveau. Si vous cliquez dessus, vous obtenez des informations sur le commit

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 master

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

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.

Exercice 7 : Rapatrier des modifs en local

1️⃣ Se rendre sur votre dépôt depuis l’interface https://github.com. 2 manières de faire à ce niveau :

• Cliquer sur Add file > Create new file et appeler le fichier README.md
• Cliquer sur le bouton ADD A README qui est affiché sur la page d’accueil. Supprimez tout autre texte si Github vous a suggéré un contenu pour le README

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 master 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. Il faut re-synchroniser votre copie locale avec le dépôt distant :

• 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 master

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

8️⃣ Regarder, sur JupyterLab, l’onglet History. 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.

Exercice 8: Créer une nouvelle branche et l’intégrer dans master

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 - Master puis sur le bouton New Branch. Rentrez issue-1 comme nom de branche (la branche doit être créée depuis master, ce qui est normalement le choix par défaut) et cliquez sur Create Branch

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 (🐱) à 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 (🐨) 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).

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 master. Dans l’interface Jupyter, il suffit de cliquer sur master dans la liste des branches. Si vous êtes en ligne de commande, il faut faire

git checkout master

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 master

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 master 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.

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 master

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 master

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 master

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

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

Exercice 11 : Gestion des branches

1️⃣ Le mainteneur va contribuer directement dans master 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 master).

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 master. 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 master

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écedemment.

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: