5  Utiliser Git avec RStudio

5.1 Tâches concernées et recommandations

L’utilisateur souhaite se servir de Git avec RStudio pour suivre les modifications d’un projet RStudio.

Cette fiche est une introduction à l’usage de Git avec RStudio, pas une introduction générale à Git. Il est donc préférable que l’utilisateur ait une connaissance basique de Git avant de lire cette fiche. Si ce n’est pas le cas, il est conseillé de consulter la formation Travail collaboratif avec R. Il est également souhaitable de lire au préalable la fiche Configurer Git sur son poste de travail et de vérifier que les éléments de configuration de Git présentés dans cette fiche sont fonctionnels.

Tâche concernée et recommandation

Recommandations générales sur l’usage de Git

  • Utiliser systématiquement Git pour suivre les modifications des codes d’un projet RStudio ;
  • Ne jamais utiliser Git pour sauvegarder les données ;
  • Utiliser l’interface graphique de RStudio pour les usages courants de Git, plutôt que la ligne de commande ;

Vous pouvez utiliser Git via la ligne de commande si vous le souhaitez. En revanche, il est très fortement déconseillé d’exécuter une commande qui comprendrait les termes force ou rebase.

Recommandations sur l’initialisation de Git

  • Il est recommandé d’utiliser Git dès le lancement de votre projet, même s’il est possible de commencer à suivre un projet déjà existant avec Git.
  • Il est recommandé de commencer par créer un dépôt distant sur une forge (Gitlab, Github…), puis de cloner ce dépôt pour travailler sur votre poste local.
  • Il est recommandé de renseigner immédiatement le fichier .gitignore afin d’exclure certains fichiers du suivi des modifications (notamment les fichiers de données).

Recommandations sur l’usage des branches

  • Utiliser RStudio pour créer une branche ou naviguer entre les branches ;
  • Utiliser les interfaces Github ou Gitlab pour fusionner deux branches. Sur ce point, vous pouvez consulter la formation Travail collaboratif avec R.

5.2 Glossaire des termes techniques

Terme technique Signification
branche Ligne de développement parallèle au sein du dossier
checkout Déplacement vers une branche et mise à jour de celle-ci
clone Serveur distant ayant une copie de repository
commit Modification validée à un instant donné, par extension état du projet à cet instant
forge Espaces où sont disponibles des dépôts pour des projets collaboratifs
fetch Mise à jour du dépôt local par rapport à l’état du dépôt distant, sans procéder à la fusion
hash Identifiant unique pour chaque commit, contenant notamment un horodatage
merge Fusion de une ou plusieurs branches
pull Récupération des nouveaux commits en local depuis le remote
pull request Demande de fusion de branches sur github (équivalent aux merge request de gitlab)
push Envoi de ses nouveaux commit vers le remote
remote Serveur distant ayant une copie de repository
rebase Déplacement des commits d’une branche vers une autre. C’est une pratique dangereuse, à éviter !
repository Dossier partagé qui contient toutes les informations
fork Copie d’un projet disponible sur un dépôt distant permettant de modifier un projet sans affecter le dépôt d’origine

Schéma illustratif d’un processus utilisant R, Git et Gitlab

5.3 Pourquoi utiliser Git

Tous les statisticiens se sont déjà demandés (ou ont demandé à leurs collègues) :

  • quelle était la bonne version d’un programme ;
  • qui était l’auteur d’un bout de code en particulier ;
  • si un changement était important ou juste un essai ;
  • comment fusionner deux versions du même programme modifié par deux personnes différentes ;
  • comment travailler à plusieurs sur les mêmes codes…

La réponse à toutes ces questions est : utiliser Git. Git est un outil qui permet de suivre en détail les évolutions d’un projet impliquant du code informatique, et qui facilite l’archivage des codes et la collaboration entre agents. Les avantages de Git sont multiples :

  • Git contient l’historique de toutes les modifications apportées à un fichier ;
  • Git permet de revenir facilement à une version antérieure d’un fichier ;
  • Git permet de travailler à plusieurs en même temps sur les mêmes fichiers, de façon cohérente et sans risque de confusion ;
  • Git permet de proposer des modifications sur des fichiers et les discuter, sans pour autant modifier la dernière version existante…
  • Git fonctionne avec tous les langages informatiques (R, Python, SAS, LaTeX, C/C++, Java, etc.) et n’est pas spécifique à R.

En un mot, Git est le bon outil pour partager des codes et travailler à plusieurs sur un projet statistique (études ou production). Si vous n’êtes pas encore convaincu, une liste plus longue des raisons d’utiliser Git est disponible ici.

Note

Cette fiche décrit l’utilisation de Git au travers de l’interface graphique RStudio, car celle-ci facilite l’apprentissage de Git pour les débutants. Toutefois, utiliser cette interface n’est nullement obligatoire, et il est possible de réaliser l’ensemble des gestes présentés dans cette fiche avec des lignes de commande. Pour les utilisateurs intéressés par la ligne de commande, le nom de la commande git concerné sera systématiquement mentionné.

5.4 Initialiser l’usage de Git dans un projet RStudio

Il est nettement préférable de commencer à suivre les modifications d’un projet RStudio avec Git dès la création du projet. Il est toutefois possible de commencer à suivre les modifications du projet à n’importe quel moment.

5.4.1 Initialiser l’usage de Git à la création d’un projet

5.4.1.1 Etape 1 : Créer le dépôt distant sur la forge

La première étape consiste à créer un dépôt vide sur la forge. C’est grâce à ce dépôt que vous allez pouvoir partager des codes avec vos collègues ou stocker vos codes personnels. Deux points sont importants sur la création du dépôt distant :

  • Cette étape ne doit être réalisée qu’une seule fois par projet. En particulier, vous n’avez pas à recréer de dépôt distant si vous changez d’ordinateur, ou si les contributeurs du projet changent.
  • Il se peut que le dépôt distant existe déjà, par exemple si vous rejoignez un projet existant, ou si un de vos collègues a déjà créé le dépôt. En ce cas, vous pouvez passer directement à l’étape 2.

La marche à suivre pour créer un dépôt distant est très similaire dans Gitlab et dans Github. Les seules différences entre les deux plateformes portent sur la dénomination (un dépôt s’appelle repository sur Github et project sur Gitlab) et sur l’endroit où il faut cliquer pour créer un dépôt :

  • Sur Gitlab, il suffit de cliquer sur New project dans la partie supérieure de la fenêtre :

  • Sur Github, il suffit de cliquer sur l’icône + en haut à droite (cadre rouge), puis sur New repository (flèche noire) :

Dans les deux cas, vous devez préciser quelques caractéristiques du dépôt :

  • le nom du dépôt ;
  • la visibilité du dépôt (privé ou public) ;
  • le contenu de départ du dépôt : le dépôt peut être créé vide, avec un fichier README minimal, ou selon un modèle de dépôt (template). Il est conseillé de créer le dépôt avec un fichier README.

5.4.1.2 Etape 2 : Récupérer l’url du dépôt distant

La deuxième étape consiste à récupérer l’adresse du dépôt distant. Cette adresse se termine toujours par .git. Par exemple, l’adresse du dépôt de la documentation utilitR est https://github.com/InseeFrLab/utilitR.git.

Pour récupérer cette adresse, vous devez d’abord vous rendre sur la page du projet sur la forge (comme Gitlab ou Github). Pour afficher l’adresse du dépôt, il faut ensuite cliquer sur un bouton déroulant à droite. Sur Gitlab, il s’agit du bouton Clone (bouton bleu) :

Sur Github, il s’agit du bouton Code (bouton vert) :

Choisir la méthode d’authentification désirée, SSH ou HTTPS (cf. fiche XXXX). Par la suite, nous allons supposer qu’on utilise une authentification HTTPS.

5.4.1.3 Etape 3 : Créer un projet RStudio en clonant le dépôt distant

La troisième étape consiste à cloner le dépôt distant (git clone) c’est-à-dire à créer un projet RStudio sur votre poste local qui est une copie du dépôt distant (voir fiche XXXX pour plus de détails sur les projets RStudio). Cliquer sur File > New Project..., puis choisissez la troisième option (Version Control) :

Il faut alors renseigner trois champs dans la fenêtre suivante :

  • Repository URL : coller l’adresse du dépôt distant récupérée à l’étape précédente ;
  • Project directory name : choisir le nom du dossier local qui contiendra le projet RStudio ;
  • Create project as subdirectory of : : définir l’emplacement de votre dépôt local dans l’aborescence de votre poste. Il est possible de modifier cet emplacement en cliquant sur le bouton Browse.

Après avoir validé, RStudio ouvre un projet RStudio. Si RStudio ne mentionne aucune erreur, un nouvel onglet portant le nom de Git doit normalement apparaître en haut à droite :

5.4.2 Initialiser l’usage de Git dans un projet RStudio déjà existant

Bien qu’il soit recommandé d’utiliser Git dès la création d’un projet RStudio, il est également possible de commencer à utiliser Git pour suivre les modifications d’un projet RStudio déjà existant. Vous pouvez utiliser cette méthode lorsque vous avez commencé à travailler seul sur un projet RStudio, et que vous souhaitez le partager avec des collègues ou mieux suivre les modifications du projet.

Spécificité Insee

La méthode décrite ci-dessous n’est applicable que dans AUS, pas sur le SSP-Cloud.

5.4.2.1 Etape 1 : Initialiser le suivi des modifications du projet RStudio

La première étape consiste à initialiser l’utilisation de Git dans le projet RStudio en exécutant la fonction usethis::use_git() du package usethis. Cette fonction met en place l’environnement informatique permettant d’utiliser Git sur votre poste local. En revanche, elle ne crée pas de lien entre votre projet local et un dépôt distant.

usethis::use_git()

Cette fonction réalise deux opérations :

  • elle crée automatiquement tous les fichiers de configuration nécessaires au bon fonctionnement de Git dans le projet sur lequel vous travaillez ;
  • elle effectue un premier commit (voir cette section) pour valider la création de ces fichiers de configuration.

La fonction usethis::use_git() va finalement vous proposer de sauvegarder les fichiers qui figurent déjà dans votre projet (par exemple, les codes R et les fichiers csv présents dans votre projet). Si vous avez des fichiers qui ne doivent pas être sous contrôle de version (notamment des données), il est préférable de refuser cette possibilité (en choisissant le chiffre qui correspond à “Non” parmi la liste de choix), puis de procéder comme ceci :

5.4.2.2 Etape 2 : Créer le dépôt distant sur la forge

Cette étape est identique à celle qui est décrite dans la section Créer le dépôt distant sur la forge.

5.4.2.3 Etape 3 : Mettre en place le dépôt distant

La troisième étape consiste à établir un lien entre votre projet local et un dépôt distant (git add remote). Dans le langage Git, le dépôt distant s’appelle un remote. Pour créer ce lien avec l’interface de RStudio, il faut se rendre dans la partie destinée à la gestion des branches sur laquelle la partie RStudio et les branches revient plus en détails.

Après avoir cliqué sur ce bouton, dans la fenêtre s’ouvrant, cliquer sur Add remote :

Dans cette nouvelle fenêtre, deux champs sont à renseigner :

  • Remote name : le nom du dépôt distant. Par convention, on utilise le nom origin (mais vous pouvez lui donner un autre nom) ;
  • Remote URL : l’url du dépôt distant (cette adresse se termine par .git, voir plus haut).

A ce stade, Git est maintenant capable de contrôler les versions des fichiers locaux et d’interagir avec le dépôt. L’environnement nécessaire pour pouvoir réaliser les opérations usuelles, présentées dans la partie Suivre les modifications avec RStudio est ainsi opérationnel.

5.4.3 Exclure certains fichiers du suivi de modifications

Certains fichiers peuvent ou doivent être exclus du suivi des modifications. En particulier, les fichiers suivants doivent toujours être exclus du suivi des modifications :

  • les fichiers de données (csv, SAS, Excel, txt…) ;
  • les fichiers de sortie (pdf, html, csv…) ;
  • le fichier .Renviron (voir la fiche [Personnaliser la configuration de R]) ;
  • les codes contenant des informations confidentielles (comme les mots de passe, les tokens ou les clés d’API).

Les fichiers exclus du suivi des modifications sont répertoriés dans un fichier nommé .gitignore. Si le projet a été créé selon l’une des deux méthodes décrites précédemment, RStudio a créé automatiquement un fichier .gitignore dans le dossier du projet, et ce fichier contient par défaut les lignes suivantes :

.Rhistory
.RData
.Rproj.user

Il est souvent nécessaire d’ajouter des lignes au fichier .gitignore pour exclure certains fichiers du suivi des modifications. Pour éditer le fichier, il suffit d’exécuter la commande usethis::edit_git_ignore(scope = "project"). Par exemple, vous pouvez ajouter les lignes suivantes pour exclure tous les fichiers de format csv, SAS et Excel du suivi des modifications :

*.csv
*.sas7bdat
*.xls
*.xlsx

Il est également conseillé d’exclure les fichiers pouvant être produits par des documents R Markdown (notamment les fichiers pdf et html). Par exemple, pour exclure tous les fichiers de formats PDF et HTML, les lignes suivantes suffisent :

*.html
*.pdf

Dans l’onglet Git, RStudio propose également un bouton Ignore qui permet d’éditer le fichier .gitignore directement dans une interface graphique.

Cette fenêtre s’affiche ensuite dans RStudio :

Note

Le site https://www.toptal.com/developers/gitignore fournit un certain nombre de modèles de fichiers .gitignore selon le type de projet associés à Git. Vous pouvez également utiliser ce modèle pour constituer une base de départ.

5.5 Suivre les modifications d’un projet RStudio avec Git

5.5.1 Présentation de l’interface RStudio

RStudio permet d’utiliser Git via une interface graphique, accessible dans l’onglet Git situé en haut à droite de la fenêtre RStudio.

C’est grâce à cette interface que vous pourrez effectuer la plupart des opérations Git courantes, qui sont présentées ci-dessous. Les principales commandes de cette interface sont les suivantes :

  • Commit : valider les modifications d’un ou plusieurs fichier(s) ;
  • Pull : récupérer sur le dépôt distant les modifications apportées au projet par d’autres contributeurs ;
  • Push : partager sur le dépôt distant les modifications que vous avez apportées au projet ;
  • History : consulter l’historique des modifications du projet ;
  • More : ajouter des fichiers à ignorer ou revenir en arrière ou utiliser le terminal ;
  • New Branch : créer une nouvelle branche dans le dépôt Git ;
  • le menu déroulant tout à droite permet de changer de branche.
Note

Si l’onglet Git n’apparaît pas dans la fenêtre RStudio, c’est que votre projet RStudio n’est pas encore configuré pour utiliser Git. Reportez-vous à la section Initialiser l’usage de Git dans un projet RStudio.

5.5.2 Repérer les modifications apportées au projet avec RStudio

L’onglet Git vous indique le statut des différents fichiers avec une petite icône colorée à gauche du nom du fichier (dans le cadre rouge) :

Voici les statuts les plus courants :

(modified) : les modifications de ce fichier sont suivies par Git, et le fichier a été modifié depuis la dernière fois que ses modifications ont été sauvegardées dans l’historique de Git ; *

(deleted) : les modifications de ce fichier sont suivies par Git, et le fichier a été supprimé (ou éventuellement renommé) depuis la dernière fois que ses modifications ont été sauvegardées dans l’historique de Git ; *

(unknown) : les modifications de ce fichier ne sont pas suivies par Git (autrement dit, ce fichier n’est pas sauvegardé).

5.5.3 Sauvegarder les modifications de vos fichiers

5.5.3.1 Principe

Lorsqu’on souhaite sauvegarder les modifications faites à un ou plusieurs fichiers, il est nécessaire d’effectuer deux opérations :

  • git add : sélectionner les modifications qui vont être ajoutées à l’historique des modifications de Git (dont le nom technique est index) ;
  • git commit : valider les modifications choisies à l’étape précédente et ajouter une entrée à l’index de Git.

Les modifications ne seront enregistrées qu’à l’issue de ces deux opérations, que vous pouvez réaliser soit avec la ligne de commande, soit avec l’interface RStudio. La suite de cette section détaille la marche à suivre avec l’interface RStudio.

Supposons qu’un fichier source a été modifié et qu’on souhaite valider ces modifications. Ci-dessus, le dépôt comporte plusieurs fichiers modifiés. On souhaite valider les modifications apportées au fichier 03_Fiches_thematiques/Fiche_git_utilisation.Rmd et ajouter le fichier pics/git/onglet_git1.png.

5.5.3.2 Etape 1 : Sélectionner les modifications à sauvegarder

La première étape (git add) consiste à sélectionner les fichiers dont on veut sauvegarder les modifications. Pour ce faire, il faut cliquer sur la case vide à gauche du nom du fichier. Cela change le statut des fichiers :

Il est évidemment possible de sélectionner plusieurs fichiers. Les modifications à sauvegarder ont été sélectionnées, et sont maintenant dans la salle d’attente. Deux statuts supplémentaires peuvent apparaître lorsqu’on sélectionne des modifications à sauvegarder :

(added) : un nouveau fichier est ajouté à l’historique de Git ; *

(renamed) : un fichier a été renommé, et l’opération de changement de nom est sélectionnée.

5.5.3.3 Etape 2 : Valider la sauvegarde des modifications

La seconde étape (git commit) consiste à valider les modifications choisies à l’étape précédente. Pour ce faire, il faut cliquer sur le bouton commit, situé au-dessus de la liste des fichiers modifiés. En cliquant sur ce bouton, une nouvelle fenêtre s’ouvre :

Les modifications apportées à chaque fichier sont résumées ligne à ligne dans la partie inférieure (suppressions en rouge, ajouts en vert). Pour valider ces modifications (commit), il faut écrire un message qui décrit la nature des modifications sauvegardées (dans le cadre vert) puis cliquer sur le bouton commit (ovale rouge). Une fenêtre s’ouvre alors et confirme que la modification a été sauvegardée :

5.5.4 Consulter l’historique d’un dépôt ou d’un fichier

Il est possible, depuis RStudio, de consulter la liste des modifications apportées à un dépôt en cliquant sur le bouton History (cadre rouge). En ligne de commande, il faudrait taper git log pour obtenir une information équivalente.

Cette action ouvre une fenêtre avec la liste des with_def("commits") réalisée sur la branches (voir plus bas pour la notion de branches), avec les modifications apportées par chaque commit. Cette interface permet de balayer rapidement les modifications apportées aux fichiers, par exemple pour retrouver à quel moment une ligne de code a été modifiée.

5.5.5 Revenir en arrière sur un fichier

Après avoir cliqué sur le bouton en forme d’écrou, RStudio propose un second bouton Revert qui permet d’annuler les dernières modifications effectuées sur un fichier. Ce bouton peut être pratique si vous souhaitez reconstituer rapidement l’état d’un fichier tel qu’il était enregistré lors du dernier commit.

En revanche, si vous souhaitez revenir à un état plus ancien d’un fichier, il n’existe pas de bouton dans RStudio pour faire cela et il faut dans ce cas utiliser les lignes de commande Git grâce au terminal.

5.6 Interagir avec le dépôt distant

Après avoir effectué des opérations sur son dépôt local, on peut effectuer deux opérations pour interagir avec le dépôt distant. Les boutons dans RStudio illustrent bien les opérations en question :

  • pull

: récupérer les modifications présentes sur le dépôt distant ; * push

: envoyer les modifications faites en local sur le dépôt distant.

Lorsque vous partagez les modifications que vous avez apportées au projet, vos modifications viennent s’ajouter à la dernière version commune disponible (celle qui figure dans le dépôt commun). C’est pourquoi il est nécessaire que votre dépôt local soit à jour de toutes les modifications partagées par les autres contributeurs avant de partager vos modifications. Il faut donc toujours récupérer la dernière version du projet sur le dépôt distant (en cliquant sur pull) avant d’envoyer des modifications (en cliquant sur push).

Note

Les icônes de l’onglet Git sont placées dans l’ordre des actions à réaliser afin de publier un code sur un dépôt distant : (add), rwith_def(“commit”), <abbr title="Récupération des nouveaux commits en local depuis le remote"><b>pull</b></abbr>,r with_def("push")

Il peut arriver que d’autres contributeurs aient partagé sur le dépôt distant des modifications du projet en même temps que vous avez apporté des modifications à votre copie locale du projet. Lorsque vous récupérez les modifications présentes sur le dépôt distant avec pull, Git essaie de fusionner automatiquement vos modifications avec celles des autres contributeurs. Il peut néanmoins arriver que ces modifications soient incompatibles, par exemple si deux modifications portent sur la même ligne du même fichier : c’est un conflit de version. En cas de conflit, Git indiquera que la fusion automatique a échoué et vous demandera de choisir par vous-mêmes la bonne version des codes : vous devez alors résoudre un conflit de version. Plus de détails sont disponibles dans la formation Travail collaboratif avec R.

5.7 RStudio et les branches

5.7.1 La notion de branche

Les branches sont l’une des fonctionnalités les plus puissantes de la gestion de version. La création de branches dans un projet permet de développer des codes sans modifier la version de référence des codes, et donc de faire cohabiter dans un projet plusieurs versions des mêmes codes sans risque de confusion. Git propose également des fonctions pour fusionner facilement des versions différentes des mêmes codes. Deux points sont particulièrement importants :

  • Dans un projet collaboratif, il existe une branche particulière, appelée le plus souvent main ou master, qui joue le rôle de version de référence. C’est autour d’elle que se développent les branches.
  • Les modifications faites sur les codes dans une branche n’altèrent pas la version de référence (celle de la branche master) tant qu’il n’y a pas de fusion entre branches (merge).

5.7.2 Créer et utiliser des branches avec RStudio

La partie droite de l’interface git de RStudio permet de travailler avec des branches.

Cette interface offre principalement deux fonctions :

  • Créer une nouvelle branche (cadre orange) : si vous cliquez sur ce bouton, une boîte de dialogue s’ouvre, dans laquelle vous devrez définir le nom de la nouvelle branche L’instruction correspondante en ligne de commande est git checkout -b ma-branche, où ma-branche est le nom de la nouvelle branche Deux points sont à noter:
    • La branche source, à partir de laquelle la nouvelle branche diverge, sera celle sur laquelle vous vous situez au moment de la création.
    • Il est recommandé de se placer sur master avant chaque création de nouvelle branche.
  • Naviguer parmi les branches (cadre bleu) : le menu déroulant affiche d’abord la liste des branches disponibles dans votre dépôt local (LOCAL BRANCHES) puis la liste des branches existantes sur le dépôt distant (REMOTE: ORIGIN). Pour afficher le contenu d’une branche, il suffit de cliquer sur le nom de cette branche. L’instruction correspondante en ligne de commande est git checkout ma-branche, où ma-branche est le nom de la branche dont vous souhaitez afficher le contenu.
Note

L’interface graphique de RStudio ne permet pas de réaliser toutes les opérations possibles sur les branches. En particulier, il n’est pas possible de fusionner des branches avec cette interface. Les interfaces des forges (telles que Gitlab, Github…) sont beaucoup plus adaptées pour mener ce type d’opération. Vous pouvez en apprendre davantage en consultant la formation Travail collaboratif avec R.

5.8 Utiliser le terminal

Utiliser Git avec la ligne de commande permet de faire davantage de choses qu’avec l’interface RStudio. Grâce à elle, on peut par exemple corriger une maladresse, ou fusionner des branches sans utiliser l’interface d’une forge. L’utilisation de la ligne de commande est toutefois moins facile pour les débutants.

L’utilisation de la ligne de commande n’est pas plus risquée que l’interface RStudio, à condition de respecter une règle simple : il ne faut jamais exécuter une commande qui comprend les termes force ou rebase. En effet, ces options peuvent créer des conflits insolubles, voire rendre le projet inutilisable par vos collaborateurs.

Pour ouvrir un terminal Git, cliquer sur l’écrou dans l’onglet Git:

Cette action ouvre un terminal Git bash permettant de taper :

  • des commandes Linux, par exemple ls (lister les fichiers) ;
  • des commandes Git, par exemple git status (lister l’état des fichiers dans Git).

Vous pouvez en apprendre davantage sur l’utilisation de la ligne de commande dans la formation Travail collaboratif avec R ).

5.9 Pour en savoir plus