Vous avez travaillé pendant des années sur vos scripts R, et avez enregistré toutes les versions avec des noms comme “script_v1.R”, “script_v2.R”, “script_v2_meilleur_du_monde.R”, … Un jour, vous avez entendu parler de git, un système de versionnage qui vous permet de faire voyager vos fichiers à travers le temps. Mais comment transformer un dossier de fichiers faussement versionnés en dépôt git et le synchroniser en ligne ?
Au départ, je voulais écrire un article de blog sur notre package {gitdown}, mais j’ai réalisé que j’avais besoin d’un exemple reproductible de dépôt git sur Github et Gitlab et j’ai commencé à documenter les étapes. Mais ensuite, c’était trop long pour rester dans le même article. Le voici donc : le préambule de mon article “Télécharger les issues Gitlab ou Github et faire un rapport résumé de vos commits”. Ce sont les toutes premières étapes de la transformation d’un dossier local en un dépôt git, synchronisé à distance avec un fournisseur git. Nous verrons également comment synchroniser le même projet avec deux fournisseurs git différents, Github et Gitlab, en même temps.
Si vous souhaitez faire une lecture rapide, vous pouvez lire uniquement les titres et le texte en gras pour obtenir les points principaux des sections.
git, pour vos projets personnels
Table des matières
Puisqu’on parle de git, vous avez peut-être entendu dire que c’était un excellent outil pour le travail collaboratif dans le développement de logiciels. Cela permet de gérer le travail de plusieurs développeurs en parallèle sur un même projet, tout en réduisant la crainte de perdre une partie du travail des gens. Mais vous n’avez pas besoin de travailler à plusieurs pour utiliser git avec votre projet. Dès que vous avez quelques scripts, vous voulez peut-être suivre les modifications que vous faites au cours du temps. git est là pour ça.
Pour installer git, vous pouvez suivre ce guide dans “Happy Git and GitHub for the useR”.
Transformer mon dossier en projet git
Vous devriez probablement travailler dans un projet Rstudio : Fichier > Nouveau projet > Répertoire existant.
Si vous ne voulez pas de Rstudio, vous devrez définir votre dossier comme votre répertoire de travail actuel.
Ensuite exécutez usethis::use_git() et répondez aux questions (je dirais “Oui” deux fois).
git vous demande de dire qui vous êtes, afin que chaque modification de votre code vous soit attribuée. Avec cette ligne de code, vous pouvez définir votre configuration de manière globale. Faites-le une fois sur cet ordinateur, et vous n’aurez pas à le refaire.
use_git_config(user.name = "Jane", user.email = "[email protected]")C’est tout. Vous travaillez maintenant dans un dépôt git.
Lignes de commandes git pour débuter
Votre projet est maintenant local. Si vous êtes un débutant et que vous ne voulez pas vous embêter tout de suite avec toutes les incroyables possibilités, c’est possible. Il y a deux actions à réaliser quotidiennement : add et commit.
add: ajoute un fichier à la liste des fichiers qui seront gelés après lecommit.commit: cela fige l’état de tous les fichiers ajoutés (add) dans le dépôt git. Cela va de pair avec un message dans lequel vous expliquez pourquoi vous avez gelé ces fichiers à cet état.
Toutes les raisons de commit sont bonnes. Faire un commit ne signifie pas que vous ne pouvez pas continuer à travailler sur ce fichier par la suite. En effet, si vous faites de nouvelles modifications, vous pouvez les add pour le prochain commit. Les messages de commit seront l’équivalent de vos v1, v2, version_finale, version_bien_mieux, …
Utilisez add et commit avec l’interface graphique RStudio
Dans Rstudio, dès que vous redémarrez un projet avec un dépôt git à l’intérieur, vous aurez accès à l’onglet git.
- Pour
addun fichier pour le prochaincommit, cochez la case dans la colonne “Staged”. - Pour
committous les fichiers cochés, cliquez sur “Commit”. Ajoutez un message decommit, et “Commit” !
Vous pourrez voir l’historique de vos commits en cliquant sur l’icône avec l’horloge.
Utilisez add et commit en ligne de commande
Si vous êtes toujours dans Rstudio, vous pouvez utiliser le Terminal pour commit. Vous pouvez également ouvrir directement un Terminal et vous assurer que vous êtes dans le bon dossier.
Dans le Terminal
# allez dans le bon dossier (nommé repo.rtask ici)
cd repo.rtask
# "add" des fichiers
git add example.txt
git add NEWS.md
# commit avec message
git commit -m "My first command line commit"Créer un exemple de projet git.
Pour les tests et les exemples dans le package {gitdown}, la fonction fake_repo() construit un faux projet avec quelques fichiers et commits. C’est déjà un dossier avec un dépôt git. J’utiliserai ce dépôt comme exemple reproductible de cet article de blog.
# remotes::install_github("ThinkR-open/gitdown")
library(gitdown)
# Creer un dépot ici avec les dossiers `R/` et `vignettes/`
repo <- fake_repo(path = "repo.rtask", as.package = TRUE)
# Contenu du dossier
fs::dir_tree(repo)## repo.rtask
## ├── NEWS.md
## ├── R
## │ └── my_mean.R
## ├── example.txt
## └── vignettesJe peux aussi voir que nous sommes effectivement dans un dépôt git en utilisant {git2r}, avec certains fichiers suivis et d’autres non.
library(git2r)
ls_tree(repo = repo)## mode type sha path name len
## 1 100644 blob 9c66eff9a1f6f34b6d9108ef07d76f8ce4c4e47f NEWS.md 98
## 2 100644 blob c36b681bb31b80cbd090f07c95f09788c88629a6 example.txt 200status(repo = repo)## Untracked files:
## Untracked: .gitignore
## Untracked: R/Synchroniser un dépôt git local avec Github
Maintenant que j’ai un dépôt git local, je vais le synchroniser sur Github, puis sur Gitlab.
Création d’un dépôt Github
- Ouvrez votre compte github sur https://github.com
- Aller à “Repositories”
- Cliquez sur le bouton “New”.
- Donnez-lui le nom de votre dépôt local (
repo.rtaskici)- Ne pas cochez “Initialize this repository with a README”
- Cliquez sur “Create repository”
Envoyez le contenu de votre dépôt local vers Github
Les informations sur la synchronisation avec votre dépôt local sont présentées par Github sur la page d’accueil de votre projet.
Choisissez la partie “…or push an existing repository from the command line” et exécutez ces lignes dans un Terminal.
Dans le Terminal
# Changer chemin si besoin
cd repo.rtask
# Synchroniser avec github
git remote add origin [email protected]:statnmap/repo.rtask.git
git push -u origin masterRetournez sur votre projet Github pour voir les deux fichiers téléchargés : https://github.com/statnmap/repo.rtask
Notez que le même type d’opérations serait utilisé pour une synchronisation avec un serveur Gitlab.
Ajoutez des issues sur Github
J’ouvre deux issues sur mon Github. En effet, dans les commits effectués par fake_repo(), les messages mentionnent des numéros d’issues différents de #1 à #145. Par exemple, vous pouvez regarder ce message de commit (ici sur Github).
summary(last_commit(repo))## Commit: 98896d1947fcd2c85771553dc1fd9f7da963e811
## Author: Alice <[email protected]>
## When: 2020-08-10 15:03:52 GMT
##
## Add NEWS
##
## issue #32.
## issue #1.
## issue#12
## ticket6789.
## ticket1234
## Creation of the NEWS file for version 0.1.
## 1 file changed, 3 insertions, 0 deletions
## NEWS.md | -0 +3 in 1 hunkJe ne vais bien évidemment pas créer 145 issues ! Deux suffisent pour l’article de blog qui suivra. Donc créons deux issues avec un titre et une petite description.
Communiquer avec un serveur git distant
Lorsque vous synchronisez votre dépôt git local avec un serveur distant, vous devez apprendre deux autres actions : pull et push.
- L’action
pullconsiste à télécharger le contenu du serveur sur votre dépôt local. - Le
pushconsiste à téléverser voscommitlocaux sur le serveur.
Si vous travaillez seul⋅e, il y a de fortes chances que vous n’ayez pas vraiment besoin de pull car les modifications ont été créées en premier sur votre ordinateur. Et il n’y a aucune raison que le serveur ait des modifications plus récentes que votre ordinateur… En revanche, vous voudrez push régulièrement vos commit vers le serveur. Vous pouvez push plusieurs commits en même temps. En général, on dit : “on commit tôt et souvent, mais on push de temps en temps”. Plus tard, vous apprendrez que vous pouvez modifier le contenu de vos commit dès lors qu’ils ne sont pas déjà push sur le serveur.
Dans l’onglet git de Rstudio, utilisez “↓” (flèche bleue vers le bas) pour pull et “↑” (flèche verte vers le haut) pour push vers le serveur. En la ligne de commande, utilisez git pull et git push.
Synchroniser un dépôt git local sur Gitlab
Nous pourrions faire exactement les mêmes étapes sur Gitlab que sur Github. Si vous envisagez d’avoir un dépôt unique à distance, ce que font presque tous les développeurs, suivez le guide Github ci-dessus sur votre serveur Gitlab (“Repository” est nommé “Project”). Vous pouvez aller directement au dernier paragraphe de cet article.
Plus bas, j’en profite pour montrer comment migrer de Github à Gitlab ou synchroniser un dépôt local vers deux fournisseurs distants différents.
Déplacer un dépôt Github vers Gitlab
J’ai d’abord essayé d’utiliser le protocole de transfert git proposé par Gitlab pour récupérer mon dépôt et mes issues sur mon compte Gitlab.com.
- Ouvrez votre compte Gitlab
- Sur gitlab.com ou sur votre propre serveur Gitlab
- Cliquez sur “Nouveau projet”.
- Choisissez l’onglet “Importer un projet”.
- Cliquez sur l’icône appropriée. Github dans ce cas.
- Cliquez sur l’icône appropriée. Github dans ce cas.
- Vous devrez peut-être vous connecter à votre compte Github
- Choisissez le dépôt que vous souhaitez importer
- Importez
…ou créez une copie de votre Github sur Gitlab
L’importateur Gitlab fonctionne en théorie. Dans mon cas, tous mes dépôts Github n’étaient pas répertoriés dans l’importateur Gitlab. Et, bien sûr, le dépôt qui m’intéresse n’y était pas. Ce paragraphe montre ce que j’ai fait pour copier le contenu de Git dans un autre fournisseur distant.
J’ai donc décidé de suivre un de mes guides “Garder à jour ses fork github/gitlab”. Ce guide fonctionne aussi si les deux dépôts ne sont pas sur le même fournisseur comme ici.
- Créer un nouveau projet “Blank” sur Gitlab sans “Initialisation” : https://gitlab.com/statnmap/repo.rtask
- Envoyez le contenu de votre dépôt local à Gitlab. Mais ici, comme nous l’avons déjà envoyé à Github, nous avons besoin de quelques modifications des lignes de commande.
Dans le Terminal
# Get all last modifications
git pull
# rename the local link dedicated to github
git remote rename origin origin_github
# Create the local link to Gitlab by default
git remote add origin https://gitlab.com/statnmap/repo.rtask.git
# Push the content
git push -u origin- Créer les deux issues manuellement comme on l’a fait dans Github
Notez que vous utiliseriez des commandes similaires si vous voulez faire un “fork” d’un projet, changer son nom et lui donner une nouvelle direction. Comme j’ai fait avec {gitlabr}, on en parlera dans la prochain article…
Utilisez git dans tous vos projets !
Maintenant que vous avez les bases de git, transformez tous vos répertoires en projets git. Si vous pensez que ce n’est pas important parce que vous avez une bonne gestion de toutes vos versions de scripts, essayez juste pour un projet. Mettez en place un rappel, dans 6 mois, et revenez me dire si vous avez changé d’avis.
Que faudra-t-il faire après ça ? Et bien pourquoi ne pas regarder par ici pour transformer votre projet en package, avec la documentation qui vous permettra de le maintenir sans se prendre la tête ?
Si vous êtes passé par la partie où je parle de transfert de Github à Gitlab, vous avez lu que j’ai dû recréer manuellement mes issues ouvertes pour obtenir une copie exacte. Que faire si vous voulez télécharger toutes vos issues localement pour garder une trace des discussions ? Vous le verrez dans le prochain épisode : “Télécharger les issues Gitlab ou Github et faire un rapport résumé de vos commits”
Si vous voulez installer git, en savoir plus et aller plus loin que cet article, je vous recommande “Happy Git and GitHub for the useR”.
