Versionner, quesaco ?

Un mémoire, ou une thèse, cela évolue en permanence. On fait parfois des retours en arrière, on souhaite parfois écrire des brouillons que finalement on ne conservera pas etc.

Les logiciels de type WYSIWYG (comme Word et LibreOffice) proposent en général des outils permettant d’avoir un historique des modifications. Que faire si on utilise (X^e)LaTeX ?

Les fichiers LaTeX étant des simples fichiers texte, le plus facile est d’utiliser un système de gestion de version dont se servent les informaticiens. Ces outils permettent en général :

• de travailler à plusieurs sur un même projets, 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 morceaux dans deux sens différents.
• d’avoir un historique de toutes les modifications, et donc de pouvoir le cas échéant revenir en arrière.
• 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 marquants, permettant de retrouver facilement l’état du projet à un moment donné (par exemple avant la première soumission au directeur, ou au moment de la déposition etc.)

Pourquoi versionner son travail ?

Pour une personne non informaticienne, cela peut paraître un luxe d’utiliser un tel outil. Pourtant pour un rédacteur en sciences humaines, choisir de versionner son travail a de nombreux avantages :

• si on hésite sur la modification d’une formulation, on peut l’effectuer tout en ayant la garantie de retrouver ensuite la formulation initiale en cas de volte-face.
• le fait d’associer un message à chaque modifications aide — en tout cas pour ma part — à décomposer sa rédaction en petites étapes, à se concentrer sur un point à la fois.
• en théorie, on pourrait combiner un outils de gestions des modifications avec un outils de suivi des tâches à effectuer (par exemple : « corriger telle partie », « vérifier telle référence » etc.)

Quels outils choisir ?

Il existe actuellement trois outils majeurs de suivis des version :

• SVN, qui tend à devenir archaïque et manque de souplesse comparativement aux deux autres.
• Mercurial, que je ne connais pas.
• Git, qui connais un succès semble-t-il grandissant, et qui est plus adapté que SVN pour :
  • Commencer facilement à gérer ses versions avec une seule personne.
  • Tout en pouvant basculer facilement vers un mode de type multi-rédacteurs.

C’est donc Git que j’ai choisi de présenter dans cet article. La présentation sera succincte, et ne vise qu’à expliquer les bases :

• pour un seul rédacteur
• pour une rédaction de type linéaire, avec simplement la possibilité de marquer les jalons, et éventuellement de faire des retours en arrière.

Pour aller plus loin, je conseille l’excellent livre ProGit, qui est sous licence libre [1].

Pré-requis

Pour pouvoir utiliser Git, la manière la plus efficace est de se servir de la ligne de commande, même s’il existe des interfaces graphiques. Rien de bien méchant toutefois. J’ai expliqué dans un autre article comment utiliser LaTeX en ligne de commande. Ce que j’y ai écrit reste valable pour Git, il faut simplement changer les commandes.

Il faut bien sûr installer Git, pour cela, il suffit de se rendre sur le site officiel puis de suivre le chemin « Download » correspondant à son système d’exploitation.

Sous Windows, l’installation ajoute un programme Git Shell. Il faudra y saisir toutes lignes de commandes.

Notion de bases

La notion de base gestion de versions est la notion de « commit ». Gardons ce terme anglais tel quel, puisqu’il correspond à l’une des commandes que vous aurez à frapper dans votre Terminal.

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

Exemple : j’ai le fichier contenant la ligne suivante :

Le petit chat es mort

et autres fautes du même type. Je procède à une correction générale de l’orthographe. À la fin de cette correction, je souhaite enregistrer mes modifications dans l’historique des modifications. Je fais alors 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, 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 le répertoire de travail, ou working directory.
• 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, ou staging area.
• il a été commité, et il est donc présent dans l’historique, ou repository.

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

Les commandes de base de Git servent à faire passer d’une zone à l’autre.

Paramètrage de Git

Nous avons dit que chaque commit contenait le nom de la personne qui l’a effectué. S’il est possible de préciser à chaque fois qui est la personne, il est plus simple de donner un nom par défaut, en configurant Git une fois pour toutes.

Vous me direz « à quoi cela sert, puisque je suis le seul à faire des modifications ? ». Je vous répondrais qu’un jour, peut-être, vous utiliserez Git à plusieurs, alors autant prendre les bonnes habitudes tout de suite !

Donc une fois Git installé, nous allons indiquer :

• l’auteur par défaut
• son courriel

Pour cela, il suffit de se rendre dans le Terminal, et frapper (le % représente l’invite de commande) :

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

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

À noter que si vous êtes plusieurs à vous partager l’ordinateur en ayant chacun un compte, ce réglage ne concerne que votre compte.

Commencer le versionnage d’un projet

Ces premiers réglages effectués, nous pouvons maintenant nous attaquer au problème du versionnage du mémoire / de la thèse.

Rendons nous avec le terminal dans le dossier de rédaction du mémoire.

% cd chemin_vers_mon_dossier_de_memoire

Puis indiquons que nous souhaitons désormais versionner les fichiers de ce dossier :

% git init

Cette commande n’est à mettre en œuvre qu’une seule fois.

Versionner son premier fichier

Créons notre premier fichier, un fichier .tex simple, principal.tex :

\documentclass[a4paper]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\begin{document}
\end{document}

Maintenant frappons dans le terminal :

% git status

Cette commande va nous indiquer l’état des fichiers :

Pour le moment, oubliez les lignes 1 à 4. Sachez simplement que ces lignes vous serviront le jour où vous voudrez créer une branche divergente de votre mémoire [2].

Nous avons l’indication des qu’il existe un fichier principal.tex qui n’est actuellement pas pris en compte par Git.

Ajoutons ce fichier dans la liste des fichiers qui vont devoir être commités :

% git add principal.tex

Puis effectuons le commit, en mettant comme message « mon fichier principal, avec juste les packages minimum » :

% git commit -m "mon fichier principal, avec juste les packages minimum"

On obtient alors un les lignes suivantes dans le terminal :

Ces lignes nous indiquent :

• une version abrégé de l’identifiant du commit : e6328ab.
• le message de commit.
• le contenu du commit.

Modifier son premier fichier

Reprenons notre fichier principal.tex et ajoutons les informations sur l’auteur et le titre

\documentclass[a4paper]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\author{Moi}
\title{Mon mémoire}
\begin{document}
\maketitle
\end{document}

Et dans le terminal, regardons ce que nous indique la commande git status :

On nous indique gentiment que le fichier principal.tex n’est pas indiqué pour être commité. Nous allons donc l’ajouter dans la liste des fichiers à commiter. Mais avant, vérifions quand même les modifications apportées, avec la commande :

git diff

On obtient (avec de la couleur) les lignes suivantes :

Passons sur les lignes à 5 qui indique « simplement » quels sont les fichiers comparés : en l’occurence, il s’agit d’une comparaison entre le fichier principal.tex tel qu’il se trouve actuellement et le même fichier dans sa version la plus récente au sein de l’historique.

Remarquons simplement que les lignes commençant par un + sont des lignes ajoutées. Les lignes commençant par un moins sont celles supprimées. Et si on modifie une ligne ? Alors on obtient une ligne - et une ligne +.

Pour cette raison, il est conseillé d’avoir une phrase par ligne dans le fichiers .tex source, pour voir plus facilement les modifications. [3]

Bref, maintenant commitons ces différences. D’abord indiquons qu’il faut ajouter le fichier principal.tex, puis commitons :

% git add principal.tex
% git commit -m "titre et nom de l'auteur"

On comprendra que si chaque commit possède un message descriptif rapide, et si on respect correctement cette règle, on travaillera sa rédaction par étape successive, ce qui est en général plutôt une saine habitude ...

Consulter l’historique

Il peut être utile d’avoir l’historique des commits. Pour ce faire, on utilise la commande :

% git log

Nous obtenons alors :

On nous indique à chaque fois :

• l’identifiant unique du commit (par ex 5c2b1ee8bcd7e1b6d22c13b2703e978b59d1cc81 [4]).
• son auteur, avec son courriel.
• sa date et son heure.

Il est possible de passer des options à la commande git log pour ne sélectionner les commits que sur certains critères (par exemple de dates, ou de fichiers modifiés) : je renvoie à ProGit.

Reprendre un fichier tel qu’il était à un instant donné

Supposons que pour x raison, je souhaite finalement reprendre le fichier principal.tex tel qu’il était dans l’historique au niveau du commit e6328ab55747c5f673345d64147d6ed806e111a0.

Il me suffit de faire :

%git checkout e6328ab55747c5f673345d64147d6ed806e111a0 principal.tex

On ne peut le faire que si les fichiers sont dans la même état que la dernière version enregistrée dans l’historique.

À noter qu’en général, on peut se contenter des six premiers caractères :

%git checkout e6328a principal.tex

À ce moment là, mon fichier principal.tex est remplacé par sa version du commit e6328a. Je peux dès lors enregistrer dans l’historique le retour à cette version :

% git add principal.tex
% git commit -m "en fait, je ne voulais pas de titre : revenons à l'état e6328ab55747c5f673345d64147d6ed806e111a0 pour le fichier principal.tex"

En revanche, supposons que je ne voulais que consulter l’état du fichier au commit e6328ab55747c5f673345d64147d6ed806e111a0, mais ne souhaitais pas y revenir. J’ai effectué ma consultation, et maintenant j’aimerais retrouver la version la plus à jour.

La solution est simple [5] :

% git checkout master

Marquer des étapes : la notion de tag

Si la consultation de l’historique est utile, il peut être plus simple de retenir automatiquement les grands jalons de votre travail. Par exemple : tel qu’il est avant que vous le relisiez, tel qu’il est avant que vous ne le confiez à la relecture de vos proches, tel qu’il est avant que vous ne le confiez à le relecture de votre directeur, tel qu’il est au moment où vous le déposez pour soutenance.

Le plus simple pour ce faire est de poser un tag. Un tag, c’est simplement une étiquette posée sur un commit donné.

Supposons que vous êtes arrivé au bout de vos peines, et souhaitez marquer la version que vous allez donner à votre directeur, pour ultime validation.

Vous poser alors un tag qui possède :

• un identifiant
• un petit message d’explication

Après avoir vérifier via git status que vous n’avez aucune modification à enregistrer dans l’historique, vous frappez :

% git tag -a "directeur_dec2011" --amend "version remise au directeur, en décembre 2011"

Vous venez ainsi de poser un tag. Vous pouvez continuer à travailler tranquillement. Le jour où vous souhaiterez obtenir à nouveau la version que vous lui avez remise, il vous suffira de faire :

% git checkout directeur_dec2011

Et si vous avez oublié le nom de votre tag, vous pourriez facilement retrouver la liste des tags, en frappant :

%git tag

Et même obtenir les messages assignés à chaque tag, en utilisant :

%git tag -n

Conclusion

Si j’ai été bon, vous savez désormais avoir un historique de vos modifications, revenir facilement à un état donné, marquer les principales étapes du travail. Bravo !

Il y aurait encore beaucoup de chose à dire, par exemple :

• dire à Git de ne pas se préoccuper de certains fichiers, comme par exemple les .aux.
• comment annuler les modifications d’un commit, sans pour autant revenir à l’état antérieur à ce commit.
• comment corriger un commit que l’on vient d’effectuer.
• comment gérer plusieurs versions du travail en parallèles (branches).
• comment partager ses modifications avec d’autes utilisateurs pour un travail collaboratif.
• etc.

Si j’ai le courage je ferais des tutoriels sur chacun de ces sujets. Mais déjà avoir un historique de son travail garanti la possibilité de revenir en arrière le cas échéant. Le reste n’est plus qu’affinage : vous trouverez aisément sur internet les outils pour le faire.