Utiliser Git et bitbucket pour écrire un livre en LaTeX (partie 1)

Pour l’enseignant en mathématique, LaTeX. est une solution élégante pour produire des documents d’une qualité typographique irréprochable.

Latex est un logiciel de composition particulièrement adapté à la production de documents scientifiques et mathématiques de grande qualité typographique. Il permet également de produire toutes sortes d’autres documents, qu’il s’agisse de simples lettres, slides ou de livres entiers. Pour ceux qui ne connaissent pas Latex et qui souhaitent le découvrir, je vous conseille la lecture du premier chapitre d’une courte (?) introduction à LaTeX.

Des notes de cours, des tests, un syllabus ou un livre de référence, cela évolue en permanence. Il faut parfois revenir en arrière sur une modification, parfois modifier légèrement un exercice, parfois écrire des parties au « brouillon » que finalement on ne conservera pas etc. Quand en plus on modifie à plusieurs le même document, les risques sont grands de se perdre dans les différentes versions de texte, voire même de perdre certaines modifications écrasées involontairement.

Le besoin se fait rapidement sentir d’un outil permettant de structurer le travail de rédaction, notamment en conservant l’historique des modifications et permettant de travailler ensemble sur un même projet, sans risque.

Le système de gestion de version Git, couplé au service en ligne offert par Bitbucket permet de répondre à ce besoin, de manière relativement simple. Le but de cet article est de présenter ces outils, et expliquer concrètement comment les utiliser pour rédiger des documents en LaTeX.

Versionner, quesaco ?

Les fichiers LaTeX étant de simples fichiers texte, le plus facile est d’utiliser un système de gestion de version dont se servent les informaticiens.

Versionner son projet signifie gérer tous les fichiers sources d’un projet (.tex, .eps, .jpg…) avec un système de gestion de version.

Un système de gestion de version est un outil qui permet de stocker plusieurs versions d’un même fichier ou ensemble de fichiers. Cela permet de conserver l’historique, mais aussi les brouillons. Tout est conservé et peut-être récupéré à tout moment.

Plus précisément, ces outils permettent en général :

  • de travailler à plusieurs sur un même projet de document, tout en s’assurant que chacun dispose de la bonne version.
  • de gérer les cas où deux personnes différentes modifient les mêmes fichiers en même temps.
  • d’avoir un historique de toutes les modifications, et donc de pouvoir revenir en arrière, le cas échéant.
  • d’associer un (court) message à chaque modification effectuée, la résumant, et permettant ainsi de (plus ou moins) facilement la retrouver.
  • de pouvoir indiquer des étapes marquantes, permettant de retrouver facilement l’état du projet à un moment donné (par exemple avant la première impression, ou au moment de la déposition etc.)
  • de maintenir plusieurs versions parallèles d’un même projet, tout en gardant la possibilité de fusionner les versions à un moment donné (par exemple, tout en gardant la version 1 d’un livre, on travaille en parallèle à la deuxième édition et on fusionnera les corrections de coquilles de l’édition 1 vers la seconde édition).

Bitbucket

Bitbucket est une plateforme proposant un service de gestion de version convivial basé sur Git.

Son avantage est d’être disponible directement via le web, via un client graphique convivial pour Windows et macOS appelé SourceTree, et via git en ligne de commande sous Linux (et aussi Windows et macOS, mais il paraît que c’est uniquement pour les barbus…).

Sur Bitbucket, il est possible d’avoir des projets privés pour lesquels on décide avec qui on les partage (pratique pour ne pas rendre public le contenu des interros). Il est donc possible de définir précisément qui a le droit de modifier les fichiers, et qui a juste l’accès en lecture seule (relecteurs, collègues non rédacteurs…).

Bitbucket est une plateforme disponible gratuitement pour les particuliers et petites équipes jusque cinq personnes. Pour les plus grandes structures, c’est payant.

Pour être complet, il faut mentionner deux autres plateformes similaires:

  • GitHub: c’est presque devenu la référence de facto pour l’hébergement de projets libres. Cependant, dans la version gratuite, il ne propose pas de projet privé, ce qui est problématique pour notre usage.
  • Gitlab: c’est un logiciel libre qui fournit toutes les fonctionnalités nécessaires. Il peut être installé sur son propre serveur pour un contrôle et une autonomie totals. Il propose aussi un service en ligne avec un nombre illimité de projets privés et de collaborateurs! C’est donc une solution idéale pour notre usage! Cet article est basé sur Bitbucket car c’est l’outil utilisé initialement par l’équipe pour qui cet article était destiné, mais si c’était à refaire, j’utiliserais sans hésiter Gitlab.

 

Introduction à Git et Bitbucket

Dans ce document, je présente Bitbucket et également Git. Il n’est absolument pas nécessaire de maîtriser ou même comprendre Git en profondeur pour pouvoir utiliser les services de Bitbucket. Cependant, comme Git est l’outil autour duquel Bitbucket est construit, il est intéressant de le présenter pour expliquer les concepts.

Dans un premier temps, cet article peut donc être lu en passant les explications spécifiques à Git.

Installation des outils

Il faut tout d’abord se créer un compte sur Bitbucket.

Sous Windows ou macOS, il faut ensuite installer l’application SourceTree.  SourceTree est l’application locale cliente de Bitbucket. Ce sera notre interface graphique privilégiée pour gérer notre projet.

Sous Linux, il faudra utiliser git en ligne de commande. Pour l’installer:

sudo apt-get install git gitk

En même temps, j’en profite pour installer gitk qui est un outil graphique de visualisation d’un projet git: cela peut être utile!

Configuration des outils

En lançant SourceTree pour la première fois, il faudra indiquer son compte Bitbucket afin de connecter l’application au service en ligne. Cela peut se faire via le menu Outils > Options > Général.

Pour git en ligne de commande, il faut définir son nom et son email qui seront utilisés par la suite pour savoir qui a fait des modifications:

git config --global user.name  "auteur"
git config --global user.email  "email"

En remplaçant évidemment auteur par votre nom, et email par votre adresse email.

Création d’un projet et de son dépôt

Un projet peut être par exemple un nouveau livre ou support de cours. Pour de plus petits documents comme des tests ou examens, un même projet peut regrouper plusieurs documents. L’idée est qu’un projet regroupe des documents ayant un lien entre eux et pour lesquels les droits d’accès sont similaires. Pour le reste de ce document, je considère que mon nouveau projet est la rédaction d’un livre scolaire.

Tout notre projet sera stocké dans un dépôt (repository en anglais). Cela peut être un dépôt existant sous Bitbucket et partagé par un autre collègue, ou alors un nouveau dépôt que vous devez créer pour votre nouveau projet.

Le dépôt est la structure de données dans laquelle le système de gestion de versions conserve toutes les informations sur notre projet.

Nouveau projet

Pour un nouveau projet, c’est assez simple: on va créer un nouveau dépôt vide sur Bitbucket, puis on va le cloner -c’est-à-dire le copier- sur notre ordinateur via SourceTree.

  1. créer un nouveau dépôt sur Bitbucket
  2. Via l’interface Bitbucket, cliquer sur « Cloner dans SourceTree ». SourceTree va s’ouvrir localement et demandera où cloner le dépôt.
  3. Le dépôt est cloné localement. Le projet est actuellement vide, mais le lien entre Bitbucket et le répertoire local est établi!

Projet existant

Pour pouvoir modifier un projet existant sur Bitbucket, il faut le cloner. Cloner signifie conserver sur le disque dur local une copie du dépôt distant. C’est sur cette copie que nous travaillerons, et nous enverrons nos modifications vers Bitbucket de temps en temps, généralement quand nous avons terminé avec une partie définie du travail, et que nous voulons partager cela avec l’ensemble de l’équipe projet.

Cloner un dépôt avec SourceTree sous Windows
Cloner un dépôt avec SourceTree sous Windows

En cliquant sur le bouton avec un globe en haut à droite, on peut sélectionner un dépôt disponible sur Bitbucket. Il faut ensuite sélectionner le chemin local de destination (Destination): c’est à cette endroit que les fichiers du projet seront accessibles localement.

On clique enfin sur le bouton « Cloner » qui va effectivement démarrer l’opération. On se retrouve avec une copie locale du dépôt (dans l’exemple ci-dessus, dans le répertoire  C:\Users\toto\Documents\math3_syllabus).

Avec git:

cd Documents
git clone https://toto@bitbucket.org/math3_syllabus.git
cd math3_syllabus.git

Dans ce cas, la copie locale du dépôt se trouve dans /home/toto/Documents/math3_syllabus.git.

L’URL à utiliser se trouve sur la page de garde du projet sur Bitbucket.

Commit

La notion de base d’un système de gestion de versions est la notion de commit.

Un commit est un ensemble de modifications au projet. Cela peut concerner plusieurs fichiers du projet, quelques lignes ou plusieurs milliers de lignes, des ajouts ou suppressions de fichiers…

Faire un commit, c’est indiquer que l’on souhaite enregistrer dans l’historique du projet des modifications effectuées sur un ou plusieurs fichiers.

Exemple: j’ai un fichier avec une équation LaTeX:

$9a^2b^3-3ab^2 = -3ab^2(3ab+1)$

Je me rends compte qu’il y a une erreur de signe dans cette équation et je modifie le fichier. A la fin de mes modifications, je souhaite enregistrer mes changements dans l’historique du projet: je fais un commit.

Sommairement un commit contient les données suivantes :

  • un identifiant unique qui permet de le distinguer des autres commits.
  • le nom de la personne qui procède au commit.
  • une date et heure
  • les modifications apportées aux fichiers concernés par le commit
  • un message résumant son contenu.

Dans Git et SourceTree, un fichier peut se trouver dans trois états différents :

  • il a été modifié mais on n’a pas indiqué à Git qu’il devra faire l’objet d’un commit : il se trouve dans le répertoire de travail uniquement et pas encore dans le dépôt.
  • il a été modifié et on a indiqué qu’il devait faire l’objet du prochain commit : il se trouve dans la zone d’attente (staging area en anglais).
  • il a été commité, et il est donc présent dans l’historique du dépôt.

À ceci s’ajoutent les fichiers qui ne sont pas encore pris en charge par Git.

Les commandes de base de Git servent à faire passer les fichiers d’un état à l’autre.

Ajouter un fichier au projet

Supposons qu’un nouveau fichier .tex doit être rajouté au projet.

  1. La première étape est de créer ce fichier de manière habituelle (TeXstudio, éditeur de texte…) dans le répertoire du projet.
  2. Une fois le fichier édité, il faut le rajouter au projet: git add mon-nouveau-fichier.texRajouter un fichier au projet signifie intégrer ce fichier dans le système de gestion de version. Dans SourceTree ci-dessous, il faut simplement cocher la case devant le fichier à rajouter, ici test.txt.txt.

Ajouter un fichier au dépôt avec SourceTree

Dans la capture d’écran ci-dessous, le fichier est bien ajouté dans la zone d’attente du système de gestion de version et prêt à être committé.

Fichier prêt pour un commit
Fichier prêt pour un commit
  1. Il faut ensuite committer le changement. Ce nouveau fichier peut être committé avec d’autres changements, que ce soit des modifications ou d’autres nouveaux fichiers: git commit. Un message court (une ligne) est demandé pour documenter le changement. Une description plus longue peut-être ajoutée également: on laisse simplement une ligne vide entre le message court et les explications détaillées.
  2. Il faut ensuite pousser ce commit vers Bitbucket pour que chaque participant au projet puisse en avoir connaissance: git push.

Avec SourceTree, les étapes 3 et 4 sont réalisées en une seule action, en cliquant sur le bouton « Valider » (commit), et en cochant bien l’option Pousser les modifications sur … dans l’écran suivant. Dans la capture d’écran ci-dessous, j’ai bien mis une petite description de mon changement: la première ligne est le résumé, une ligne blanche, puis ensuite une description plus détaillée si nécessaire.

Message de commit avec SourceTree
Message de commit avec SourceTree

Effectuer des modifications

Pour des modifications, on procède de la même manière que pour un nouveau fichier:

  1. on effectue les modifications de manière habituelle,
  2. avec la commande git add on ajoute les fichiers modifiés à la liste des fichiers à committer dans la zone d’attente,
  3. on committe les changements avec git commit.
  4. on pousse le commit sur Bitbucket avec git push.

Prochaines étapes: historique, revenir en arrière, branches, tags…

Cette introduction a permis de présenter le système de gestion de versions Git et son intérêt pour la rédaction collaborative de documents LaTeX.  Dans le prochaine article, je présenterai certaines fonctionnalités intéressantes de Git et Bitbucket, comme par exemple:

  • l’accès à l’historique des modifications des fichiers du dépôt,
  • comment revenir en arrière sur un ou plusieurs fichiers,
  • comment identifier avec une étiquette précise certaines versions du projet (par exemple, la version envoyée pour relecture aux autres collègues, la version imprimée en début d’année…)
  • comment travailler sur plusieurs versions du document en même temps (par exemple pour préparer la deuxième édition du livre tout en corrigeant les éventuelles coquilles de la première édition)

La suite dans le prochain article donc!

PS: une partie de cet article est basée sur du contenu initialement créé par Maïeul Rouquette. Je vous invite à consulter son article qui présente son utilisation de Git (sans bitbucket) dans le cadre de la rédaction d’une thèse ou d’un mémoire par un seul auteur.

1 commentaire sur “1”

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *