Colaborer sur du code avec Git

Introduction

Git est un logiciel dit de gestion de version (version control system - VCS) qui permet de suivre les modifications qui sont apportées à un code. L'intérêt principal de ce type d'outil est de permettre à plusieurs développeurs d'éditer un code en parallèle et de se synchroniser régulièrement sans risquer de perdre d'information lors de la mutualisation.

Git en tant que logiciel est dit "décentralisé", c'est à dire qu'il peut être utilisé localement pour des projets personnels sans avoir besoin d'un hébergement accessible depuis internet. Dans le cas d'une utilisation classique à plusieurs, on ajoutera généralement l'utilisation d'un hébergement "centralisé" en ligne sur lequel chaque développeur pourra se synchroniser en venant récupérer les updates, et/ou envoyer ses modifications. Plusieurs plateformes sont à votre disposition pour réaliser cet hébergement:

- Gitlab Binet: Est une plateforme utilisant le framework "Gitlab" qui est mis en place par votre Binet réseau. La plateforme est spécifique à Polytechnique et vous pouvez y héberger des codes privés (par défaut) ou publics.
- - Il s'agit probablement de la plateforme la plus simple à utiliser si vous débutez. Vous y trouverez un TD de formation, et pouvez disposer du soutien de votre Binet.
- - Votre code y est sécurisé et reste privé tant que vous ne le placez pas publiquement. Seuls les étudiants de Polytechnique peuvent avoir un compte sur le gitlab binet (vos enseignants n'y auront pas de comptes).

- Gitlab.com: Est une plateforme générique et communautaire, basée sur le framework "Gitlab".
- - Il s'agit d'une plateforme communautaire ou toute personne peut y créer un compte. Vous pouvez créer par la suite des dépots de codes publics ou privés à votre convenance.
- - La plateforme est gratuite pour une utilisation simple (largement suffisant pour vos projets), et peut proposer des fonctionnalités plus avancées de contrôle continu avec des offres payantes.

- Github: La plateforme générique la plus répandue actuellement pour partager du code sur internet. Github est basé sur sa propre interface (différent de GitLab).
- - Github nécessite l'utilisation de clés SSH pour synchroniser son code. Cela apporte plus de sécurité que l'utilisation d'un login/mot-de-passe, mais demande un effort supplémentaire de configuration sur votre machine. A ce titre, ce n'est pas forcément la plateforme la plus simple pour vos débuts avec git.
- - Github est une plateforme acquise par Microsoft. Les codes que vous y placez peuvent être utilisés, notamment, comme données d'entrainement d'outils d'apprentissage tel que Github Copilot. La plateforme propose également une version gratuite (suffisante dans la plupart des cas) et une version payante pour des fonctionnalités avancées.

Process du tutoriel

La suite de ce document décrit un tutoriel "pas à pas" dans le cas où il s'agit de votre toute première utilisation de git et d'une plateforme d'hébergement.

On considèrera la configuration où vous êtes en binome: Student1 et Student2. Le schéma que l'on souhaite mettre en place contient 3 instances de code:

- Le code présent sur la machine de Student1.
- Le code présent sur la machine de Student2.
- Le code présent sur le serveur d'hébergement (on considèrera gitlab pour cet exemple).

On suivra la logique de mise en place suivante permettant de vous entrainer à faire une première synchronisation tant en minimisant les étapes de configurations sur vos machines:

1) Installation du logiciel git
2) Création d'un projet vide sur la placeforme gitlab
3) Clone du projet et synchronisation entre Student1 et Student2
4) Mise en place des fichiers du projet sur le dépot

Remarques: Git est un logiciel écrit et documenté principalement pour fonctionner à partir d'une ligne de commande, peut importe votre OS.

- Bien qu'il existe de nombreuses extensions (ex. sous Visual Studio, ou VS Code) permettant d'utiliser git en mode graphique, nous vous conseillons vivement de débuter en utilisant la ligne de commande.
- Le mode graphique peut vous paraitre plus simple initialement, mais sera sans doute moins connu et documenté en cas de problèmes. N'utilisez ces aides que si vous avez déjà l'habitude de git en ligne de commande.
- Au besoin, un rappel de commande de bases sur la ligne de commande est disponible ici.

1) Installation du logiciel git

Il est tout d'abord nécessaire d'installer sur vos machines le logiciel git. Chaque étudiant du groupe doit réaliser cette étape sur sa propre machine.

- Si vous êtes sous Linux vous pouvez installer git à partir de votre gestionnaire de package.

# ex Sous Ubuntu
sudo apt get install git

- Si vous êtes sous MacOS, vous pouvez utiliser Homebrew ou MacPorts. Voir documentation. (Vérifiez que vous n'avez pas déjà git avant de tenter de l'installer en tapant par exemple 'git --version' en ligne de commande)

- Si vous utiliser les machines fixes de l'école, git est déjà installé.

- Si vous êtes sous Windows, vous pouvez installer "gitforwindows" comme détaillé ci-après.

Installation de gitforwindows sous Windows

Installez Git que vous pouvez trouver à partir de https://gitforwindows.org/.

Lors de l'installation, suivez les options par défaut sauf pour les écrans suivants:

- Editeur par défaut: choisissez Visual Studio Code (plutôt que vim)

- Cette option suppose que vous avez Visual Studio Code déjà installé sur la machine (vous pouvez prendre n'importe quel autre éditeur de texte de votre choix).

- Rem. Le choix par défaut est "vim" qui est un éditeur de texte sur ligne de commande minimaliste, puissant mais ancien, et dont les commandes sont moins classiques.

- Branche principale: Choisissez la branche par défaut nommée "main" (seconde option)

assets/02_gitforwindows_defaultbranch.jpg

Git et les serveurs en lignes utilisaient principalement le terme "master" par défaut pour désigner la "branche" principale du code. Pour éviter la connotation associée à ce terme, la plupart des serveurs utilisent désormais le terme "main" pour désigner le code principal. Il est préférable que votre Git et votre serveur utilise le même terme pour désigner le code.

Rem. Git définit la notion de branches, qui permet de gérer plusieurs versions d'un code sur un même dépot - par exemple une version proposant des fonctionnalités expérimentales non disponibles/compatibles avec la branche "principale". Vous n'avez cependant pas besoin d'utiliser cette notion dans le cas de votre projet.

Une fois installé, vous devez pouvoir exécuter le programme "Git Bash" depuis le menu de Windows. Celui-ci vous ouvrez une ligne de commande qui vous permettra de naviguer dans vos répertoires avec une ligne de commande de type Unix.

2) Création d'un projet sur gitlab

Dans cette étape, nous allons créer un projet sur le serveur en ligne. Ce sera à partir de ce projet centralisé en ligne que votre groupe pourra se synchroniser.

Dans un premier temps, créez un simple projet vide qui va permettre d'initialiser le projet. Nous complèterons l'ensemble avec les fichiers du projet dans un second temps. Notez que cette étape ne doit être faite qu'une seule fois par projet et par un seul étudiant du groupe. On supposera que seul Student1 réalise cette étape.

L'interface de gitlab devrait disposer d'une option de création d'un nouveau projet.

Si plusieurs choix sont proposés, sélectionnez la création d'un projet vide qui ne contiendra pas de fichiers (souvent un simple Readme).

Complétez le nom de votre projet, par exemple inf443-project-nom1-nom2. Vous pouvez choisir à ce moment si votre projet sera public ou privé (peut être modifié par la suite également).

assets/05_gitlab_create_project_fill.jpg

Une fois créé, vous devriez obtenir une fenêtre montrant l'état actuel de votre projet. Dans le cas présenté, le projet ne contient qu'un fichier README.md généré automatiquement dont le contenu est affiché dans l'interface.

Par défaut, Student1 pourra avoir accès à ce projet à partir de son login/mot de passe. Mais Student2 n'y a pas accès en écriture (ni en lecture si le projet est privé).

Pour permettre la collaboration avec Student2, ajoutez le en tant que membre du projet.

- Sous gitlab: Project information \(\rightarrow\) Members \(\rightarrow\) Invite members.
- Ajoutez alors l'identifiant de Student2 en tant que Developer/Maintainer/Owner.
- Sous github: Settings \(\rightarrow\) Collaborators \(\rightarrow\) Add people

Student2 devrait recevoir une notification sur l'outil en ligne, qu'il devra potentiellement accepter pour obtenir accès au projet.

3) Clone du projet et synchronisation

Récupération du code (git clone)

Dans cette partie, un des étudiants va récupérer le code depuis le dépot, et vérifier qu'il arrive à se synchroniser avec le serveur. On supposera que cette opération est réalisée d'abord par Student1.

Student1 doit réaliser une étape dite de "clone". C'est à dire que l'on va récupérer le code à l'aide de git, ainsi que l'ensemble de la configuration indiquant où est hébergé le code pour pouvoir y apporter des modifications par la suite.

Choisissez tout d'abord un endroit dans vos fichiers où sera placé le code de votre projet.

- Sous Windows cela peut être par exemple "c:/inf443_project/", sous Linux cela pourra être "/usr/home/votreNom/inf443_project/".
- Mais vous pouvez créer et vous placer dans n'importe quel sous-répertoire de votre choix.
- Choisissez de préférence un répertoire vide dans votre cas ce qui vous facilitera les choses en cas de problème. Ne ré-utilisez pas votre répertoire existant avec vos codes de TD.
- Sous Windows, évitez de placer ce code dans une hiérarchie de noms trop longs car le nombre de caractères maximal du chemin depuis la racine est limité. Evitez également des chemins possédant des accents, des espaces, ou tout caractère autre que les lettres a-z et nombres 1-9.

A) Ouvrez une ligne de commande et déplacez-vous jusqu'à être localement dans le répertoire que vous avez choisi (à l'aide des commandes "cd directoryName").

- Au besoin: Tutoriel de rappel de l'utilisation de la ligne de commande.
- Sous Windows, la ligne de commande correspond à celle obtenue en lançant "Git Bash"

# Exemple: Si votre répertoire est dans: c:/inf443_project
# Etape 1: Allez sur la racine du répertoire c:
cd /c
# Etape 2: Allez dans inf443_project
cd inf443_project

B) Une fois dans le bon répertoire (vérifiez avec la commande "pwd"), tapez la commande suivante pour réaliser l'étape de "clone"

git clone URL

avec URL correspondant à celle de votre projet sur le serveur en ligne.

\(\Rightarrow\) Vous pouvez obtenir cette url à partir de l'onglet "Clone" \(\rightarrow\) "Clone with HTTPS" dans l'interface en ligne.
- (utilisez la version HTTPS et non pas SSH sauf si vous avez préalablement configuré une clé SSH).

Notez que la forme attendue de l'URL est la suivante:
- Avec gitlab.com: "https://gitlab.com/Student1Login/ProjectName.git"
- Avec gitlab.binet.fr: "https://gitlab.binets.fr/Student1Login/ProjectName.git"
- Avec gitlab.com: "https://github.com/Student1Login/ProjectName.git"

Vous devrez indiquer votre login et mot de passe à ce moment si le projet est privé avec gitlab.

Si l'étape s'est déroulée correctement, vous devriez voir votre répertoire.

- Placez votre ligne de commande dans ce nouveau répertoire (ex. "cd inf443-project-nom1-nom2").
- Une fois dans ce répertoire, la ligne de commande indique généralement le nom de la branche (ici main).
- En tapant 'ls -a', vous devriez voir un répertoire .git qui contient les fichiers nécessaires à git pour traquer les modifications.

Rem. A la différence d'un "téléchargement classique", la récupération du code par le biais d'un git clone permet de récupérer un projet git déjà initialisé avec l'url du projet centralisé.

Envoie sur le serveur (git commit, git push)

Pour l'instant, le répertoire récupéré par Student1 ne contient rien, ou un seul fichier README.md. Nous allons vérifier dans cet étape que Student1 arrive à envoyer ses modifications sur le serveur.

- Modifiez le contenu du fichier README.md (ouvrez-le avec VS code par exemple et modifier les premières lignes).
- Ajoutez un fichier quelconque dans le répertoire du projet. Par exemple, créez le fichier temp.cpp, avec un contenu arbitraire.

Indiquez à git qu'il faut traquer un nouveau fichier avec les lignes de commande suivante:

git add README.md
git add temp.cpp

Rem. "git add README.md" est inutile si README.md était déjà présent. Git track automatiquement les modifications sur les fichiers du dépot. Le fichier temp.cpp doit par contre être explicitement ajouté à Git car il ne faisait pas partie du dépot.

Dans la suite, la synchronisation avec le dépot central se réalise en deux étapes:

Etape 1: Commit

Le "commit" correspond à la prise en compte par Git d'une nouvelle version locale à votre machine.

git commit -a

Un éditeur de texte (VS Code si vous l'aviez sélectionné) va s'ouvrir en attendant que vous indiquiez le message correspondant à cette mise à jour.

- Notez que vous aurez dans ce message un aperçu des fichiers modifiés et/ou ajoutés en fin de commentaires.
- Le message que vous mentionnez peut être quelconque, c'est une simple information pour les utilisateurs (ici "My first update"), mais il est nécessaire d'indiquer un message non vide.

- Sauvegarder le fichier et quittez pour que le commit soit réalisé.

Rem. Il est possible d'avoir le listing de l'ensemble des commits passés (donc de vos mises à jours) en appelant "git log"

Etape 2: Push

L'étape de commit n'impacte que le répertoire Git sur votre machine et n'est pas propagé sur le serveur centralisé. Pour cela, vous devez appeler explicitement

git push

Si l'opération "push" s'est bien déroulée, vous devriez voir sur le dépot en ligne la propagation de votre modification et votre nouveau fichier (rafraichissez le navigateur).

Votre code local et en ligne sont alors synchronisés.

Synchronisation globale

Vérifiez désormais que Student2 puisse réaliser les mêmes étapes. Réalisez dans l'ordre:

1) Ouverture d'une ligne de commande dans un répertoire où Student2 souhaite placer son projet (ce répertoire peut être différent de celui de Student1).

2) "git clone URL" sur l'url du dépot en ligne afin de récupérer le projet.
- Vérifiez que Student2 récupère bien le projet avec les modifications déjà réalisé par Student1.

3) Student2 peut modifier à son tour les fichiers du projet, et/ou ajouter d'autres fichiers (n'oubliez pas alors "git add" pour ajouter les fichiers modifiés)

4) Student2 fait appel à "git commit -a" pour mettre à jour localement ses modifications.

5) Student2 envoie ses modifications sur le dépot en ligne avec l'appel à "git push".
- Vérifiez que la modification effectuée par Student2 apparait bien en ligne.

Après cette étape, les codes sont dans l'état suivant:

Student 2: Code à jour
Code en ligne: Code à jour
Student 1: Code non à jour - ne contient pas la dernière modification de Student2

Pour mettre à jour sa version, Student1 doit réaliser un "pull"

git pull

La commande permet de récupérer la dernière version du code et vient intégrer les modifications dans le répertoire local. Une synthèse des fichiers modifiés/ajoutés sont affichés sur la ligne de commande.

A ce stade, les trois codes sont tous au même stade.

Si jamais Student1 avait modifié son code avant de réaliser un pull, git indiquerait qu'il faudrait alors préalablement réaliser un "commit": La mise à jour d'un code depuis un dépot en ligne ne pouvant se faire que sur une version "localement à jour".

Si jamais Student1 avait modifié la même fonction que Student2 entre temps, un conflit serait mentionné. Il faudra alors choisir entre:

- Fusionner les deux codes et "trier" manuellement: Git modifie alors les fichiers pour indiquer les deux choix. Student1 devra garder la version des propositions qu'il souhaite.
- Garder sa propre version
- Ecraser sa partie pour ne garder que la version de Student2.

Git pull/commit/push

Student1 et Student2 peuvent par la suite éditer en parallèle leur propre version de code localement. La synchronisation consiste à régulièrement venir mettre à jour sa version depuis le dépot en ligne, et y envoyer ses propres modifications. Student1 et Student2 peuvent réaliser ces étapes à différents moments.

Il est conseillé de suivre l'enchainement suivant pour chaque mise à jour:

# Mise a jour locale
git commit -a

# Récupération des mises à jour depuis le dépot en ligne
git pull

# Si git pull récupère un nouveau code, il sera nécessaire de faire un nouveau commit
# git commit -a # si nécessaire pour le "merge" de code

# Envoie de ses propres modifications sur le dépot en ligne
git push

Pour éviter les conflits, et les divergences de votre code, prenez l'habitude de mettre régulièrement à jour votre code. Il est conseillé de garder sur le dépot en ligne une version la plus à jour possible, en veillant à ne placer que des modifications qui n'empêchent pas le code de compiler.

Mise en place du projet sur le dépot

Préparation du répertoire du projet

Jusqu'à présent vous avez créé un dépot git contenant uniquement des fichiers de tests. Dans la suite, nous allons nous servir de ce dépot pour y placer les fichiers du projet.

Le principe consiste à ce que l'un des étudiants (uniquement Student1, ou uniquement Student2, mais pas les deux) remplace les fichiers de son dépot git par une version initiale du projet d'où vous allez partir.

Les fichiers que vous devez déposer sur ce répertoire sont l'ensemble des fichiers sources nécessaire à la compilation chez chacun des étudiants. Cela comprend des fichiers de votre scène, mais également l'ensemble de la bibliothèque CGP. Par contre, vous ne devez pas placer sur votre dépot git les fichiers temporaires issus de la compilation (ex. les répertoire build/) puisque ceux-ci n'ont pas à être partagés entre vous et viendrait générer des conflits à chaque mise à jour.

Vous pouvez réaliser cette préparation de fichiers de bases:

- Soit en copiant vous-même les bons fichiers et répertoires de code dans votre répertoire git. La scène d'où vous allez partir peut être n'importe quelle scène de TD. Vous pouvez alors copier le répertoire souhaité et le renommer avec votre nom de projet.
- Soit en récupérant cette archive inf443_project.zip d'un code minimaliste contenant: la bibliothèque CGP (sans les exemples), une scène de base dans le répertoire scenes_inf443/project.

Une fois mis en place, votre répertoire git devra avoir cette architecture:

Remarques:

- Vérifiez bien que le répertoire contenant cgp/ et scenes_inf44/ soit bien le répertoire de votre dépot git: présence du répertoire .git/. (sous Windows, vous devez activer la vue des fichiers cachés explicitement pour voir les répertoires commençant par un .).
- Ici, les fichiers sources de la scène de votre projet sera défini dans scenes_inf443/project/src/. D'autres configurations sont possibles, mais celle-ci correspond le plus directement à celle suivi en TD.
- Le fichier .gitignore est optionnel. Il permet d'indiquer à git d'ignorer certains fichiers ou répertoires - typiquement les fichiers temporaires issus de la compilation.
- Le fichier README.md est également optionnel. Il permet de décrire au format Markdown des informations qui apparaitront sur la page de votre dépot en ligne.

Envoie sur le dépot en ligne

Pour l'instant le projet n'est placé que sur l'ordinateur de l'un des étudiants. Il faut désormais ajouter les fichiers sur git et les synchroniser.

Remarque: Avant tout ajout de répertoire avec git, prenez soin de vérifier que ces répertoires ne contiennent que les fichiers sources nécessaires et pas de fichiers issus de la compilation.

Si vous avez testé la compilation de la scène dans ce répertoire, veillez à bien supprimer le répertoire build/ (ou à utiliser les scripts de "clean" en fonction de votre OS).

Ajout des répertoires sur git

git add cgp/
git add scenes_inf443/ 
git add .gitignore # si vous avez ce fichier
git add README.md  # si necessaire

Synchronization et envoi

git commit -a 
# ou git commit -m "Initialization project"

git push

Si tout se passe bien, les fichiers de votre projet devraient être visible sur le dépot en ligne.

Si vous avez des fichiers inutiles (ex. temp.cpp) issus des tests, vous pouvez les supprimer du dépot à l'aide de "git rm fileName"

Exemple:

git rm temp.cpp
git commit -m "Remove temp.cpp from repository"
git push

Synchronisation

Une fois le nouveau code placé en ligne, le second étudiant peut réaliser un "git pull" et vérifier qu'il arrive bien à récupérer le code.

Vous pouvez alors séparément compiler le code et commencer à éditer votre projet.

- Les fichiers temporaires issus de la compilation ne seront pas ajoutés au projet tant que vous ne le faites pas explicitement.
- Prenez soin de vous synchroniser régulièrement (commit/pull/push) afin de garder en permanence une version la plus à jour possible partagée.
- Si vous ajoutez des fichiers: code, assets, shaders, etc, n'oubliez pas de les ajouter au répertoire commun avec "git add".