13 mai 2015 Fabricɛ Dɛssaint Inra - UMR Agroécologie, Dijon 13 mai 2015 Version 4 (Rstudio : version 0.98.1103 ; Git : version 1.9.5) Cette note présente l utilisation du gestionnaire de version Git via une interface graphique proposée par l environnement de développement (IDE) RStudio. Sommaire 1.1 Introduction.................................... 1 1.1.1 Pourquoi utiliser un gestionnaire de versions............ 1 1.1.2 Les types de gestionnaires de versions................ 2 1.2 Installer et configurer Git............................ 2 1.2.1 Installation................................ 2 1.2.2 Configuration............................... 3 1.3 Utilisation avec RStudio............................ 3 1.3.1 Activer Git................................. 3 1.3.2 Créer un projet.............................. 4 1.3.3 Choisir les éléments à suivre...................... 5 1.3.4 Enregistrer les modifications...................... 6 1.3.5 Visualisation d un fichier........................ 8 1.3.6 Suppression/déplacement d un fichier................ 9 1.3.7 Réparer une erreur............................ 9 1.3.8 Visualiser l historique.......................... 10 1.1 Introduction Un système de gestion de versions est un outil logiciel qui permet entre autres, de garder une trace datée des modifications faites sur un ou des fichiers dans un ou des répertoires. Les fichiers peuvent être de différents types mais l outil offre plus de possibilités lorsque ce sont des fichiers «texte» comme un script R, un fichier LATEX ou Sweave, un fichier de données au format.csv, un fichier.html, etc. Plusieurs programmes de gestion de versions sont disponibles (Subversion, mercurial, etc.). Nous présentons ici, une partie des fonctionnalités du logiciel et l interface graphique proposée par RStudio. 1.1.1 Pourquoi utiliser un gestionnaire de versions La création d un document suit généralement un parcours linéaire où les différentes versions du document se succèdent depuis un état initial jusqu à un état final en passant par différentes versions intermédiaires.
Etat initial Etat 1 Etat 2... Etat final Fichier 1 Fichier 2 Fichier 3 Fichier n Fichier N A la fin du travail, il ne reste que la version finale. Généralement, on ne peut pas revenir en arrière et repartir d une ancienne version. Avec un système de gestion de version, on va pouvoir «remonter» le temps et retrouver les modifications faites entre 2 versions plus ou moins éloignées et rétablir une version antérieure. Etat initial Etat 1 Etat 2... Etat final Fichier 1 Fichier 2 Fichier 3 Fichier n Fichier N 1.1.2 Les types de gestionnaires de versions Il existe plusieurs catégories de gestionnaires de versions. Leur description ainsi que leurs avantages et inconvénients ne seront pas évoqués dans ce document. On trouve assez facilement ces informations sur Internet. RStudio intègre une interface graphique pour l utilisation de 2 systèmes de gestion de versions : le système Git et le système Subversion. Ici nous présentons l interface pour le système Git. Un présentation plus complète est donnée par Pro Git book. 1.2 Installer et configurer Git 1.2.1 Installation Pour installer Git vous devez télécharger la version correspondant à votre système d exploitation à l adresse http://gitscm.com/downloads. Windows On commence par télécharger la dernière version disponible pour le système d exploitation. Pour windows, c est la version 1.9.5 (avril 2015). L installation se fait à partir du fichier associé, en l occurrence, Git-1.9.5-preview20150319.exe, en une dizaine d étapes. 2
FIGURE 1.1 Principaux écrans affichés lors de l installation de Git sous Windows 1.2.2 Configuration Préalablement à l utilisation de Git, il faut le configurer. La configuration se fait en ligne de commande via une fenêtre Terminal. Dans un certain nombre de cas, cette étape n est pas nécessaire (la configuration a déjà été faite). git config --global user.name "votre nom" git config --global user.email "adresse mèl" git config -l 1.3 Utilisation avec RStudio Comme tout nouvel outil, l utilisation d un gestionnaire de versions nécessite un apprentissage mais les opérations de base sont simples et relativement peu nombreuses. Avec quelques efforts on va pouvoir : gagner du temps lors de la mise au point de programmes. On peut, par exemple, essayer une autre approche, modifier une portion de code, etc. Le gestionnaire de versions vous permet d annuler les modifications effectuées ; suivre les modifications réalisées sur les fichiers et éventuellement revenir à d anciennes versions ; mutualiser un travail collectif sur des programmes communs : fichiers de données, programmes R, etc. Les modifications des uns et des autres pouvant être suivies. 1.3.1 Activer Git Sous RStudio, avant de pouvoir utiliser Git, il faut activer la gestion de versions. Pour cela, cliquer sur Tools Globals options... et choisir le panneau Git/SVN (Figure 1.2). Il suffit ensuite de cocher Enable version control interface for RStudio projects et de renseigner les cases avec le chemin de l exécutable du (des) système(s) de gestion de versions. Sur certains systèmes d exploitation (OSX, Ubutu, 3
FIGURE 1.2 Activation du système de gestion de versions (a) OSX Maverick ; (b) Windows 8) en particulier), ces informations peuvent être déjà renseignées pour les programmes présents sur la machine. Il faut enfin redémarrer RStudio. Remarque : Le choix de Git ou de SVN peut se faire de façon globale pour l ensemble des futurs projets ou au cas par cas en fonction des projets. 1.3.2 Créer un projet Dans le RStudio, la création d un dépôt Git ne peut se faire que dans le cadre d un projet. La création d un projet se fait via le menu File New Projects.... Trois options sont alors possibles (Figure 1.3a) : New Directory le projet est créé dans un répertoire qui n existe pas. Trois types de projets sont proposés par RStudio (Figure 1.3b) Empty Project : création d un projet RStudio. Cette option est à utiliser pour les projets classiques contenant des scripts R, des fichiers de données, etc. R Package : création d un package R. Le répertoire créé va contenir une structure bien particulière qui est celle recommandée pour la création de packages R. Shiny Web Application : création d une application Shiny. De la même façon que précédemment, le répertoire possède une structure particulière. Existing Directory les données sont déjà dans un répertoire et on souhaite simplement bénéficier des facilités du mode Projet de RStudio. Version Control le projet est un clone d un dépôt existant sur un site externe Git ou Subversion. Pour l exemple, on va créer notre projet, Exemple.Rproj dans un nouveau répertoire, Exemple (Figure 1.4). Dans la fenêtre qui s ouvre, il suffit ensuite de renseigner le nom du répertoire et sa localisation pour créer le projet. 4
(a) (b) FIGURE 1.3 Origine et type de projet Si on souhaite lui associer localement un dépôt Git et donc utiliser le gestionnaire de versions, il faut cocher Create a git repository puis valider avec le bouton Create project. Cette validation crée le répertoire et les différents éléments constituant le projet et le dépôt Git. On va copier dans ce répertoire, un fichier de données au format.txt, Mesures.txt et créer un programme R, Exercices.Rhtml. Remarque : la création d un projet n implique pas nécessairement la création d un dépôt Git!! Pour indiquer à RStudio que la création des projets s accompagne systématiquement de la création d un dépôt Git, on utilise alors le menu Tools Project Options... et le panneau Git/SVN. 1.3.3 Choisir les éléments à suivre Le répertoire créé pour notre nouveau projet contient, outre les 2 fichiers copiés, 2 nouveaux fichiers (affichage via le volet Files ). On a donc 4 fichiers dans ce répertoire :.gitignore : un fichier de configuration de Git Mesures.txt : le fichier de données Exercices.Rhtml : le script R Exemple.Rproj : un fichier de configuration créé par RStudio contenant différentes informations sur le projet FIGURE 1.4 Création d un projet dans un nouveau répertoire 5
On retrouve les mêmes fichiers dans le volet Git deux icônes de Statut. mais ils sont associés à une case à cocher (colonne Staged) et à FIGURE 1.5 Liste des fichiers et leur statut pour Git Au lancement du projet, tous les éléments du répertoire sont munis de l icône que les fichiers sont connus de Git mais ne sont pas suivis (Untracked).? (Figure 1.5). Cette icône signifie Indication des fichiers à suivre Pour indiquer à Git, les fichiers que l on veut suivre, il suffit de cocher la case de la colonne Staged. Pour l exemple, on va suivre les modifications faites sur le fichier Exemple.R et le fichier Donnees.csv. Lorsque l on coche la case, le statut du fichier change ainsi que l icône. FIGURE 1.6 Modification du statut : ajout des fichiers au dépôt Git On a maintenant l icône A (Figure 1.6). Cette icône symbolise le fait que le fichier est à ajouter à la liste des fichiers à suivre. Le fichier sera (Added) au dépôt Git. Cependant, cet ajout n interviendra que lors du prochain commit. Si vous souhaitez ignorer (de façon permanente) des fichiers dans le dépôt, il faut les ajouter au fichier.gitignore. Pour cela, la façon la plus simple, consiste à utiliser l item Ignore situé dans le menu représenté par une roue bleue. Cette action ouvre le fichier.gitignore et il suffit d ajouter le nom des fichiers que l on veut ignorer. On peut aussi sélectionner les fichiers puis ouvrir le menu contextuel (clic droit) et sélectionner l item Ignore.... Pour notre exemple, on va ignorer les fichiers Exemple.Rproj et.gitignore. Ces fichiers disparaissent de l affichage dans le volet Git (ils sont encore présents et visibles dans le volet Files ). 1.3.4 Enregistrer les modifications L enregistrement d un nouveau fichier ou le suivi des modifications réalisées sur un fichier suivi s appelle un commit. C est en quelque sorte une capture, un instantané du contenu du fichier à un moment donné. C est l utilisa- 6
teur qui décide quand il fait cette capture. L intérêt de ce type d opération c est que l on peut revenir à l une des versions précédentes ou visualiser les modifications faites entre différents commits. Pour créer un commit avec RStudio, on va utiliser le bouton Commit. On va faire un premier état des fichiers Exercices.Rhtml et Mesures.txt. La fenêtre Commit est constituée de 3 parties (Figure 1.7). : FIGURE 1.7 Premier commit sur le fichier Exercices.Rhtml et le fichier Mesures.txt En haut à gauche, la liste et le statut des différents fichiers présents dans le répertoire. Dans cette fenêtre, on peut indiquer que l on ne souhaite pas enregistrer les modifications sur un fichier en décochant la case de la colonne Staged. En haut à droite, une partie commentaire pour documenter les modifications faites. Cette information est obligatoire. En bas, le contenu du fichier sélectionné dans la liste avec éventuellement les différentes versions et leurs différences. Dans notre exemple, c est le premier enregistrement et il n y a donc qu une version. On valide le commit avec le bouton Commit. Une fois la validation faite, les fichiers disparaissent de l affichage dans le volet Git. Idéalement chaque commit doit être minimal et complet. Minimal. Un commit ne devrait comporter que des changements relatifs à un seul problème (correction d une fonction, ajout d un graphique, etc). Cette façon de faire simplifie la compréhension des modifications réalisées et facilite la rédaction du commentaire. Si on a plusieurs problèmes, on procède à plusieurs commits. Complet. Un commit doit solutionner le problème qu il est censé solutionner et peut de ce fait contenir un test unitaire confirmant que le problème est résolu. Les commentaires associés au commit doivent être concis mais suffisamment descriptifs. On doit être capable de comprendre ce qu il fait et ce qui a été fait. De même, ils doivent décrire le pourquoi plus le quoi. On peut toujours retrouver ce qui a été modifié par comparaison des versions. 7
1.3.5 Visualisation d un fichier On modifie le fichier Exercices.Rhtml et le fichier Mesures.txt et on enregistre les modifications. Les 2 fichiers réapparaissent dans le volet Git avec une nouvelle icône de statut : M (Figure 1.8). FIGURE 1.8 Modification du statut d un fichier suivi. Cette icône indique que le fichier a été modifié (Modified). A ce stade, il n y a pas encore eu d enregistrement des modifications dans le dépôt Git. Le logiciel signale simplement que le fichier a été modifié. L icône placée à droite indique que Git a noté que le fichier a été modifié depuis le dernier commit. Pour lui indiquer que les modifications sont à enregistrer lors du prochain commit, il faut cocher la case dans la colonne Staged. L icône se déplace et apparait dans la colonne de gauche. On procède ensuite à un nouveau commit sur le fichier Exercices.Rhtml. Cette fois, on peut visualiser les modifications faites sur ce fichier (Figure 1.9). FIGURE 1.9 Commit sur un fichier déjà suivi Les lignes modifiées apparaissent sur un fond coloré : les lignes de l ancienne version sont sur un fond en rouge alors que celles de la nouvelle version sont sur un fond en vert. On peut aussi utiliser les numéros de lignes présents dans les colonnes situées sur la gauche : la première colonne correspond au fichier le plus ancien alors que la deuxième se rapporte au plus récent. 8
Une partie des lignes qui n ont pas été modifiées sont aussi affichées. Elles définissent le contexte : on peut en afficher un plus ou moins grand nombre avec la case de choix Context (5 lignes par défaut). Cette information permet la localisation des parties qui ont été modifiées. Sur cet exemple, on peut voir que le script R a été modifié en ligne 9, 23 et 26. 1.3.6 Suppression/déplacement d un fichier On va ajouter un répertoire pour stocker les données. On le crée via le volet Files : on l appelle Data, puis on déplace le fichier Mesures.txt dans ce nouveau répertoire. Git, on voit que le fichier Mesures.txt est maintenant doté d une nouvelle icône D (Fi- Si on ouvre le volet gure 1.10). FIGURE 1.10 Statut d un fichier déplacé 1.3.7 Réparer une erreur L un des avantages des systèmes de gestion de versions réside dans le fait que l on peut revenir sur une version précédente. Pour cela, il suffit de faire un clic droit sur le fichier dans le volet Git et de choisir dans le menu contextuel, l item revert. Cette opération annule les changements réalisés depuis le dernier commit. Remarque : cette opération est irréversible! On peut aussi avoir besoin de revenir à la précédente version pour une partie du document uniquement. Pour cela, on se place dans la fenêtre contenant les modifications faites sur le fichier et on utilise le bouton unstage 9
situé au dessus de la ligne/bloc dont on souhaite annuler les modifications. Cette opération peut être réalisée sur une ligne ou un bloc de lignes (Figure 1.11). FIGURE 1.11 Annulation des modifications faites sur une partie du document 1.3.8 Visualiser l historique On peut visualiser l historique des modifications faites sur un fichier. Pour cela on clique sur l icône en forme de «montre» dans la barre d outils du volet Git. La fenêtre ouverte donne une chronologie des modifications (Figure 1.12). FIGURE 1.12 Historique des modifications réalisées dans le répertoire Merci à Claire CHABANET, Annie BOUVIER, Sergueï SOKOL et Brigitte SCHAEFFER pour la relecture attentive de cette notice. 10