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:
L’interface de votre projet se présente alors ainsi :
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) :
En revenant à la racine du porjet, on constate que le fichier REAMDE.md a bien été modifié :
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
:
-
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 ducommit
, veillez à mettre un texte d’explication du styleUpdate README.md dans branche testFonction
. Constatez que ces changements ont bien été pris en compte :
En basculant dans la branchemain
, vous ne devriez plus voir apparaître les derniers ajouts (puisque les 2 branches n’ont pas encore étaient fusionnées). -
Nous allons maintenant fusionner la branche
TestFonction
dans la branchemain
.
- Basculez à nouveau dans la brancheTestFonction
.
- Sélectionnez dans la barre latérale gauche le menuBranches
, cliquez sur le boutonMerge Requests
,
- Cliquez sur le boutonCreate merge request
qui indique que l’on demande à fusionner (merger) la brancheTestFonction
dans la branchemain
:
- Appuyer sur les boutonsApprove
puisMerge
. - 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 branchetestFonction
, 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
) :
Modifier le projet depuis votre ordinateur¶
Copie et modification locale des fichiers du projet¶
-
Ouvrez un Terminal et déplacez-vous dans un répertoire temporaire à l’aide de la commande
cd
. -
Exécutez
git clone XX
, ou XX est l’adresse de votre projet (celle copier ne mémoire à l’instant). Grâce à la commandels
, constatez qu’un nouveau répertoire vient d’être créé. Déplacez-vous dedans grâce à la commandecd
. -
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). -
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, commeNouveau 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
- 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.
- 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"
- 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.
- 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 !
- Pour fusionner la branche
TestFonction
dans la branchemain
, déplacez-vous d’abord dans la branchemain
, 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¶
-
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 ! -
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.
- Allez observer la page web (une fois mise à jour avec
CTRL+R
ouCMD+R
) : vous devriez voir la différence !
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).
- 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 :
Ajoutez un élément graphique de typelabel
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.
-
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 à
-
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
, puisgit 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.
-
Vous pouvez maintenant modifier votre projet avec QT. Toutes les commandes git de QT sont disponibles dans le menu
Outils / Git
. Dans le sous-menuDépôt local
, utilisezgit commit
pour enregistrer localement les changements (en sélectionnant les fichiers que vous souhaitez associer à ce commit) :
N’oubliez pas de déposer un petit message qui explique le commit, sinon le boutonSoumettre
ne sera pas actif. -
Dans le menu
Dépôt distant
, vous pouvez alors faire ungit pull ...
pour s’assurer que personne n’a modifié le dépôt GitLab entre temps, puis ungit push ...
pour envoyer vos dernières modifications. Votre projet GitLab sera alors automatiquement mis à jour. -
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 ungit 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.