Git : guide d'utilisation de base

git est-ce que l'on appelle un « gestionnaire de version » qui permet de travailler de façon collaborative. Il nécessite le recours à un hébergeur qui stocke un dépôt de fichiers (« repository » en anglais), communément accessible à plusieurs utilisateurs. En guise d'hébergeur, vous pouvez recourir à l'instance GitLab fournie par l'EPFL : https://gitlab.epfl.ch/. Notez qu'il existe d'autres hébergeurs de dépôt, comme le célèbre, mais commercial GitHub, par exemple. Vous êtes libre d'utiliser un autre hébergeur à la seule condition que les travaux notés restent strictement privés.

Préambule

git est un outil très puissant, mais riche et complexe à utiliser dans toutes ses dimensions. Ce guide a pour but de vous permettre de l'utiliser à un niveau très simple et il faudra appliquer les conseils indiqués de façon rigoureuse pour éviter tout problème. Aucun soutien n'est en principe offert par l'équipe du cours en cas de problème non trivial sortant de ce cadre d'utilisation simple. Gérer de tels soucis peut en effet être chronophages et porter préjudice à l'aide que nous souhaiterions apporter sur les projets eux-mêmes.

Un système de gestion de version (« version control system » en anglais) est un programme permettant à plusieurs personnes de travailler en commun sur un projet. Il permet surtout de maintenir un historique complet des changements dans le projet ainsi que différentes versions vers lesquelles il est possible de revenir. Ainsi, il est utile d'y avoir recours même si l'on travaille seul.e.

Pour pouvoir travailler avec git, il faut que l'outil git soit installé sur la machine utilisée. C'est le cas des VMs de L'EPFL (en connexion à distance) ou sur les machines des salles de TP. Sinon, voir : https://git-scm.com/book/en/v2/Getting-Started-Installing-Git.

Nous supposons dans ce qui suit qu'Alice et Bob travaillent sur un projet commun et qu'Alice possède quelque part chez elle un répertoire, par exemple [chemin_vers_le_projet]/MP1-2023/, contenant déjà du code du projet.

Les commandes indiquées ci-dessous sont à taper dans un terminal ou une invite de commande.

SETUP INITIAL (à ne faire qu'une fois et uniquement par Alice)

Voici les manipulations que doit faire Alice (seulement elle et une seule fois) pour initialiser le projet avec git:

Créer un dépôt sur https://gitlab.epfl.ch (identification Tequila avec les identifiants Gaspar) en cliquant sur le + en haut à gauche :

et choisir l'option New project/repository.
Choisir l'option Create blank project.
Choisir un nom de projet, par exemple, cs107-2023-alice-et-bob, et laisser le niveau de visibilité à "private".
Décochez l'option permettant de créer automatiquement un fichier README:
Cliquer sur le bouton Create project en bas de page ceci crée un dépôt commun où placer le contenu à partager.

Dans les messages qui apparaîssent en haut de la fenêtre : "You won't be able to pull or push project code via HTTPS until you set a password on your account" Cliquer sur "set a password" et introduire un mot de passe de votre choix

Alice doit ensuite importer le contenu de [chemin_vers_le_projet]/MP1-2023/ dans ce dépôt. Pour cela, elle doit taper les commandes suivantes dans une invite de commande/terminal :

            cd [chemin_vers_le_projet]/MP1-2023/
            git init
            git add .
            git config --global user.email "‹your mail>"
            git config --global user.name "‹your name>"
            git commit -m "Initial import"
            git remote add origin https://gitlab.epfl.ch/alice/cs107-2023-alice-et-bob.git
            git push -u origin master

Taper ces commandes dans un terminal ou une invite de commande en remplaçant https://...cs107i-2023-bob-et-alice.git par l'adresse exacte associée à votre dépôt, et ne pas oublier le point à la fin de git add .

La dernière commande exigera de vous de taper le mot de passe que vous avez précédemment créé (utilisez votre user name gaspar).

Pour vérifier que tout est en ordre, Alice peut taper dans le terminal :

            git status .

et devrait obtenir :

            On branch master
            Your branch is up to date with 'origin/master'.

            nothing to commit, working tree clean

Le projet est alors configuré avec git.

Droits d'accès

Alice doit finalement donner le droit de contribution à Bob.

Dans la page https://gitlab.epfl.ch/.../cs107-2023-alice-et-bob/, sur le bandeau de gauche, cliquer sur Settings > General > Manage > members, puis:

Cliquer sur le bouton à droite Invite members.
Introduire l'adresse email epfl de Bob et lui attribuer le rôle Maintainer.
Puis cliquer sur le bouton Invite.

RÉCUPÉRATION DU PROJET (par Bob)

Le partenaire de travail d'Alice peut maintenant récupérer une copie du projet git chez lui. Pour cela, il lui suffit de se placer dans un répertoire choisi sur sa machine et récupérer le contenu du dépôt en tapant les commandes suivantes dans un terminal ou une invite de commande :

            cd chemin_vers_le_repertoire_choisi
            git clone https://gitlab.gnugen.ch/.../cs107-2023-alice-et-bob.git

(ne pas oublier de remplacer par l'adresse exacte chez vous)

Notez qu'Alice peut aussi faire la même chose sur une autre machine à elle.

Pour travailler sur le projet dans IntelliJ, il suffit d'ouvrir le répertoire du projet (dans notre exemple MP1-2023).

TRAVAIL ROUTINIER (Pour Bob et Alice)

Les instructions sont données en ligne de commande, mais elles peuvent, pour la plupart, être lancées dans IntelliJ, via le bouton Git.

À faire SYSTÉMATIQUEMENT à chaque fois que vous décidez de recommencer à travailler sur le projet :

            git pull

qui récupère les modifications faites par l'autre. Supposons que vous ayez ensuite modifié un fichier existant Main.java et que vous avez terminé et relu vos modifications:

            git pull
            git add Main.java
            git commit -m "commentaire explicatif sur la modification\ 
            (par exemple : ajouté un test sur la méthode getXthBit)" Main.java

(on peut omettre le nom du fichier si on a modifié plusieurs fichiers pour un patch) puis

            git push

qui permet de pousser/publier les modifications sur le dépôt commun. L'autre personne peut à ce moment récupérer les modifications au moyen d'un git pull)

ATTENTION: à partir du moment où un fichier ou dossier est sous git, IL NE FAUT PAS LE SUPPRIMER/DÉPLACER MANUELLEMENT du disque au risque de générer des conflits. De même ne changez pas manuellement la structure des dossiers de votre projet. Si vous voulez faire cela passer par les commandes ci-dessous.

Si on veut supprimer un fichier

            git rm nom_de fichier

ou si on veut déplacer un fichier ou un dossier:

            git mv nom_de_fichier_ou_dossier nouveau_nom_ou_repertoire_destination.

Annulation des modifications courantes

Si l'on a fait des modifications dans un fichier que l'on n'a pas encore ajouté au moyen de la commande git add, il est possible de les annuler avec :

            git checkout nomDuFichier

            git checkout

qui annule toutes les modifications (non ajoutées) sur tous les fichiers.

Conflits

Un souci récurrent avec git est l'occurrence de conflits dont certains sont très pénibles à résoudre. Vous pouvez éviter ces derniers en:

Adhérant strictement au protocole indiqué ci-dessus pour le travail routinier
En vous concertant avant de travailler : git ne vous dispense pas de communiquer sur qui prend la main sur quelle partie du projet et à quel moment
Finalement, en ne partageant pas ce qui est spécifique à chacun (fichier .class, fichiers de configuration, etc.).

Le dernier point est particulièrement important. Afin d'éviter des conflits sur les fichiers exécutables ou issus de la compilation, il est préférable de les exclure de git. Pour ce faire, il suffit d'ajouter au projet, un fichier .gitignore qui indique tout ce qu'il faut exclure.

Ce cours vous fournit d'emblée un fichier .gitignore pour chaque projet. Jetez un œil dessus pour voir comment il se rédige. Si vous devez en générer un par vous-même, vous trouverez un exemple typique de contenu ici.

Bonnes pratiques

Pour pouvoir tirer le meilleur parti de Git et du travail collaboratif, il est recommandé d'adhérer à la discipline suivante:

Ne pousser que du code qui compile
Ne pas ajouter les fichiers .class ou les des fichiers de configurations spécifiques à sa machine (un bon fichier .gitignore devrait faire l'affaire).
Faire des publications (commit) atomiques: c'est à dire ne pas ajouter un ensemble important de modifications d'un coup avec un seul gros (commit), mais plutôt publier, comme un tout, l'ensemble des modifications liées à une petite correction/ajout donné. Par exemple, si deux fonctionnalités ont été ajoutées au code, on les publiera par le biais de deux commit séparés, plutôt que comme un seul gros commit incluant les deux.

Commandes utiles

Voici deux commandes très utiles pour savoir où vous en êtes :

            git status

(ou git status . pour connaitre le status du répertoire courant)

Dans IntelliJ, le status est donné par des couleurs (rouge pour fichier non recensé, bleu pour fichier recensé et localement modifié, etc.), donc il n'y a pas directement besoin de cette commande.

git status vous dit où vous en êtes de vos commits, etc. Par exemple :

            On branch master
            Your branch is up-to-date with 'origin/master'.
            Untracked files:
            (use "git add ‹file>..." to include in what will be committed)

                crypto-stegano/MyNewFile.java

            nothing added to commit but untracked files present (use "git add" to track)

veut dire que :

Ma « branche » de référence dans le dépot local s'appelle « master » ; vous pouvez l'ignorer, nous n'utiliserons pas les branches dont nous n'allons pas du tout parler
qu'elle est actuellement synchronisée ('up to-date') avec le dépot commun qui s'appelle ici `origin/master` (ce nom ne changera pas) ;
mais qu'il y a un nouveau fichier (« untracked file ») : fichier existant chez moi, mais non recensé dans git;
et ce qu'il faut faire si je veux l'ajouter : « use git add ... » Si ce fichier est pertinent, il faut l'ajouter comme indiqué plus haut. Sinon il faut ignorer simplement le message ou détruire le fichier sans passer par git rm.

Après le git add, la commande git status donne:

            On branch master
            Your branch is up-to-date with 'origin/master'.
            Changes to be committed:
            (use "git reset HEAD ‹file>..." to unstage)

                new file:    crypto-stegano/myNewFile.java

une fois git commit fait (après avoir fait un `pull` comme conseillé plus haut) , git status donne:

            On branch master
            Your branch is ahead of 'origin/master' by 1 commit.
            (use "git push" to publish your local commits)
            nothing to commit, working directory clean

(et l'on termine par un push). Dans IntelliJ, le status est donné par des couleurs (rouge pour fichier non recensé, bleu pour fichier recensé et localement modifié, etc.), donc il n'y a pas directement besoin de cette commande. L'autre commande utile est :

            git log (ou git log .)

elle permet de voir tous les `commit` effectués et leur message. C'est-à-dire tout l'historique des modifications. Un synopsis des commandes usuelles est disponible ici (il s'agit d'une documentation de l'hébergeur GitHub, mais les commandes git sont partout les mêmes).

Accès pas ssh

L'accès aux données de votre dépôt par https (comme nous l'avons fait plus haut) est un peu pénible, car il exige d'entrer un mot de passe à chaque push. Pour simplifier cela, il faut ajouter à GitLab une clé ssh publique qu'il faut générer en suivant ces instructions: https://docs.gitlab.com/ee/user/ssh.htm. Une fois une clé ssh publique générée, il faut la fournir à GitLab :

Accéder à votre page https://gitlab.epfl.ch/votre_user_name;
Cliquer sur le bouton à droite en forme de crayon pour éditer votre profil
Dans le bandeau latéral gauche, sélectionner SSH Keys
Cliquer sur le bouton en haut à gauche Add new key et saisissez la clé (par copier-coller).

Le mot de la fin

git est un outil complexe, même pour un public averti, et très utile s'il est employé à bon escient. Mal utilisé, il peut en revanche rapidement vous faire perdre un temps précieux (voir des contenus de fichiers :-/). Son utilisation rigoureuse est donc très importante. Il s'agit du système de gestion de version le plus en vogue actuellement, ce qui présente plusieurs avantages, en particulier une documentation assez abondante — dont l'excellent livre Pro Git, disponible gratuitement — et plusieurs programmes facilitant son utilisation.

Ce document est publié pour la première fois cette année. Vos suggestions pour l'améliorer sont bienvenues sur le forum Ed du cours.