Introduction à GitLab

Connecter RStudio à GitLab et assurer le suivi de version

R
RStudio
GitLab
Author

Jonathan Kitt

Published

December 12, 2022

Introduction


Git, GitHub et GitLab


Lorsqu’on travaille sur des données ou qu’on rédige un rapport, on peut rapidement se retrouver avec beaucoup de fichiers aux noms plus ou moins explicites : fichier.txt, fichier2.txt, fichier2_modifs.txt, fichier2_version1.txt, … Difficile de s’y retrouver !


Dessing de PHDComics


Git est un gestionnaire de versions, gratuit et open source qui permet de garder une trace de toutes les modifications apportées à un fichier.

Git vous permet de “figer” l’état de votre répertoire de travail à un instant donné à l’aide de commits.

Vous pourrez ainsi naviguer dans l’historique des modifications d’un fichier, savoir quand une modification a été faite et en quoi consiste cette modification.

Vous pourrez revenir à un état antérieur de votre fichier en remontant dans l’historique des modifications.

Git vous permet également de travailler sur des branches. La branche principale sur laquelle se situe votre travail “propre” se nomme la branche master. Vous pouvez créer une seconde branche pour effectuer des tests, faire du développement, tout en laissant intacte la branche master. Vous pourrez inclure les modifications apportées sur la seconde branche dans la branche master en les fusionnant : c’est ce qu’on appelle un merge.

Git vous permet également de faire une sauvegarde de vos modifications sur un serveur distant : Github ou Gitlab. Ces outils permettent de travailler à plusieurs sur un même projet, de synchroniser vos répertoires locaux et distants, de partager votre code, …


Installer git


Windows


Cliquez sur ce lien pour télécharger et installer la dernière version de git pour Windows. Lors de l’installation, laissez les paramètres par défaut.


Linux


Pour installer git sur Linux, suivez les instructions sur ce lien.


MacOS


Pour installer git sur MacOS, suivez les instructions sur ce lien.


Premiers pas avec git


Ouvrez RStudio, et cliquez sur Tools > Global Options > Git/SVN.

Assurez-vous que la case Enable version control interface for RStudio projects est cochée, et que le chemin vers l’exécutable git est bien renseigné. Si ce n’est pas le cas, cliquez sur Browse et indiquez-le. Validez en cliquant sur Apply.


Créez un nouveau projet RStudio.


Workflow git en ligne de commande


Dans votre session RStudio, ouvrez un terminal :


Tapez la ligne de commande suivante pour afficher la version de git installée sur votre ordinateur :

git --version


Paramétrer git


Dans un premier temps, nous allons paramétrer git en renseignant un nom d’utilisateur et un e-mail qui seront utilisés pour nous identifier dans l’historique (cela nous permettra si nous travaillons à plusieurs sur un même projet de savoir qui a fait quoi). Dans la suite du turoriel nous verrons comment connecter RStudio à GitLab, nous allons donc utiliser nos identifiants LDAP :

git config --global --user.name "Prenom Nom"  
git config --global --user.email prenom.nom@inrae.fr

Assurez-vous que ces paramètres ont bien été pris en compte :

git config --global --list


Initialiser git


Votre répertoire de travail (le projet RStudio) n’est pour le moment pas versionné.

Il vous faut pour cela associer un répertoire git à votre répertoire de travail, en initialisant git :

git init

Assurez-vous que le répertoire git a bien été créé. La commande ls permet de lister les fichiers du répertoire actuel, et les options -la permettent d’afficher le détail (droits, date, …) et d’inclure les dossiers cachés (dont le nom commence par un point .)

ls -la


Ignorer des fichiers


Parmi les fichiers et répertoires listés ci-dessus, le répertoire .Rproj.user n’a pas besoin d’être versionné. Nous allons pour cela ajouter à notre répertoire de travail un fichier dans lequel nous pourrons lister les fichiers et répertoires que git devra ignorer.

Créez un fichier texte basique en cliquant sur File > New File > Text File. Sauvegardez ce fichier à la racine de votre répertoire de travail en le nommant .gitignore. Ajoutez une ligne à ce fichier :


Vérifiez l’état dans lequel se trouve votre répertoire :

git status


Le terminal affiche plusieurs informations :

  • On branch master : vous vous trouvez sur la branche principale (la seule pour le moment)

  • No commits yet : vous n’avez pas encore figé l’état de votre répertoire à l’aide d’un commit

  • Untracked files : des fichiers non versionnés sont présents dans le répertoire de travail

  • nothing added to commit but untracked files present : résumé des lignes précédentes

  • use “git add” to track : pour figer l’état de ces fichiers et tracer l’historique des modifications, nous utiliserons la commande git add.


Pour afficher également les fichiers ignorés, utilisez la commande git status --ignored.


Ajouter des fichiers (git add)


Pour versionner des fichiers, vous pouvez les ajouter à l’aide de la commande git add :

  • soit en précisant les noms des fichiers les uns à la suite des autres

  • soit à l’aide du symbole * pour ajouter tous les fichiers présents dans le répertoire de travail

  • soit à l’aide d’un point . pour ajouter l’ensemble du répertoire actuel

# Ajouter les fichiers un a un
git add .gitignore tutoriel_git.Rproj

# Ajouter tous les fichiers du repertoire de travail
git add *
  
# Ajouter le répertoire actuel
git add .

Affichez l’état de votre répertoire à l’aide de la commande git status. Vous remarquerez que les noms des fichiers ajoutés apparaissent en vert.


De nouvelles informations sont affichées dans le terminal :

  • No commits yet : les fichiers ont été ajoutés mais leur état n’a pas encore été figé par un commit

  • Changes to be commited : liste des fichiers ajoutés mais pas encore figés


La commande à utiliser pour annuler l’ajout des fichiers est indiquée :

# Annuler l'ajout de fichiers un par un
git rm --cached .gitignore tutoriel_git.Rproj

# Annuler l'ajout de tous les fichiers du repertoire de travail
git rm --cached *


rm -r

L’argument -r permet de supprimer de façon récursive un dossier.


Figer l’état du répertoire (git commit)


Nous allons maintenant figer l’état de notre répertoire de travail à l’aide de la commande git commit -m .... Un commit est toujours associé à un message (-m) à écrire entre guillemets ("message") pour préciser ce que nous faisons. Soyez le plus précis possible dans vos messages de commits, cela vous permettra de vous y retrouver dans l’historique des modifications !

Dessin de @xkcd


Effectuez le premier commit à l’aide de la commande suivante :

git commit -m "premier commit"

Si vous tapez git status dans le terminal, celui-ci affiche nothing to commit, working tree clean. Cela indique que votre commit a bien été effectué.


La commande git log permet d’afficher l’historique de votre répertoire :

  • commit ### (HEAD -> master) vous donne l’identifiant unique du commit (qu’on appelle hash) et indique où pointe votre dernier commit (sur la branche master)

  • auteur (avec les identifiants renseignés plus haut), date et message du commit


Ajoutez un fichier README dans votre répertoire : File > New File > Markdown File. Ajoutez une ligne et sauvegardez le fichier à la racine de votre répertoire :


Ajoutez ce fichier et effectuez un commit :

git add README.md
git commit -m "ajout d'un fichier README.md"

Affichez l’historique de vos commits à l’aide de la commande git log.


Ajoutez une ligne de texte dans votre fichier README.md et sauvegardez-le :

Tapez les commandes suivantes :

git add README.md
git commit -m "ajout d'une ligne de texte dans le fichier README.md"


Créer une branche (git branch)


Les branches vous permettent de travailler sur vos fichiers sans impacter la branche principale.

Créez une branche “dev” : git branch dev.

Pour afficher les différentes branches, utilisez la commande git branch :

L’astérisque indique la branche sur laquelle vous vous situez.

Pour changer de branche, utilisez la commande git checkout <nom-de-la-branche> ou git switch <nom-de-la-branche>.

Exécutez les commandes suivantes :


Pour supprimer une branche, utilisez la commande git branch -d <nom-de-la-branche>. Avant de pouvoir supprimer la branche dev, il faut se placer sur la branche master.


La commande git checkout -b <nom-de-la-nouvelle-branche> permet de créer une branche et de s’y placer.


Pour créer une nouvelle branche à partir d’un commit précis, précisez l’identifiant du commit : git checkout -b <nom-de-la-branche> <commit_id>. Utilisez cette commande pour créer une branche dev au niveau de l’avant-dernier commit de votre historique.


Modifiez le fichier README.md sur la branche dev :

Effectuez un add + commit sur cette branche dev :

git add README.md
git commit -m "modification du fichier README.md sur la branche dev"


En naviguant entre les branches à l’aide de git checkout (ou de git switch) pour afficher l’historique avec git log, vous remarquerez que l’historique varie en fonction de la branche.


Fusionner les branches et résoudre les conflits (git merge)


Une fois que vous avez terminé de travailler sur votre branche dev, vous pouvez “rapatrier” les modifications apportées sur cette branche sur votre branche master.

Placez-vous sur la branche master : git checkout master.

Pour fusionner la branche dev sur la branche master, utilisez la commande git merge dev :

Le terminal nous indique qu’il y a un conflit : le fichier README.md diffère entre les deux branches. Il vous faut résoudre ce conflit avant de pouvoir fusionner les deux branches.


Regardons à quoi ressemble notre fichier README.md :

  • Les marqueurs de conflit indiquent le début (<<<<) et la fin (>>>) du conflit

  • Les noms des branches sont indiqués à côté de ces marqueurs de conflit

  • L’indicateur ===== montre la séparation entre les modifications des deux branches

Il vous incombe de choisir quelle version conserver : supprimez les indicateurs <<<, >>> et === et ne gardez que le texte présent dans le fichier de la branche dev.


Vérifiez l’état de notre branche master à l’aide de la commande git status :

Les deux branches ne sont pas fusionnées, mais les modifications ont bien été prises en compte.


Ajoutez le fichier README.md et effectez un commit :

git add README.md
git commit -m "resolution de conflit entre les branches master et dev"

En affichant l’historique avec git log vous verrez maintenant l’ensemble des commits effectués sur les deux branches.

Vous pouvons maintenant supprimer la branche dev : git branch -d dev


Workflow git en “clique-bouton”


Nous allons voir comment effectuer les mêmes étapes à l’aide de l’interface RStudio.

Créez un nouveau projet RStudio.


Initialiser git


Pour initialiser git, cliquez sur Tools > Project Options, puis dans le menu Git/SVN sélectionnez Git :

Dans les fenêtres qui s’ouvrent, cliquez sur Yes.

RStudio redémarre, et vous remarquerez la présence d’un onglet Git dans votre espace de travail. En cliquant dessus, vous verrez qu’un fichier .gitignore a été ajouté automatiquement :


Initialiser git lors de la création d’un projet

Lorsque vous créez un nouveau projet RStudio, vous pouvez cocher la case Create a git repository


Ajouter des fichiers


Pour ajouter des fichiers, cochez-les dans l’onglet git. Leur statut change et une icône A (pour added) s’affiche à côté des noms de fichiers.

Sélectionner plusieurs fichiers

Quand vous travaillez avec beaucoup de fichiers versionnés, vous pouvez tous les sélectionner : cliquez sur le nom d’un des fichiers dans l’onglet git, puis utilisez la combinaison Ctrl + A et enfin cochez la case à côté du premier fichier.


Les fichiers présents dans l’onglet Git de votre espace de travail peuvent avoir différents statuts :

nouveau fichier
fichier ajouté
fichier modifié
fichier supprimé


Effectuer un commit


Cliquez sur Commit.


Dans la fenêtre qui s’ouvre, écrivez le message du commit et cliquez à nouveau sur Commit.


En cliquant sur l’icône horloge vous pouvez voir l’historique de nos commits.


Créer une branche


Vous pouvez créer une nouvelle branche en cliquant sur l’icône à gauche du nom de la branche actuelle, en précisant le nom et en cliquant sur Create :


Vous pouvez maintenant naviguer entre les branches en cliquant sur leurs noms :

Limites de l’approche clique-bouton

L’onglet Git dans l’interface RStudio ne vous permettra pas d’effectuer les opérations suivantes, pour lesquelles vous devrez passer par la ligne de commande :

  • revenir à un commit précédent

  • créer une branche à partir d’un commit précis

  • résoudre des conflits entre branches


Connecter RStudio à GitLab


Nous avons jusqu’ici utilisé git en local pour suivre les modifications apportées à des fichiers sur notre ordinateur.

Nous allons voir comment connecter RStudio à Gitlab afin de pouvoir :

  • synchroniser nos répertoires entre plusieurs ordinateurs
  • travailler à plusieurs sur un même projet
  • rapatrier en local un répertoire distant pour travailler dessus

Le répertoire distant présent sur Github ou Gitlab s’appelle le remote.

La première chose à faire est de créer un paire de clés SSH qui nous permettra de communiquer entre notre ordinateur et le serveur distant Gitlab.


Créer des clés SSH


Dans RStudio, puis cliquez sur Tools > Global Options > Git/SVN.

Si aucune clé n’est indiquée dans SSH key, cliquez sur Create SSH Key ….

Dans SSH key type, sélectionnez RSA puis validez en cliquant sur Create.


Cliquez sur View public key et copiez la clé qui s’affiche.


Paramétrer GitLab


Ouvrez ce lien dans votre navigateur internet et cliquez sur Connexion SSO.

Dans le menu déroulant, choisissez INRAE et cliquez sur Sélectionner. Dans le menu suivant, renseignez les champs à l’aide de votre identifiant LDAP puis cliquez sur Se connecter.


Cliquez sur l’icône dans le coin supérieur droit puis sur Preferences.

Dans la barre de menu à gauche, cliquez sur la première icône en forme de clé. Collez dans le champ Key la clé SSH copiée dans RStudio.

Le champ Title devrait se remplir automatiquement. Si ce n’est pas le cas, renseignez ce champ.

Vous pouvez choisir une date d’expiration de votre clé dans Expiration date.

Pour terminer, cliquez sur Add key. Assurez-vous que votre clé apparaisse bien en bas de la page sous Your SSH keys.


Exporter un répertoire local vers Gitlab

Nous allons exporter vers Gitlab le projet RStudio existant.


Dans GitLab

Dans la barre de menu supérieure, cliquez sur l’icône plus et sélectionnez New project/repository. Dans le menu suivant, choisissez Create blank project.


Dans le menu Create blank project, remplissez les différents champs :

  • Project name : le même nom que votre projet RStudio.

  • Project URL : en fonction des groupes dont vous faites partie, vous pourrez choisir l’emplacement du projet. Pour l’instant, choisissez votre espace utilisateur.

  • Project slug : identique au nom du projet.

  • Visibility Level : qui a accès au projet. Pour notre exemple, choisissez Public.

  • Project Configuration : décochez la case Initialize repository with a README.

Cliquez sur Create project.


Dans la fenêtre qui s’ouvre, vous verrez une liste de commandes :

  • Git global setup : nous l’avons fait au début du tutoriel

  • Create a new repository : télécharger votre répertoire Gitlab en local

  • Push an existing folder : exporter un dossier local vers Gitlab

  • Push an existing Git repository : exporter un répertoire Git local vers Gitlab (c’est ce qui nous intéresse)


Dans RStudio

Dans votre projet, ouvrez un terminal, et exécutez les lignes de commande suivantes (vous pouvez les copier directement depuis Gitlab) :

git remote add origin git@forgemia.inra.fr:<prenom.nom>/<nom_projet>.git
git push -u origin --all

Si c’est la première fois que vous vous connectez à Gitlab depuis RStudio, vous verrez un message dans le terminal vous demandant si vous êtes certain de vouloir continuer la connexion. Tapez yes et appuyez sur Entrée.

Le terminal vous indiquera des détails comme le nombre de fichiers à exporter et la progression de la connexion.


Dans l’onglet Git de RStudio, deux flèches sont maintenant accessibles :

  • Flèche bleue pour récupérer en local les dernières modifications du répertoire distant (Pull)

  • Flèche verte pour exporter les dernières modifications effectuées en local sur le serveur distant (Push)

Si vous rafraîchissez votre page Gitlab, les fichiers .gitignore, README.md et <nom_projet>.Rproj devraient apparaître.


Importer un répertoire distant vers RStudio


Nous allons voir comment importer un répertoire distant présent sur Gitlab vers notre ordinateur. Fermez votre sessions RStudio et supprimez le dossier contenant le projet local sur votre ordinateur.


Dans Gitlab


Sur la page d’accueil du répertoire, cliquez sur Clone puis copiez le lien SSH :


Dans RStudio


Ouvrez une nouvelle session RStudio. Dans la barre de menu supérieure, cliquez sur File > New project.

Dans la fenêtre Create Project, choisissez Version Control.

Dans la fenêtre Create Project from Version Control, choisissez Git.

Dans la fenêtre Clone Git Repository, remplissez les champs :

  • Repository URL : collez le lien SSH copié dans GitLab

  • Project directory name : se remplit automatiquement

  • Create project as subdirectory of : emplacement où sera créé le projet

Cochez la case Open in New Session dans le coin inféreur gauche de la fenêtre et cliquez sur Create Project.


Le projet s’ouvre dans une nouvelle fenêtre.


Cloner un répertoire distant en ligne de commande

Vous pouvez également cloner le répertoire distant en ligne de commande, en utilisant le lien SSH copié dans Gitlab. Placez-vous au niveau du dossier dans lequel vous souhaitez cloner le répertoire à l’aide de la commande cd (pour change directory puis utilisez la commande git clone).

cd <dossier-dans-lequel-cloner>
git clone git@gitlab.com:<user-id>/<nom-du-projet>


Commit, pull, push


Lorsque nous travaillons uniquement en local, le workflow git se limite aux opérations suivantes :

  • ajouter des fichiers

  • effectuer des commits

  • créer des branches, fusionner des branches et résoudre les conflits


Quand nous travaillons en synchronisant notre répertoire local avec un répertoire distant (remote), deux opérations s’ajoutent au workflow :

  • pull pour récupérer en local les modifications apportées dans le répertoire distant

  • push pour exporter les modifications apportées dans le répertoire local vers le répertoire distant


De manière générale, si vous travaillez seul et que vous utilisez le répertoire distant pour garder une copie de votre travail sur votre serveur, vous n’aurez pas vraiment besoin d’effectuer des pull.

Si vous travaillez sur plusieurs ordinateurs, par exemple un ordinateur de bureau et un ordinateur portable de télétravail, les commandes pull et push vous seront très utiles : vous exporterez la version la plus récente de votre répertoire sur le répertoire distant à l’aide d’un push, et vous récupérerez cette dernière version sur votre deuxième ordinateur à l’aide d’un pull.

Si vous travaillez à plusieurs sur un même projet, ces utiliserez ces commandes pull et push très fréquemment : - pour travailler en local avec les dernières modifications apportées par vos collègues
- pour que vos collègues travaillent dans leurs répertoires locaux avec vos dernières modifications


Gestion des branches locales et distantes


Créer une branche en local et l’exporter


Dans votre projet RStudio, créez une nouvelle branche que vous appelerez dev.

Assurez-vous que la case Sync branch with remote est bien cochée et cliquez sur Create.


Pour exporter la branche dev sur Gitlab, ouvrez un terminal et tapez la commande suivante :

git push --set-upstream origin dev


Les différentes branches locales et distantes apparaissent maintenant dans l’onglet git dans RStudio :

En rafraîchissant votre page Gitlab vous verrez que la branche dev a bien été exportée :


Dans RStudio, placez-vous sur la branche dev et modifiez le fichier README.md :

Effectuez un add - commit - push de cette modification.

Fusionner des branches sur le serveur distant

Dans Gitlab, cliquez sur 2 branches puis sur dev. Vous remarquerez que le fichier README.md contient bien la dernière modification apportée en local. Cliquez ensuite sur Create merge request : nous allons fusionner les deux branches et inclure les modifications apportées à la branche dev dans la branche master.


Merge request et Pull request

Il s’agit de la même opération, qui porte deux noms différents selon qu’on utilise Github (Pull request) ou Gitlab (Merge request).


Dans la fenêtre New merge request renseignez un titre (normalement pré-rempli avec le message du dernier commit) et une description. Soyez le plus explicite possible : vous saurez précisément ce que vous avez fait et les collègues qui travaillent sur le même projet auront toutes les informations nécessaires.


Dans la suite de la fenêtre, vous pouvez renseigner plusieurs champs :

  • Assignee : qui doit valider la requête

  • Reviewer : solliciter une vérification de la part d’autres personnes

  • Milestone : vous pouvez préciser une date limite

  • Labels : pour ajouter des étiquettes à vos requêtes

Dans Merge options, vous pouvez choisir de supprimer la branche source quand la requête sera acceptée (Delete source branch when merge request is accepted, case cochée par défaut) et d’écraser les commits (case décochée par défaut).


Dans la fenêtre suivante, cliquez sur Approve (cette étape n’est pas obligatoire) puis sur Merge pour valider la fusion des branches.

Une fois la fusion terminée, revenez sur la page d’accueil du répertoire sur Gitlab : il n’y a qu’une branche et le fichier README.md contient bien les dernières modifications.


Dans RStudio, placez-vous sur la branche master et cliquez sur Pull. Votre répertoire local est désormais à jour.

Cependant, les branches dev locale et distante sont toujours présentes dans l’onglet Git de RStudio …

Pour les supprimer, utilisez les commandes suivantes :

git fetch -p
git branch -d dev

Rafraîchissez l’onglet Git, il ne devrait rester que la branche master locale et distante.