46  Contrôle de version et collaboration avec Git et Github

Ce chapitre présente un aperçu de l’utilisation de Git pour collaborer avec d’autres personnes. Des tutoriels plus complets peuvent être en bas de page dans la section Ressources.

46.1 Qu’est-ce que Git ?

Git est un logiciel de contrôle de version qui permet de suivre les modifications dans un dossier. Il peut être utilisé comme l’option “track change” dans Word, LibreOffice ou Google docs, mais pour tous les types de fichiers. C’est l’une des options les plus puissantes et les plus utilisées pour le contrôle de version.

Pourquoi n’en ai-je jamais entendu parler? Les personnes ayant une formation de développeur développeurs apprennent couramment à utiliser un logiciel de contrôle de version (Git, Mercurial, Subversion ou autres), peu d’entre nous issus de disciplines disciplines quantitatives sont enseignés ces compétences. Par conséquent, la plupart des épidémiologistes n’en Par conséquent, la plupart des épidémiologistes n’en ont jamais entendu parler au cours de leurs études, et doivent l’apprendre à la volée.

Attendez, j’ai entendu parler de Github, c’est la même chose? Pas exactement, mais vous les utilisez souvent ensemble, et nous vous montrerons comment faire. En bref :

  • Git est le système de contrôle de version, un logiciel. Vous pouvez l’utiliser localement sur votre ordinateur ou pour synchroniser un dossier avec un hôte site web. Par défaut, on utilise un terminal pour donner à Git en ligne de commande.

  • Vous pouvez utiliser un client/interface Git pour éviter la ligne de commande et et effectuer les mêmes actions (au moins pour les actions simples et super courantes). courantes).

  • Si vous souhaitez stocker votre dossier dans un site web hôte pour collaborer avec d’autres, vous pouvez créer un compte sur Github, Gitlab, Bitbucket ou autres.

Ainsi, vous pouvez utiliser le client/interface Github Desktop, qui utilise Git en arrière-plan pour gérer vos fichiers, à la fois localement sur votre ordinateur, et à distance sur un serveur Github.

46.2 Pourquoi utiliser le combo Git et Github ?

L’utilisation de Git facilite :

  1. L’archivage des versions documentées avec des modifications incrémentielles de sorte que vous afin que vous puissiez facilement revenir en arrière à n’importe quel état antérieur.
  2. Avoir des branches parallèles, c’est-à-dire des versions de développement/“de travail” avec des moyens structurés pour intégrer les changements après révision

Cela peut être fait localement sur votre ordinateur, même si vous ne collaborez pas avec d’autres personnes. avec d’autres personnes. Avez-vous déjà :

  • regretté d’avoir supprimé une section du code, pour réaliser deux mois plus tard que mois plus tard que vous en aviez réellement besoin ?

  • revenir sur un projet qui avait été mis en pause et tenter de se rappeler si vous aviez fait cette modification délicate dans l’un des éléments du projet. de vous rappeler si vous aviez fait cette modification délicate dans l’un des modèles ?

  • aviez un fichier model_1.R et un autre fichier model_1_test.R et un fichier model_1_not_working.R pour faire des essais ?

  • avait un fichier report.Rmd, un fichier report_full.Rmd, un fichier report_true_final.Rmd, un fichier report_final_20210304.Rmd, un fichier report_final_20210402.Rmd et maudit vos compétences en archivage ?

Git vous aidera dans tout cela, et vaut la peine d’être appris pour cette seule raison.

Cependant, il devient encore plus puissant lorsqu’il est utilisé avec un référentiel en ligne tel que Github pour soutenir des projets collaboratifs. Cela facilite :

  • la collaboration : d’autres personnes peuvent examiner, commenter, et accepter/refuser des modifications

  • Le partage de votre code, de vos données et de vos résultats, et l’invitation à faire des commentaires du public (ou en privé, avec votre équipe)

et évite :

  • “Oups, j’ai oublié d’envoyer la dernière version et maintenant vous devez refaire deux jours de travail sur ce nouveau fichier”.

  • Mina, Henry et Oumar ont tous travaillé en même temps sur un script et doivent doivent fusionner manuellement leurs modifications

  • Deux personnes tentent de modifier le même fichier sur Dropbox et Sharepoint et cela crée une erreur de synchronisation.

Cela semble compliqué, je ne suis pas un programmeur

Cela peut l’être. Les exemples d’utilisations avancées peuvent être assez effrayants. Cependant, un peu comme R, ou même Excel, vous n’avez pas besoin de devenir un expert pour profiter des avantages de l’outil. L’apprentissage d’un petit nombre de fonctions et de notions vous permet de suivre vos modifications, de synchroniser vos fichiers sur un référentiel en ligne et de collaborer avec vos collègues en très peu de temps.

En raison de la courbe d’apprentissage, le contexte d’urgence n’est peut-être pas le meilleur moment pour apprendre ces outils. Mais l’apprentissage peut se faire par étapes. Une fois que vous aurez acquis quelques notions, votre flux de travail peut être assez efficace et rapide. Si vous ne travaillez pas sur un projet où la collaboration avec des personnes peut-etre Git n’est pas une nécessité, mais c’est en fait un bon moment pour devenir l’utiliser en solo avant de vous lancer dans la collaboration.

46.3 Installation

Installer Git

Git est le moteur qui se cache derrière les coulisses de votre ordinateur, qui suit les changements, les branches (versions), les fusions et les retours en arrière. Vous pouvez d’abord installer Git de le lien ici: https://git-scm.com/downloads.

Installer une interface (facultatif mais recommandé)

Git possède son propre langage de commandes, qui peuvent être tapées dans un terminal de ligne de commande. Cependant, il existe de nombreux clients/interfaces et en tant que non-développeur, dans votre utilisation quotidienne, vous aurez rarement besoin d’interagir directement avec Git. L’interface Git fournit généralement des outils de visualisation agréables pour les modifications de fichiers ou les branches.

De nombreuses options existent, sur tous les systèmes d’exploitation, de plus simples aux plus complexes. Parmi les bonnes options pour les débutants, citons le volet Git de RStudio et le Github Desktop, que nous présenterons dans ce chapitre. Les options intermédiaires (plus puissantes, mais plus complexes) comprennent Source Tree, Gitkracken, Smart Git et d’autres programmes.

Trouvez un explication rapide sur les clients Git.

Remarque : comme les interfaces utilisent toutes Git en interne, vous pouvez en essayer plusieurs, passer de l’une à l’autre en fonction de vos besoins.

Comme indiqué ci-dessous, vous aurez occasionnellement avoir besoin d’écrire des commandes Git dans un terminal tel que le volet terminal de RStudio (un onglet adjacent à la Console R) ou le terminal Git Bash.

Compte Github

Créez un compte gratuit sur github.com.

Il se peut que l’on vous propose de configurer une authentification à deux facteurs avec une application sur votre téléphone. Pour en savoir plus, consultez le document Github help documents.

Si vous utilisez Github Desktop, vous pouvez entrer vos informations d’identification Gitub après l’installation en suivant ces étapes. Si vous ne le faites pas, les informations d’identification vous seront demandées ultérieurement lorsque vous tenterez de cloner un projet à partir de Github.

46.4 Vocabulaire, concepts et fonctions de base

Comme lors de l’apprentissage de R, il y a un peu de vocabulaire à retenir pour comprendre Git. Voici les bases pour vous aider à démarrer/ tutoriel interactif. Dans les prochaines sections, nous montrerons comment utiliser les interfaces.

Référentiel

Un référentiel Git (“repo”) est un dossier qui contient tous les sous-dossiers et fichiers de votre projet (données, code, images, etc.) et l’historique de leurs révisions. Lorsque vous commencez à suivre les changements dans le dépôt, Git créera un dossier caché qui contient toutes les informations de suivi. Un référentiel Git typique est votre dossier R Project (voir la page du manuel sur les Projets R).

Nous allons montrer comment créer (initialiser) un dépôt Gitub, Github Desktop ou Rstudio dans les sections suivantes.

Commits

Un commit est un snapshot du projet à un moment donné. Lorsque vous apportez un changement au projet, vous faites un nouveau commit pour suivre les modifications (le delta) apportées à vos fichiers. Par exemple, vous avez peut-être édité quelques lignes de code et mis à jour une jeu de données associé. Une fois que vos modifications sont enregistrées, vous pouvez regrouper ces changements en un seul “commit”.

Chaque commit a un ID unique (un hash). À des fins de contrôle de version, vous pouvez revenir en arrière dans votre projet en vous basant sur les commits, pars les garder relativement petits et cohérents. Vous joindrez également une brève description des modifications appelée “message de validation”.

Modifications organisées ? Mettre en scène les changements, c’est les ajouter à la zone de mise en scène en préparation pour le prochain commit. L’idée est que vous pouvez finement décider quels changements inclure dans un commit. Par exemple, si vous avez travaillé sur la spécification d’un modèle dans un un autre script, il serait judicieux d’avoir deux commits différents (ce serait plus facile au cas où vous voudriez annuler les changements sur la figure mais pas sur le modèle).

Branches

Une branche représente une ligne indépendante de changements dans votre repo, une version parallèle et alternative des fichiers de votre projet.

Les branches sont utiles pour tester les modifications avant qu’elles soient incorporées dans la branche principale, qui est généralement la version principale/finale/“live” de votre projet. Lorsque vous avez fini d’expérimenter sur une branche, vous pouvez apporter les changements dans votre branche principle, en la fusionnant, ou la supprimer, si les changements n’ont pas été couronnés de succès.

Note : vous n’avez pas besoin de collaborer avec d’autres personnes pour utiliser les branches, ni d’avoir un référentiel en ligne distant.

Dépôts locaux et distants

Cloner consiste à créer une copie d’un dépôt Git à un autre endroit.

Par exemple, vous pouvez cloner un dépôt en ligne de Github localement sur votre ordinateur, ou commencer par un dépôt local et le cloner en ligne en ligne sur Github.

Lorsque vous avez cloné un référentiel, les fichiers du projet existent à deux endroits :

  • le référentiel LOCAL sur votre ordinateur physique. C’est là que vous apportez les modifications réelles aux fichiers/codes.

  • le référentiel ROMPU, en ligne : les versions de vos fichiers de projet dans le dépôt Github (ou sur tout autre hébergeur).

Pour synchroniser ces dépôts, nous allons utiliser d’autres fonctions. En effet , contrairement à Sharepoint, Dropbox ou autre logiciel de synchronisation, Git ne met pas automatiquement à jour votre dépôt local en fonction de ce qui est en ligne,ou vice-versa. C’est vous qui choisissez quand et comment synchroniser.

  • git fetch télécharge les nouvelles modifications depuis le dépôt distant mais ne modifie pas votre dépôt local. Pensez-y comme une vérification de l’état du dépôt distant.

  • git pull télécharge les nouvelles modifications depuis les dépôts distants et met à jour votre dépôt local.

  • Lorsque vous avez fait un ou plusieurs commits localement, vous pouvez utiliser git push pour faire les commits vers le dépôt distant. Ceci envoie vos modifications sur Github afin que d’autres personnes puissent les voir et les tirer s’ils le souhaitent.

46.5 Démarrer : créer un nouveau dépôt

Il y a plusieurs façons de créer de nouveaux dépôts. Vous pouvez le faire à partir de la console, de Github, ou d’une interface.

Deux approches générales sont possibles :

  • Créer un nouveau projet R à partir d’un dépôt Github existant ou nouveau. (préféré pour les débutants), ou bien
  • Créer un dépôt Github pour un projet R existant.

Fichiers de démarrage

Lorsque vous créez un nouveau référentiel, vous pouvez éventuellement créer tous les fichiers ci-dessous, ou vous pouvez les ajouter à votre référentiel à un stade ultérieur. Ils se trouvent généralement dans le dossier “racine” du référentiel.

  • Un fichier README est un fichier que quelqu’un peut lire pour comprendre pourquoi votre projet existe et ce qu’il doit savoir pour l’utiliser. Il sera vide au début, mais vous pouvez le compléter plus tard.

  • Un fichier .gitignore est un fichier texte dont chaque ligne contient des dossiers ou fichiers que Git devrait ignorer (ne pas suivre les modifications). Lisez plus sur ce sujet et voir des exemples ici.

  • Vous pouvez choisir une licence pour votre travail, afin que les autres personnes sachent sous quelles conditions elles peuvent utiliser ou reproduire votre travail. Pour de plus amples informations, consultez la page Creative Commons licenses.

Créer un nouveau référentiel dans Github

Pour créer un nouveau dépôt, connectez-vous à Github et cherchez le bouton vert. Ce dépôt vide peut être cloné localement sur votre ordinateur (voir la section suivante).

Vous devez choisir si vous voulez que votre dépôt soit public (visible par tout le monde sur Internet) ou privé (seulement visible pour ceux qui ont la permission a acceder le dépôt). Cela a des implications importantes si vos données sont sensibles. Si votre référentiel est privé, vous rencontrerez certains quotas dans des circonstances particulières, par exemple si vous utilisez les actions de Github pour exécuter automatiquement votre code dans le nuage.

Clone à partir d’un dépôt Github

Vous pouvez cloner un référentiel Github existant pour créer un nouveau projet R local sur votre ordinateur.

Le dépôt Github peut être un dépôt qui existe déjà et contient du contenu, ou un dépôt vide que vous venez de créer. Dans ce dernier cas, vous créez essentiellement le repo Github et le projet local R en même temps (voir les instructions ci-dessus).

Remarque : si vous n’avez pas de droits de contribution sur un dépôt Github, il est possible de d’abord “forker” (creer une copie) le dépôt vers votre profil, et ensuite de procéder aux autres actions. La bifurcation est expliquée à la fin de ce chapitre, mais nous vous recommandons de lire les autres sections en premier.

Etape 1 : Naviguez dans Github jusqu’au dépôt, cliquez sur le bouton vert “Code”. et copier l’URL HTTPS clone (voir image ci-dessous)

L’étape suivante peut être effectuée dans n’importe quelle interface. Nous allons illustrer avec Rstudio et le bureau Github.

Dans Rstudio

Dans RStudio, démarrez un nouveau projet R en cliquant sur Fichier > Nouveau projet > Contrôle de version > Git.

  • Lorsque vous êtes invité à saisir l’“URL du dépôt”, collez l’URL HTTPS de Github.
  • Attribuez au projet R un nom court et informatif.
  • Choisissez l’endroit où le nouveau projet R sera enregistré localement.
  • Cochez “Ouvrir dans une nouvelle session” et cliquez sur “Créer un projet”.

Vous êtes maintenant dans un nouveau projet RStudio local qui est un clone du dépôt Github. Ce projet local et le dépôt Github sont maintenant liés.

Dans le bureau de Github

  • Cliquez sur Fichier > Cloner un référentiel.

  • Sélectionnez l’onglet URL

  • Collez l’URL HTTPS de Github dans la première case.

  • Sélectionnez le dossier dans lequel vous voulez avoir votre dépôt local.

  • Cliquez sur “CLONE”.

Nouveau repo Github à partir d’un projet R existant

Un autre scénario de configuration est que vous avez un projet R existant avec du contenu, et que vous voulez créer un dépôt Github pour celui-ci.

  1. Créez un nouveau dépôt Github vide pour le projet (cf. instructions ci-dessus).
  2. Clonez ce dépôt localement (voir les instructions HTTPS ci-dessus).
  3. Copiez tout le contenu de votre projet R (codes, données, etc.) dans ce nouveau dépôt local vide (utilisez le copier-coller, par exemple).
  4. Ouvrez votre nouveau projet dans RStudio, et allez dans le volet Git. Les nouveaux fichiers devraient s’enregistrer comme des modifications de fichiers, désormais suivies par Git. Par conséquent, vous pouvez regrouper ces modifications sous forme de commit et les pousser (push) vers Github. Une fois poussé (pushed), le dépôt sur Github reflétera tous les fichiers.

Voir la section sur le flux de travail Github ci-dessous pour plus de détails sur ce processus.

A quoi cela ressemble-t-il maintenant ?

Dans RStudio

Une fois que vous avez cloné un dépôt Github vers un nouveau projet R, vous voyez maintenant dans RStudio un onglet “Git”. Cet onglet apparaît dans le même volet de RStudio que votre environnement R :

Veuillez noter les boutons encerclés dans l’image ci-dessus, puisqu’ils seront référencés plus tard (de gauche à droite) :

  • Bouton pour commettre (commit) les modifications du fichier sauvegardé dans la branche locale (cela ouvrira une nouvelle fenêtre)
  • Flèche bleue pour tirer (pull, mettre à jour votre version locale de la branche avec avec les changements effectués sur la version distante/Github de cette branche)
  • Flèche verte pour pousser (push, envoyer tous les commits/modifications de votre version version locale de la branche vers la version distante/Github de cette branche)
  • L’onglet Git dans RStudio
  • Bouton pour créer une NOUVELLE branche en utilisant comme base la branche locale affichée. Vous voulez presque toujours créer une branche à partir de la branche principale (après la première extraction).
  • La branche dans laquelle vous travaillez actuellement
  • Les modifications que vous avez apportées au code ou à d’autres fichiers apparaissent ci-dessous

dans Github Desktop

Github Desktop est une application indépendante qui vous permet de gérer tous vos dépôts. Lorsque vous l’ouvrez, l’interface vous permet de choisir le dépôt sur lequel vous souhaitez travailler, puis d’effectuer les actions Git à partir de là.

46.5.1 Flux de travail Git + Github

Aperçu du processus

Une fois que vous avez terminé la configuration (décrite ci-dessus), vous aurez un Github qui est connecté (cloné) à un projet R local. La branche principale (créée par défaut) est la version dite “live” de tous les fichiers. Lorsque vous voulez faire des modifications, il est bon de créer une pratique de créer une nouvelle branche à partir de la branche principale (comme “créer une copie”). Il s’agit d’un flux de travail typique de Git, car la création d’une branche est facile et rapide.

Un flux de travail typique est le suivant :

  1. Assurez-vous que votre dépôt local est à jour, mettez-le à jour si ce n’est pas

  2. Allez sur la branche sur laquelle vous travailliez précédemment, ou créez une nouvelle branche

  3. Travaillez sur les fichiers localement sur votre ordinateur, faites un ou plusieurs commits à cette branche

  4. Mettre à jour la version distante de la branche avec vos modifications (push)

  5. Lorsque vous êtes satisfait de votre branche, vous pouvez fusionner la version en ligne de la branche de travail avec la branche “principale” afin de créer une nouvelle branche.

Les autres membres de l’équipe peuvent faire la même chose avec leurs propres branches, ou peut contribuer des commits dans votre branche de travail aussi.

Nous détaillons ci-dessous le processus, étape par étape.

Voici un schéma que nous avons développé - il se présente sous la forme d’un tableau à double sens, ce qui devrait aider les épidémiologistes à comprendre.

Voici un autre diagramme.

*Note : jusqu’à récemment, le terme de branche “master” était utilisé, mais on parle maintenant de branche “principale” (“master”).

Image source

46.6 Créer une nouvelle branche

Lorsque vous sélectionnez une branche sur laquelle travailler, Git réinitialise votre répertoire de travail comme il était la dernière fois que vous étiez sur cette branche.

Dans le volet Git de Rstudio

Assurez-vous que vous êtes dans la branche “principale”, puis cliquez sur l’icône violette pour créer une nouvelle branche (voir image ci-dessus).

  • Vous serez invité à nommer votre branche avec un nom descriptif en un mot (vous pouvez utiliser des caractères de soulignement si nécessaire).
  • Vous verrez que, localement, vous êtes toujours dans le même projet R, mais que vous ne travaillez plus sur la branche “principale”.
  • Une fois créée, la nouvelle branche apparaîtra également sur le site Github comme une branche.

Vous pouvez visualiser les branches dans le volet Git de Rstudio après avoir cliqué sur “Historique” (“History”).

Dans le bureau de Github

Le processus est très similaire, il vous est demandé de donner un nom à votre branche.Ensuite, il vous sera demandé de “Publier votre branche sur Github” pour que la nouvelle branche apparaisse également dans le dépôt distant.

Dans la console

Ce qui se passe en réalité dans les coulisses est que vous créez une nouvelle branche avec git branch, puis vous allez dans la branche avec git checkout ( i.e. dites à Git que vos prochains commits se feront là). Dans votre dépôt git :

git branch my-new-branch # Créez la nouvelle branche
git checkout my-new-branch # Aller sur la branche
git checkout -b ma-nouvelle-branche # Les deux à la fois (raccourci)

Pour plus d’informations sur l’utilisation de la console, voir la section sur les Commandes Git à la fin.

46.7 Valider les changements

Vous pouvez maintenant modifier le code, ajouter de nouveaux fichiers, mettre à jour les ensembles de données, etc.

Chacune de vos modifications est suivie, une fois que le fichier respectif est sauvegardé. Les fichiers modifiés apparaîtront dans l’onglet Git de RStudio, dans Github Desktop, ou en utilisant la commande git status dans le terminal (voir ci-dessous).

Chaque fois que vous effectuez des modifications substantielles (par exemple, l’ajout ou la mise à jour d’une section de code), faites une pause et committez ces changements. Pensez à un commit comme un “partie” de changements liés à un objectif commun. Vous pouvez toujours continuer à réviser un fichier après y avoir apporté des modifications.

Conseil sur les commits : en général, il est préférable de faire de petits commits, qui peuvent être facilement annulées si un problème survient, pour commiter ensemble des modifications liées à un objectif commun. Pour y parvenir, vous trouverez que vous devez commiter souvent. Au début, vous allez probablement oublier de commiter souvent, mais ensuite l’habitude s’installe.

Dans Rstudio

L’exemple ci-dessous montre que, depuis le dernier commit, le script R Markdown “collaboration.Rmd” a été modifié, et plusieurs images PNG ont été ajoutées.

Vous vous demandez peut-être ce que représentent les carrés jaunes, bleus, verts et rouges à côté de les noms de fichiers. Voici un instantané de la feuille de route RStudio cheatsheet qui explique leur signification. Notez que les changements avec des ” ?” jaunes peuvent toujours être mises en scène, validées et poussées.

  • Cliquez sur le bouton “Commit” dans l’onglet Git, ce qui ouvrira une nouvelle fenêtre (voir ci-dessous).

  • Cliquez sur le nom d’un fichier dans le cadre supérieur gauche.

  • Passez en revue les modifications que vous avez apportées à ce fichier (surlignées en vert ou en rouge ci-dessous).

  • “Mettez en scène” le fichier, ce qui inclura ces modifications dans le commit. Faites en cochant la case à côté du nom du fichier. Alternativement, vous pouvez mettre en surbrillance plusieurs noms de fichiers, puis cliquer sur “Stage”.

  • Rédigez un message de validation court mais descriptif (obligatoire).

  • Appuyez sur le bouton “Commit”. Une boîte de dialogue apparaîtra, indiquant le succès ou un message d’erreur.

Vous pouvez maintenant effectuer d’autres modifications et d’autres livraisons, autant de fois que vous le souhaitez.

Dans le bureau de Github

Vous pouvez voir la liste des fichiers qui ont été modifiés sur la gauche. Si vous sélectionnez un fichier texte, vous verrez un résumé des modifications qui ont été apportées dans le volet de droite (cette vue ne fonctionnera pas sur des fichiers plus complexes comme les .docs ou les .xlsx).

Pour mettre en scène les changements, il suffit de cocher la petite case à côté des noms de fichiers. Lorsque vous avez sélectionné les fichiers que vous voulez ajouter à cette livraison, donnez un nom à la livraison, une description, puis cliquez sur le bouton commit.

Dans la console

Les deux fonctions utilisées dans les coulisses sont git add pour sélectionner/établir et git commit pour effectuer la livraison.

git status # voir les changements 

git add new_pages/collaboration.Rmd # sélectionner les fichiers à livrer (= mettre en scène les changements)

git commit -m "Describe commit from Github Desktop" # livrer les changements avec un message

git log # affiche les informations sur les commits passés

Modifier un commit précédent

Que se passe-t-il si vous commettez des changements, continuez à travailler et réalisez que vous avez fait des changements qui devraient “appartenir” au commit précédent (à votre avis)? N’ayez crainte ! Vous pouvez ajouter ces changements à votre validation précédente.

Dans Rstudio, cela devrait être assez évident puisqu’il y a une case “Amend previous commit” sur la même ligne que le bouton COMMIT.

Pour une raison peu claire, la fonctionnalité n’a pas été implémentée en tant que telle dans Github Desktop, mais il existe une moyen de la contourner. Si vous avez validé mais pas encore poussé vos changements, un bouton “UNDO” apparaît juste en dessous du bouton COMMIT. Cliquez dessus et il annulera votre validation (mais conservera vos fichiers indexés et votre message de validation). Sauvegardez vos changements, ajoutez de nouveaux fichiers à la livraison si nécessaire et livrez à nouveau.

Dans la console :

git add [YOUR FILES] # Ajoute vos nouvelles modifications

git commit --amend # Modifie le commit précédent

git commit --amend -m "An updated commit message" # Modifie la livraison précédente ET met à jour le message de livraison.

Note : réfléchissez avant de modifier des commits qui sont déjà publics et partagés avec vos collaborateurs.

46.8 Tirez et poussez les modifications vers Github

“D’abord TIREZ, ensuite POUSSER”

C’est une bonne pratique de aller chercher et de tirez avant de commencer à travailler sur votre projet, afin de mettre à jour la version de la branche sur votre ordinateur local avec toutes les modifications qui ont été apportées dans la version distante/Github.

TIREZ souvent. N’hésitez pas. Tirez toujours avant de pousser.

Lorsque vos modifications sont effectuées et validées et que vous êtes satisfait de l’état de votre projet, vous pouvez pousser vos commits vers la version distante/Github de votre branche.

Rincez et répétez pendant que vous travaillez sur le référentiel.

Note: il est beaucoup plus facile de revenir sur des modifications qui ont été commises mais pas poussées (c’est-à-dire qu’elles sont toujours en cours de traitement) que de revenir sur des changements qui ont été poussés vers le dépôt distant (et peut-être déjà extraites par quelqu’un d’autre).

Dans Rstudio

TIREZ - Cliquez d’abord sur l’icône “Tirez” (flèche vers le bas) qui récupère et tire en même temps.

POUSSER - Cliquez sur l’icône verte “Tirez” (flèche vers le haut). Il peut vous être demandé d’entrer votre nom d’utilisateur et votre mot de passe Github.La première fois, vous devrez peut-être entrer deux lignes de commande Git dans le Terminal:

  • git config –global utilisateur.email ” “ (votre adresse électronique Github ), et
  • git config –global user.name “Votre nom d’utilisateur Github”

Pour en savoir plus sur la façon de saisir ces commandes, consultez la section ci-dessous sur les commandes Git.

TIP: On vous demande trop souvent de fournir votre mot de passe ? Consultez les chapitres 10 & 11 de ce tutoriel pour se connecter à un référentiel en utilisant une clé SSH (plus compliqué).

Dans le bureau de Github

Cliquez sur le bouton “Récupérer l’origine” pour vérifier s’il y a de nouveaux commits sur le dépôt distant.

Si Git trouve de nouveaux commits sur le dépôt distant, le bouton se se transformera en bouton “Pull”. Comme le même bouton est utilisé pour pousser et tirer, vous ne pouvez pas pousser vos modifications si vous ne tirez pas auparavant.

Vous pouvez aller dans l’onglet “History” (près de l’onglet “Changes”) pour voir toutes les commits (les vôtres et ceux des autres). C’est un bon moyen de savoir ce que vos collaborateurs ont fait. Vous pouvez lire le message du commit, la description s’il y en a une, et comparer le code des deux fichiers en utilisant le volet diff.

Une fois que toutes les modifications distantes ont été tirées, et qu’au moins une modification locale a été validée, vous pouvez pousser en cliquant sur le même bouton.

Console

Sans surprise, les commandes sont chercher (fetch), tirez (pull) et pousser (push).

git fetch # Y a-t-il de nouveaux commits dans le répertoire distant ?
git pull # Apporte les commits distants dans votre branche locale
git push # Pousse les commits locaux de cette branche vers la branche distante

Je veux tirer mais j’ai du travail local

Cela peut arriver parfois : vous avez effectué des modifications sur votre dépôt local, mais le dépôt distant a des commits que vous n’avez pas tirés.

Git refusera de les extraire car cela pourrait écraser vos modifications. Il existe plusieurs stratégies pour conserver vos modifications, bien décrites dans Happy Git with R, parmi lesquelles les deux principales sont :

  • livrer vos modifications, récupérer les modifications distantes, les tirer, résoudre les conflits si nécessaire (voir la section ci-dessous), et pousser le tout en ligne
  • stash vos changements, ce qui les met en quelque sorte de côté, les tirer, les déstocker (restauration), puis commit, résolution des conflits, et push.

Si les fichiers concernés par les modifications distantes et les fichiers concernés par vos modifications locales ne se chevauchent pas, Git peut résoudre les conflits automatiquement.

Dans Github Desktop, cela peut être fait avec des boutons. Pour mettre en cache, allez dans Branch > Stash all changes.

46.9 Fusionner la branche dans Main

Si vous avez fini de faire des changements, vous pouvez commencer le processus de fusionner ces changements dans la branche principale. En fonction de votre situation, cela peut être rapide, ou vous pouvez avoir des étapes délibérées de révision et d’approbation impliquant des coéquipiers.

Localement dans Github Desktop

On peut fusionner des branches localement en utilisant Github Desktop. Tout d’abord, allez dans (checkout) la branche qui sera le destinataire des commits, en d’autres termes, la branche que vous voulez mettre à jour. Ensuite, allez dans le menu Branche > Fusionner en branche actuelle et cliquez. Une boîte vous permet de sélectionner la branche à partir de laquelle vous souhaitez importer.

Dans la console

Revenez d’abord à la branche qui sera le destination des changements. C’est généralement master, mais cela peut être une autre branche si vous le souhaite. Fusionnez votre branche de travail dans master.

git checkout master # Retournez à master (ou à la branche que vous voulez déplacer)
git merge this_fancy_new_branch

Cette page montre un exemple plus avancé de branchement et explique un peu ce qui se passe en coulisses.

Dans Github : soumettre des demandes de pull (tirer)

S’il est tout à fait possible de fusionner deux branches localement, ou sans en informer qui que ce soit, une fusion peut être discutée ou étudiée par plusieurs personnes avant d’être intégrée à la branche master. Pour aider à ce processus, Github propose des fonctionnalités de discussion autour de la fusion : la pull request.

Une pull request (une “PR”) est une demande de fusion d’une branche dans une autre (en d’autres termes, une demande pour que votre branche de travail soit intégrée à la branche “principale”). Une pull request implique généralement plusieurs commits. Une pull request commence généralement une conversation et un processus de révision avant qu’elle soit acceptée et que la branche soit fusionnée. Par exemple, vous pouvez lire les discussions sur les demandes de téléchargement sur le site dplyr’s github.

Vous pouvez soumettre une demande de modification (PR) directement à partir du site Web (comme illustré ci-dessous) ou à partir de Github.

  • Accéder au dépôt Github (en ligne)
  • Affichez l’onglet “demande de retrait” et cliquez sur le bouton “New pull request”.
  • Choisissez dans le menu déroulant de fusionner votre branche avec la branche principale.
  • Rédigez un commentaire détaillé de la Pull Request et cliquez sur “Create Pull Request”.

Dans l’image ci-dessous, la branche “forests” a été sélectionnée pour être fusionnée dans “main” :

Maintenant vous devriez être capable de voir la pull request (image d’exemple ci-dessous) :

  • Passez en revue l’onglet “Fichiers modifiés” pour voir comment la branche “principale” changerait si la branche était fusionnée.
  • Sur la droite, vous pouvez demander une révision aux membres de votre équipe en marquant leur identifiant Github. Si vous le souhaitez, vous pouvez définir les paramètres du référentiel pour qu’une révision approuvée soit nécessaire afin de fusionner avec la branche master.
  • Une fois la demande de retrait est approuvée, un bouton permettant de “Merge pull request” devient actif. Cliquez dessus.
  • Une fois terminé, supprimez votre branche comme expliqué ci-dessous.

Résolution des conflits

Lorsque deux personnes modifient la ou les mêmes lignes au même moment, un conflit de fusion se produit. En effet, Git refuse de prendre une décision quant à version à conserver, mais il vous aide à trouver où se trouve le conflit. NE PANIQUEZ PAS. La plupart du temps, il est assez simple à résoudre.

Par exemple, sur Github :

Après que la fusion ait soulevé un conflit, ouvrez le fichier dans votre éditeur préféré. Le conflit sera indiqué par une série de caractères :

Le texte entre <<<<<<< HEAD et ======= provient de votre dépôt local, et celui entre ======= et >>>>>>> de l’autre branche (qui peut être origin, main ou toute autre branche de votre choix).

Vous devez décider quelle version du code vous préférez (ou même écrire une troisième, en incluant les changements des deux côtés si cela est pertinent), effacer le reste et retirer toutes les marques que Git a ajoutées ((<<<<<<< HEAD, =======, >>>>>>> origin/master/your_branch_name).

Ensuite, sauvegardez le fichier, mettez-le en scène et commitez-le : c’est le commit qui rend la version fusionnée “officielle”. N’oubliez pas de pousser (push) ensuite.

Plus vous et vos collaborateurs tirent et poussent souvent, plus les conflits seront réduits.

*Remarque : Si vous vous sentez à l’aise avec la console, il existe des outils plus avancés de fusionner options (par exemple, ignorer les espaces, donner la priorité à un collaborateur, etc.)

Supprimer votre branche

Une fois qu’une branche a été fusionnée dans master et n’est plus nécessaire, vous pouvez la supprimer.

46.9.0.1 Github + Rstudio

Allez sur le dépôt sur Github et cliquez sur le bouton pour afficher toutes les branches (à côté de la liste déroulante pour les branches). Trouvez maintenant votre branche et cliquez sur l’icône de la corbeille à côté d’elle. Lisez plus de détails sur la suppression d’une branche ici.

Assurez-vous de supprimer également la branche localement sur votre ordinateur. Cela ne se fera pas automatiquement.

  • Dans RStudio, assurez-vous que vous êtes dans la branche Main.
  • Passez à la saisie de commandes Git dans le “Terminal” de RStudio (l’onglet adjacent à la console R), et tapez : git branch -d nom_branche, où “nom_branche” est le nom de la branche à supprimer.
  • Rafraîchissez votre onglet Git et la branche devrait avoir disparu.

46.9.0.2 Dans Github

Vérifiez simplement la branche que vous voulez supprimer ce retrouve maintenant dans le menu Branche > Supprimer.

Forking

Vous pouvez bifurquer d’un projet si vous souhaitez contribuer mais que vous n’avez pas les droits pour le faire, ou si vous voulez simplement le modifier pour votre usage personnel. Une courte description de la bifurcation se trouve ici.

Sur Github, cliquez sur le bouton “Fork” :

Ceci clonera le dépôt original, mais dans votre propre profil. Donc maintenant, il y a deux versions du dépôt sur Github : l’original, que vous ne pouvez pas modifier, et la version clonée dans votre profil.

Ensuite, vous pouvez procéder au clonage de votre version du dépôt en ligne en local sur votre ordinateur, en utilisant l’une des méthodes décrites dans les sections précédentes. Ensuite, vous pouvez créer une nouvelle branche, faire des changements, les livrer et les pousser vers votre dépôt distant.

Une fois que vous êtes satisfait du résultat, vous pouvez créer une Pull Request à partir de Github ou de Github Desktop pour entamer la conversation avec les propriétaires/mainteneurs du dépôt d’origine.

Et si vous avez besoin de commits plus récents du dépôt officiel?

Imaginez que quelqu’un apporte une modification critical au dépôt officiel, que vous voulez inclure dans votre version clonée. Il est possible de synchroniser votre fork avec le dépôt officiel. Cela implique l’utilisation du terminal, mais ce n’est pas trop compliqué. Vous devez surtout vous rappeler que :

  • upstream = le dépôt officiel, celui que vous n’avez pas pu modifier
  • origin = votre version du dépôt sur votre profil Github

Vous pouvez lire ce tutoriel ou suivre les instructions ci-dessous :

Tout d’abord, tapez dans votre terminal Git (à l’intérieur de votre repo) :

git remote -v

Si vous n’avez pas encore configuré le référentiel amont, vous devriez voir deux lignes, commençant par origin. Elles montrent le dépôt distant vers lequel chercher et pousser pointent. Rappelez-vous, origin est le surnom conventionnel pour votre propre version du dépôt sur Github. Par exemple :

Maintenant, ajoutez un nouveau dépôt distant :

git remote add upstream https://github.com/epirhandbook/Epi_R_handbook.git

Ici, l’adresse est l’adresse que Github génère lorsque vous clonez un dépôt (voir la section sur le clonage). Vous aurez maintenant quatre pointeurs distants :

Maintenant que la configuration est faite, chaque fois que vous voulez obtenir les changements de le dépôt original (upstream), il suffit d’aller (checkout) dans la branche la branche que vous voulez mettre à jour et taper :

git fetch upstream # Obtenir les nouveaux commits du dépôt distant
git checkout la_branche_que_vous_voulez_mettre_à_jour
git merge upstream/the_branch_you_want_to_update # Fusionne la branche amont dans votre branche.
git push # Mettez à jour votre propre version du dépôt distant.

S’il y a des conflits, vous devrez les résoudre, comme expliqué dans la section Résoudre les conflits.

Résumé : forker est un clonage, mais du côté du serveur Github. Le reste des actions sont des actions typiques du flux de travail de collaboration (cloner, pousser, tirer, commettre, fusionner, soumettre des demandes de tirage…).

Remarque : si la bifurcation est un concept et non une commande Git, elle existe aussi sur d’autres hôtes Web, comme Bitbucket.

46.10 Ce que nous avons appris

Vous avez appris à :

  • paramétrer Git pour suivre les modifications dans vos dossiers,
  • connecter votre référentiel local à un référentiel en ligne distant,
  • livrer les changements,
  • synchroniser vos dépôts local et distant.

Tout cela devrait vous permettre de démarrer et de répondre à la plupart de vos besoins en tant qu’épidémiologistes. Nous n’avons généralement pas un usage aussi avancé que les développeurs.

Cependant, sachez que si vous voulez (ou devez) aller plus loin, Git offre plus de puissance pour simplifier l’historique des commits, le retour en arrière d’un ou plusieurs commits, le cherry-pick des commits, etc. Tout cela peut sembler de la pure magie, mais maintenant que vous avez les bases, il est plus facile de s’appuyer dessus.

Notez que si le volet Git de Rstudio et Github Desktop sont bons pour les débutants / l’utilisation quotidienne dans notre travail, ils n’offrent pas une interface pour certaines des fonctions intermédiaires/avancées de Git. Certaines interfaces plus complètes vous permettent d’en faire plus en pointant et en cliquant (généralement au prix d’une mise en page plus complexe).

Rappelez-vous que puisque vous pouvez utiliser n’importe quel outil à n’importe quel moment pour suivre votre dépôt, vous pouvez très facilement installer une interface pour l’essayer parfois, ou pour effectuer occasionnellement une tâche complexe moins courante, tout en préférant une interface simplifiée le reste du temps (par exemple en utilisant Github Desktop la plupart du temps, et passer à SourceTree ou Gitbash pour certaines tâches spécifiques).

46.10.1 Commandes Git

Apprentissage recommandé

Pour apprendre les commandes Git à l’aide d’un tutoriel interactif, voir ce site web.

Où entrer les commandes

Vous entrez les commandes dans un shell Git.

Option 1 Vous pouvez ouvrir un nouveau Terminal dans RStudio. Cet onglet se trouve à côté de la Console R. Si vous ne parvenez pas à y taper du texte, cliquez sur le menu déroulant sous “Terminal” et sélectionnez “Nouveau terminal”. Tapez les dans l’espace clignotant situé devant le symbole du dollar “$”.

Option 2 Vous pouvez également ouvrir un shell (un terminal pour entrer des commandes) en cliquant sur l’icône bleue “gears” dans l’onglet Git (près de l’environnement RStudio). Sélectionnez “Shell” dans le menu déroulant. Une nouvelle fenêtre s’ouvre dans laquelle vous pouvez saisir les commandes après le signe du dollar “$”.

Option 3 Cliquez avec le bouton droit de la souris pour ouvrir “Git Bash here”, qui ouvrira le même type de terminal, ou ouvrez Git Bash depuis votre liste d’applications. Plus d’informations pour les débutants sur Git Bash, comment le trouver et quelques commandes bash dont vous aurez besoin.

Exemples de commandes

Nous présentons ci-dessous quelques commandes git courantes. Lorsque vous les utilisez, gardez à l’esprit quelle branche est active (check-out), car cela changera l’action !

Dans les commandes ci-dessous, représente un nom de branche et représente l’ID de hachage d’un commit spécifique. représente un nombre. Ne tapez pas les symboles < ou >>.

Commande Git Action
git branch <name> Créer une nouvelle branche avec le nom
git checkout <name> Bascule de la branche actuelle vers . |git checkout -b | Raccourci pour créer une nouvelle branche *et* y basculer | |git status| Voir les modifications non suivies | |git add | Mettre en scène un fichier | |git commit -m Comptabilise les changements actuellement mis en scène dans la branche actuelle avec le message | |git fetch| Récupérer les commits du dépôt distant | |git pull| Extraire les commits du dépôt distant dans la branche actuelle | |git push| Pousse les commits locaux vers le répertoire distant | |git switch| Une alternative àgit checkoutqui est en train d'être introduite progressivement dans Git | |git merge | Fusionner la branche <name> dans la branche courante | |git rebase `

46.11 Ressources

Une grande partie de cette page a été informée de ce site “Happy Git with R” site web par Jenny Bryan. Il y a une section très utile qui vous aide à résoudre les erreurs courantes liées à Git et à R.

Le Guide de documentation et de démarrage de Github.com guide.

La fiche technique de RStudio “IDE” cheatsheet qui comprend des conseils sur Git avec RStudio.

https://ohi-science.org/news/github-going-back-in-time

Les commandes Git pour les débutants

Un tutoriel didacticiel pour apprendre les commandes Git.

https://www.freecodecamp.org/news/an-introduction-to-git-for-absolute-beginners-86fa1d32ff71/ : bon pour apprendre les bases absolues pour suivre les changements dans un dossier sur votre propre ordinateur.

De beaux schémas pour comprendre les branches : https://speakerdeck.com/alicebartlett/git-for-humans

Tutoriels couvrant les sujets de base et plus avancés.

https://tutorialzine.com/2016/06/learn-git-in-30-minutes

https://dzone.com/articles/git-tutorial-commands-and-operations-in-git https://swcarpentry.github.io/git-novice/ (cours court) https://rsjakob.gitbooks.io/git/content/chapter1.html

Le livre Pro Git est considéré comme une référence officielle. Bien que certains chapitres soient corrects, il est généralement un peu technical. C’est probablement une bonne ressource une fois que vous avez utilisé Git un peu et quand vous voulez apprendre un peu plus précisément ce qui se passe et comment aller plus loin avec Git.