Présentation des outils

Git est un logiciel de gestion de versions décentralisé. Il permet, en autres, de sauvegarder chaque modification d'un programme, de travailler à plusieurs sur le même projet et de gérer différentes versions d'un programme. On peut également partager (push) nos modifications vers un serveur (GitLab pour nous).

GitLab est une plateforme qui permet de sauvegarder et de visualiser un repository git. Il propose aussi un certain nombre de services comme par exemple un gestionnaire de bug (issues), de la code review ou de l'intégration continue (CI).

Git peut être utiliser en ligne de commande ou bien via une interface graphique. Pour ce tutoriel, nous allons l'utiliser via sublime-merge. C'est un outil qui permet de se passer de la ligne de commande et de simplifier la gestion d'un repo git.

Installation

Installation de git

Sur ubuntu ou debian, il suffit de faire cette commande dans un terminal sudo apt install git.

Pour les autres plateformes :

Accéder à https://git-scm.com/download/
Télecharger la dernière version du logiciel pour votre plateforme.
Pour Windows, en faisant clique droit dans un dossier vous devriez voir apparaître "Git GUI Here" et "Git Bash Here".

Installation de sublime-merge

Voir sur le site https://www.sublimemerge.com/ .

Organisation des repos de Polybot

Les repository de PolyBot se trouve à cette adresse : https://gitlab.com/polybot-grenoble . Si vous n'y avez pas accès, vous pouvez demander qu'on vous le donne aux responsables de Polybot.

Voici une description de chaque projet sur GitLab :

Power Supply : La carte de puissance (projet 5A 2021)
Robot Core : Le code qui tournera sur le robot principal
Tutorials and Exemples : Code utilisé pour certains tutos
CAN Bus : Exemple de communication de 2 STM via le bus CAN
Supervisor : Outils qui permettent de contrôler les robots à distance depuis un ordi
Hub ToF : Code et Hardware qui va gérer les capteurs distance pour les collisions
ROBOT-2 : Le code qui tournera sur le robot 2
CAD : Modélisation 3D SolidWorks des robots
MCP230 DSUB Breakout : PCB pour connecter les encodeurs au contrôleur moteur
ArUco_4A : Code pour lire une image avec un code ArUco (projet 4A 2020)

Chaque projet est indépendant, vous pouvez travailler sur un ou plusieurs projet en même temps.

Utilisation pratique

Guide video

Cette vidéo montre :

le fonctionnement de GitLab
comment faire un fork
comment clone un repo grâce à sublime-merge
une visualisation d'un projet git avec des commits et des branches
le concept de branche locale et de branche distante
la création d'une branche local à partir d'une branche distante
la création d'un commit
comment push des commit sur la branche distante
la création d'une merge request
la création d'une nouvelle branche
le changement de branche
la différence d'un fork à un clone direct et l'intéret de le faire
comment récuperer (fetch) les modifications du serveur distant

https://tube.nocturlab.fr/videos/watch/2055a0cd-1b93-4e8d-ab41-a41cc1c0ccbe

La commande stash

Lorsque l'on change de branche, le code visible du dossier va être également modifier pour correspondre à celui de la branche.

Si vous aviez des modifications en cours, git va vous dire cela :

error: Your local changes to the following files would be overwritten by checkout:
    .gitignore
Please commit your changes or stash them before you switch branches.
Aborting

Pour changer de branche vous avez donc 3 options :

Annuler chacune de vos modifications (ça peut être fait facilement via sublime-merge)
Enregistrer vos modfications dans un commit sur la branche actuelle
Utiliser la commande stash pour "planquer" vos modfications dans un dossier interne de git. Vous pourrez ensuite changer de branche et travailler dessus.

Si vous vous êtes trompé de branche et que vous voulez déplacer les modifications en cours vers une autre branche :

Faire la commande stash pour enregistrer vos modifications et pour pouvoir changer de branche
Changer la branche active vers celle que vous désirez
Faire la commande stash pop, qui permet d'appliquer toutes les modifications précédement enregistré
Si cela fonctionne, c'est fini, sinon cela peut créer un conflit. Voir la section sur les conflits pour plus de détail.

Les conflits

[todo] https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts

Le fichier .gitignore

Le fichier .gitignore situé à la racine du projet est particulier. Il permet de lister les fichiers qui seront ignorés par git. Il ne les prendra pas en compte lors de leur modification dans le projet.

Exemple de contenu du fichier .gitignore :

Debug/
*.o
*.tmp

Le dossier Debug et tout son contenu est ignoré. Les fichiers terminants par .o et par .tmp seront également ignorés.

L'utilisation principale de ce fichier est d'ignorer les fichiers temporaires, les fichiers de build et les fichiers générés par les IDE.

Pour aller plus loin (Facultatif)

Ajout d'une clé SSH

GitLab autorise la communication avec ses serveurs via des clés SSH. L'avantage principal est de pouvoir se connecter à GitLab sans devoir rentrer son nom d'utilisateur et son mot de passe à chaque fois.

Pour générer une clé SSH, suivez les indications ici.
Puis, sur GitLab, cliquer sur l'avatar en haut à droite, puis sur Settings.
Cliquer sur "SSH Keys" puis coller la clé publique générée avant (le contenu du fichier terminant par .pub).
Valider en cliquant sur "Add key".

Ajout d'une clé PGP

C'est une forme d'authentification en plus et certains projets (comme par exemple le noyau linux) l'oblige.

Une clé PGP (Pretty Good Privacy) permet de signer son travail.

Tout le monde peut changer son nom lors du commit et peut donc usurper votre identité [1]. PGP empêche cela, en signant le commit. Voici une vidéo explicant le fonctionnement général de PGP : https://www.youtube.com/watch?v=GSIDS_lvRv4 .

Pour créer et mettre en place votre clé PGP, suivez la partie Introduction ici.
Pour l'ajouter sur GitLab, aller dans les paramètres puis dans "GPG Keys".
Ajouter la clé.
Pour signer chaque commit automatiquement faire : git config --global commit.gpgsign true

Maintenant, lorsque vous faites un commit, vous pouvez voir la mention Verified sur le commit signé comme sur l'image ci-dessous.

Utilisation des sous-modules

[todo] [pas urgent car pas utilisé actuellement]

Guide Git

Sommaire