Sommaire

Tuto Git / GitLab

ELC a11 - Programmation des interfaces graphiques en C++, Stéphane Derrode

Dans ce tutorial, vous apprendrez les rudiments de l’utilisation de git, et de la plateforme gitlab de l’École Centrale de Lyon. L’objectif est d’utiliser git lors du développement, en binôme, de votre projet.

Git est un système de gestion de versions de fichiers texte, très utilisé pour gérer les codes sources d’un projet, quel que soit le langage (Python, Java, C++); il est également très utile pour les rapports écrits en Latex ou en markdown. Il permet à tout moment de revenir à une version antérieure de votre code, ou bien de tester de nouvelles fonctionnalités sans mettre en péril votre code principal (cf notion de branche de développement).

GitLab (comme d’autres : GitHub, BitBucket) est une sorte de réseau social pour développeur, basé sur git, facilitant le partage de code entre les membres d’une équipe travaillant au même projet.

Git est un outil essentiel pour l’informaticien, et savoir le maîtriser est une compétence très appréciée des employeurs. Nous allons ici le mettre en œuvre, dans le cadre du développement du projet, l’équipe étant ici constituée de votre binôme.

Remarque : Le lien vers le fichier github-git-cheat-sheet.pdf donne un aperçu rapide des commandes git. Il pourra vous être utile après la première phase d’apprentissage.

Installation / configuration de git

Pour vérifier que git est déjà installé sur sa machine, tapez la commande git --version dans un Terminal (les utilisateurs de Windows doivent utiliser le terminal Windows PowerShell, a priori déjà installé sur leur machine, plutôt que le terminal standard). Vous devriez normalement voir apparaître quelque chose comme git version 3.8.1. Si cette commande ne fonctionne pas, pour les utilisateurs de Windows, alors suivez ce pointeur pour l’installer : git-scm.

git est utilisé en ligne de commandes, par le biais d’un Terminal. Il est aussi possible d’utiliser des interfaces graphiques (comme GitHub Desktop), mais je le déconseille vivement (au moins dans un premier temps). Mieux vaut se confronter à la syntaxe pour maîtriser les concepts derrière git, puis éventuellement utiliser les interfaces graphiques (mais vous verrez alors que vous n’en aurez plus nécessairement besoin !).

Pour configurer git (à ne faire qu’une seule fois) :

git config --global user.name "votre nom"           # enregistrement par git de votre nom.
git config --global user.email "votre adresse mail" # enregistrement par git de votre adresse mail.
git config --global color.ui auto                   # active la colorisation de la sortie en ligne de commande

Vérifiez que tout est ok grâce à la commande git config --list qui affiche la configuration de git sur votre machine.

Création d’un nouveau projet avec GitLab

  • Ouvrez GitLab, et connectez-vous avec vos identifiants de l’École Centrale de Lyon.
  • Créez un nouveau projet (New project / Create Blank Project), en le configurant de la manière suivante:
    New Project
    L’interface de votre projet se présente alors ainsi :
    Interface Projet

Le fichier README.md permet de décrire l’objectif de votre projet ou de donner des indications sur la manière de l’installer (le projet que nous venons de créer est public, et donc toute personne peut être amenée à le télécharger ). Le format .md (dit markdown) est un format texte permettant d’afficher des textes avec une mise en page minimale (titre, gras, souligné, liste à puces…). Il est très utile pour la prise de notes rapides (CR de réunion, notes de cours ou ToDo List). Vous pouvez consulter ce pointeur pour en connaître la syntaxe : Markdown-Cheatsheet.

Pour compléter ce fichier, cliquez sur son nom, puis sur le bouton Edit : vous êtes en mode édition. Effacez le contenu par défaut et rajoutez alors ces quelques lignes en dessous du titre :

**Élément en gras**

Liste à puces:

 1. item 1
 1. item 2
 1. item 3

Pour que les changements apportés à votre fichier soient pris en compte par git, vous devez commiter vos modifications, à l’aide du bouton Commit changes, en n’oubliant pas de donner une explication sur les modifications effectuées (ici : Update README.md par défaut) :
Modif readme.md
En revenant à la racine du porjet, on constate que le fichier REAMDE.md a bien été modifié :
Update readme.md

Manipulation des branches de développement

Par défaut, vous travaillez sur une branche appelée main. Il est possible de créer d’autres branches de développement, ce qui permet de coder une nouvelle idée (par exemple une nouvelle option de jeu, ou un nouveau menu dans une interface graphique) sans intervenir directement sur la branche principale. On ne fusionne la branche annexe avec la branche principale que si l’on est satisfait du travail réalisé sur cette branche. Si on ne l’est pas, on peut détruire la branche annexe sans influence sur la branche principale. Notez que pendant le développement de la branche annexe, la branche principale peut continuer à évoluer, la fusion sera faite intelligemment.

Voyons ceci au travers d’un exemple :
1. Créer une branche appelée testFonction:
New branch

  1. Vous êtes automatiquement placé dans la branche testFonction et toutes les modifications que vous apportez ne le sont que dans cette branche. Pour le vérifier, modifiez le fichier README.md, en rajoutant quelques lignes (en suivant la démarche présentée ci-dessus). Lors du commit, veillez à mettre un texte d’explication du style Update README.md dans branche testFonction. Constatez que ces changements ont bien été pris en compte :
    Test branch
    En basculant dans la branche main, vous ne devriez plus voir apparaître les derniers ajouts (puisque les 2 branches n’ont pas encore étaient fusionnées).

  2. Nous allons maintenant fusionner la branche TestFonction dans la branche main.
    - Basculez à nouveau dans la branche TestFonction.
    - Sélectionnez dans la barre latérale gauche le menu Branches, cliquez sur le bouton Merge Requests,
    - Cliquez sur le bouton Create merge request qui indique que l’on demande à fusionner (merger) la branche TestFonction dans la branche main :
    merge branch
    - Appuyer sur les boutons Approve puis Merge.

  3. Revenez alors à la racine de votre projet. Constatez que la branche main a bien été mise-à-jour par fusion du travail réalisé sur la branche testFonction, et que cette dernière branche a été supprimée (notez qu’il est possible de conserver une branche suite à une fusion).

Vous connaissez maintenant le minimum vital pour travailler avec git depuis la plateforme GitLab. Nous allons maintenant étudier comment faire le lien entre cette plateforme et votre ordinateur. Avant de basculer, veuillez copier en mémoire l’adresse du projet, que vous trouverez de la façon suivante (choisissez Clone with HTTPS) :

adresse clone

Modifier le projet depuis votre ordinateur

Copie et modification locale des fichiers du projet

  1. Ouvrez un Terminal et déplacez-vous dans un répertoire temporaire à l’aide de la commande cd.

  2. Exécutez git clone XX, ou XX est l’adresse de votre projet (celle copier ne mémoire à l’instant). Grâce à la commande ls, constatez qu’un nouveau répertoire vient d’être créé. Déplacez-vous dedans grâce à la commande cd.

  3. La commande ls permet de voir le seul fichier actuellement dans votre projet : le fichier README.md. Il existe également un répertoire caché qui accompagne votre projet : ce répertoire contient toutes les informations nécessaires à git pour gérer les versions des fichiers et les branches (répertoire qu’il ne faut jamais modifier directement).

  4. Créez un nouveau fichier appelé tuto.c avec votre éditeur préféré et sauvegardez-le dans le répertoire local de votre projet après avoir ajouté une phrase quelconque dans ce fichier, comme Nouveau fichier créé sur mon ordinateur.. Pour que ce fichier soit bien pris en compte par git, il faut le faire de manière explicite avec la commande : 

git add tuto.c

Cette dernière ne doit être faite qu’une seule fois lors de la création du fichier. La commande git checkout permet de voir que le statut du fichier est A (ajout). A savoir : pour ajouter plusieurs nouveaux fichiers dand un un projet en une seule fois : 

git add -A
  1. Pour réaliser le commit à la main : 
git commit tuto.c -m "commit initial"

L’option -m permet d’associer un commentaire à votre commit : ce message est obligatoire ! La commande git checkout montre alors que votre projet local est en avance d’un commit par rapport à sa version sur la plateforme GitLab. Nous verrons comment publier ces changements un peu plus loin.

  1. Vous pouvez maintenant modifier le fichier README.md en ajoutant une phrase du type Cette phrase a été ajoutée depuis mon ordinateur, et commiter localement le changement :
git commit README.md -m "message d'explication"

Un nouveau git checkout indique que le dépôt local du projet est maintenant en avance de 2 commits par rapport à la plateforme.
Remarque : si vous avez besoin de commiter un grand nombre de fichiers d’un coup (-a pour all) : 

git commit -a -m "message d'explication"
  1. La commande git log permet de voir tous les commits réalisés sur le projet depuis sa création. Un identifiant unique du type 6d0cec16bbddb8a513805fc83c888a59627bdcb1 est affecté à chaque commit. Grâce à ce numéro, il est ainsi possible de revenir à n’importe quelle version antérieure de votre projet. Les commandes pour le faire sont relativement complexes et dangereuses ; vous pourrez y revenir après avoir acquis une certaine maîtrise des commandes de base. Notez que l’on peut voir la date et l’auteur de chaque commit, et donc revenir vers le fautif en cas d’introduction d’un bug !

Il faut noter que l’opération de commit local se fait environ toutes les heures dans un projet, jamais au-delà d’un jour de développement. On peut commiter localement un travail même s’il est buguer ou non terminé : ce n’est pas grave puisque cette version du projet vous appartient (elle est sur votre ordinateur). Par contre, l’étape suivante ne se fait que lorsque l’on dispose d’une version qui compile et fonctionne, après des tests intensifs, sinon on risque de partager ses bugs avec tous les autres développeurs du projet.

  1. Il est possible de créer vos branches locales 
git branch TestFonction

et de changer de branche par 

git checkout TestFonction

ou

git checkout main

pour revenir à la branche main si vous étiez dans la branche TestFonction. La commande git branch permet de savoir dans quelle branche on travaille actuellement. Avant un changement de branche, il faut commiter son travail, pour que git se souvienne de l’état de la branche avant d’en sortir. Faites un essai !

  1. Pour fusionner la branche TestFonction dans la branche main, déplacez-vous d’abord dans la branche main, puis : 
git merge TestFonction

S’il n’y a pas de conflit de fusion, alors la fusion est faite instantanément. Pour détruire la branche locale :

git branch -d TestFonction

La commande git checkout indique que localement vous êtes maintenant en avance de la somme des commits de la branche main et de ceux de la branche TestFonction.

Publication de ses modifications sur la plateforme GitLab

  1. Dans un premier temps, vérifiez que tous les changements locaux ont bien été commiter localement, grâce à la commande git checkout. Si cette commande indique que certains fichiers ne sont pas à jour, alors faites le nécessaire !

  2. Pour envoyer les commits sur la plateforme : 

git push origin main

On précise ainsi que l’on envoie le contenu de la branche main sur la plateforme github ; origin est une variable qui désigne l’adresse de votre projet. On peut également publier une branche locale, pour la partager avec d’autres développeurs.

  1. Allez observer la page web (une fois mise à jour avec CTRL+Rou CMD+R) : vous devriez voir la différence !

apres git push

Travailler à plusieurs sur le même projet

Pour la suite de ce tuto, veuillez-vous organiser par deux. Le premier doit permettre au second de modifier son projet. Pour cela, le premier se rend dans l’onglet Members de son projet sur la plateforme GitLab. Il autorise alors son binôme à participer à son projet, en tant que Reporter ou Developer. Attention la demande de rejoindre le projet du premier doit être validée par le second en répondant à l’e-mail qu’il reçoit automatiquement de la part de la plateforme.

Le second étudiant clone alors le projet sur son ordinateur (comme ci-dessus). Veuillez ensuite vous mettre dans la situation suivante : modifiez localement tous les deux un fichier différent sur votre ordinateur. Le premier met alors à jour la plateforme par un git push ... (après le git commit qui va bien). Tout devrait se passer normalement. Constatez ensuite que si le second tente de faire la même chose, alors git refuse de le faire car sa version locale est en retard par rapport à la version sur la plateforme. git vous demande donc d’abord de mettre à jour votre version locale par un git pull … (rapatrie les changements de votre collègue sur votre machine perso). Cette étape entraîne la fusion de votre version locale avec la version de la plateforme. Si la fusion se passe bien (i.e. : il n’y a pas de conflit entre les 2 versions), alors il sera alors possible au second de pusher son travail à son tour. À partir de cet instant, c’est le premier qui dispose d’une version locale en retard par rapport à la plateforme.

C’est bien compris ? Tant mieux, car maintenant nous allons voir comment mettre cela en œuvre avec QT…

QT + git + GitLab

Dans cette partie du tutorial, vous pouvez travailler séparément (pour travailler en binôme sur un projet QT géré avec git, il vous suffira de combiner ces informations avec la section précédente).

  1. Veuillez d’abord créer un nouveau projet C++ Qt Quick Application avec QT, appelé tutoGitQT. N’oubliez pas de sélectionner git comme gestionnaire de version, comme ci-dessous :
    new projet _QT_ with _git_
    Ajoutez un élément graphique de type label dans la fenêtre (vous savez maintenant comment faire). Voilà le code QML que vous devriez obtenir:
import QtQuick 6.2
import QtQuick.Controls 6.2
import tutoGitQT

Rectangle {
    id: rectangle
    width: 300
    height: 200

    color: Constants.backgroundColor

    TextInput {
        id: textInput
        width: 80
        height: 20
        text: qsTr("Text Input")
        anchors.verticalCenter: parent.verticalCenter
        font.pixelSize: 12
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        anchors.horizontalCenter: parent.horizontalCenter
        font.bold: true
    }
}

Exécutez votre projet pour vérifier que l’application fonctionne bien.

  1. Créez ensuite un nouveau projet public sur GitLab, nommé par exemple QT1. Modifier le fichier README.md pour qu’il ne contienne qu’une simple phrase d’accueil. À ce stade, vous devriez avoir quelque chose de similaire à projet QT/git sous Gitlab

  2. On va maintenant associer le projet QT au projet GitLab.

  • Ajouter à la racine de votre projet QT un fichier appelé .gitignore (le nom est important à respecter), et copier le contenu de ce pointeur dans ce fichier.

  • Ouvrez un Terminal et déplacez-vous dans le répertoire de votre projet QT. Puis tapez:

    • git commit -a -m "commit initial"
    • git remote add depot xx où xx correspond à l’adresse de votre projet sur GitLab (quelque chose comme https://gitlab.ec-lyon.fr/sderrode/qt1.git).
    • git config pull.rebase false, puis git pull --allow-unrelated-histories depot main, pour tirer le dépôt distant vers votre répertoire local (importation du fichier README.md). La fusion devrait se passer sans problème (vous pouvez entrer un texte d’explication ou accepter le texte proposé par défaut). Attention pour quitter l’éditeur intégré au Terminal (et donc valider le message), utilisez la commande :q.
    • git push -u depot main, pour envoyer votre code fusionné source sur la plateforme GitLab.

  • Vérifiez alors que la page Web de votre projet se met bien à jour avec les codes sources de votre projet (recharger la page si nécessaire).
    Ces étapes doivent être réalisée une seule fois, lors de la création d’un nouveau projet. Seules les opérations suivantes doivent être répétées pour mettre à jour régulièrement votre projet.

  1. Vous pouvez maintenant modifier votre projet avec QT. Toutes les commandes git de QT sont disponibles dans le menu Outils / Git. Dans le sous-menu Dépôt local, utilisez git commit pour enregistrer localement les changements (en sélectionnant les fichiers que vous souhaitez associer à ce commit) :
    commit avec _QT_
    N’oubliez pas de déposer un petit message qui explique le commit, sinon le bouton Soumettre ne sera pas actif.

  2. Dans le menu Dépôt distant, vous pouvez alors faire un git pull ... pour s’assurer que personne n’a modifié le dépôt GitLab entre temps, puis un git push ... pour envoyer vos dernières modifications. Votre projet GitLab sera alors automatiquement mis à jour.

  3. Si vous souhaitez travailler à deux sur le même projet QT, alors
    a. le premier doit inviter le second à participer au projet (comme précédemment).
    b. le second n’a alors qu’à opérer un git clone xx sur le projet, avant de l’ouvrir avec QT. Il peut alors faire ses propres commits locaux et pusher son travail sur GitLab.