Garder un historique de son travail grâce à Git

dimanche 5 février 2012, mise à jour mercredi 14 novembre 2018, par Maïeul
Suivre la vie du site RSS 2.0 Forum

Cet article sort un peu de l’ordinaire. Je ne viens pas y donner des techniques LaTeX, mais expliquer comment garder un historique de son travail lorsqu’on utilise LaTeX. Pour cela, je propose de passer par le logiciel de gestion des versions Git.

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 (Xe)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.

Les trois états d’un fichiers dans Git
Schéma par Scott Chacon, sous licence CC-by-nc-sa 3.0

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.

P.-S.

Un autre article sur le sujet par Xavier Lüthi.

Documents joints

Notes

[1Il n’existe pas de version française sous forme PDF. On peut toutefois fabriquer la sienne en récupérant les sources sur le site Github. Toutefois la fabrication de ce PDF passe par des outils qu’il faut installer sur son ordinateur (en plus de LaTeX). C’est pourquoi je vous propose une version que je me suis faite pour moi même en juillet dernier.

[2L’avantage, c’est que Git pourra fabriquer pour vous le stemma codicum.

[3Il existe des logiciels de comparaison de versions permettant de contourner ce problème, mais ceci nécessiterait sans doute un autre tutoriel, une chose à la fois.

[4Si cette identifiant semble avoir un nom imprononçable, c’est parce qu’il s’agit d’une version « résumé » du commit, qui permet de vérifier qu’il n’y a pas eu de corruption de la base de donnée. On appelle cela un hash.

[5La notion de master est un brin complexe : elle est liée au travail par branche. Disons simplement que master désigne, dans un système avec une seule branche, l’état des fichiers à la date la plus récente dans l’historique.

Vos commentaires

  • Le 5 février 2012 à 18:29, par Thomas En réponse à : Garder un historique de son travail grâce à Git

    Sympa de voir un article qui parle de git avec un exemple très concret qui sort de la programmation « pure et dure ». Merci et félicitations.

    Deux petites remarques :

    • « git add principal.tex » n’est nécessaire qu’une seule fois, pour dire à git de suivre le fichier. Il est inutile de répéter la commande ensuite.
    • pour revenir en arrière, regarder plutôt du côté de « git revert »
  • Le 5 février 2012 à 18:41, par Maïeul En réponse à : Garder un historique de son travail grâce à Git

    Merci pour cette réaction.

    Deux points :

    • le git add est tout le temps nécéssaire, pour faire passer de l’état « modifié » à l’état « prêt à être commité », sauf si tu fais un git commit -a
    • tout a fait d’accord pour le git revert, sauf que le git revert revient à annuler des modifications, et pas revenir à un état donné. Ce n’est pas tout à fait la même approche, et je pense que pour une première étape, il faut garder l’idée de « revenir à l’étape 2 » et non pas « annuler les changements entre l’étape 2 et l’étape 3 ». De plus, si mon fichier a été modifié après le commit que l’on souhaite reverter, il faut gérer soit même la résolution des conflits. Pour un tutoriel, destiné à des non informaticiens, cela fait un peu trop à la fois :-)
  • Le 5 février 2012 à 20:46, par Brent Longborough En réponse à : Garder un historique de son travail grâce à Git

    Depuis quelques années j’utilise « git » pour gérer mes documents, et il est vraiment bon.

    Récemment, j’ai découvert SmartGit, une excellente interface graphique pour Git, que je recommande à tous vos lecteurs.

    http://www.syntevo.com/smartgit/index.html

    Pardonnez, s’il vous plaît, mon français affreux et oxidé.

  • Le 5 février 2012 à 20:52, par Maïeul En réponse à : Garder un historique de son travail grâce à Git

    merci, je ne connaissais pas de Gui pour git sous licence libre … et toujours pas

  • Le 4 avril 2012 à 01:22, par Severo En réponse à : Garder un historique de son travail grâce à Git

    Un petit détail, c’est pas

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

    mais

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

    sans les « = »

    Merci pour le tuto, c’est bien expliqué

  • Le 4 avril 2012 à 10:13, par Maïeul En réponse à : Garder un historique de son travail grâce à Git

    merci,

    effectivement, je corrige.

  • Le 5 juillet 2012 à 20:45, par JN En réponse à : Garder un historique de son travail grâce à Git

    Par rapport à la note indiquant qu’il n’y a pas de pdf, le projet de traduction française (dont je suis) publie un pdf et des ebooks les dernières versions en date

  • Le 5 juillet 2012 à 22:52, par Maïeul En réponse à : Garder un historique de son travail grâce à Git

    yep, j’avais pas trouvé à l’époque, mais effectivement, merci !

Qui êtes-vous ?

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Acheter XeLaTeX appliqué aux sciences humaines

À propos

Titulaire d’un doctorat en théologie et d’un doctorat en histoire, sous la direction conjointe de Frédéric Amsler et d’Élisabeth_Malamut, je commence à partir du 1er août 2017 un travail d’édition critique des Actes de Barnabé.

Dans le cadre de la rédaction de mon mémoire de master puis de ma thèse de doctorat, j’ai été emmené à utiliser LaTeX, et j’ai donc décider de partager mes techniques. En effet, au cours de mes premiers apprentissages, j’ai découvert que les ressources indiquant les outils pour l’utilisation de LaTeX en sciences humaines étaient rares. Ceci m’a conduit à maintenir ou créer plusieurs packages LaTeX et à donner plusieurs formations.

J’ai reçu en 2018 le prix DANTE e.V pour mon travail autour de LaTeX, en particulier autour de reledmac et reledpar.

Par ailleurs, je suis membre actif de la communauté SPIP, au sein de laquelle j’administre le site Spip-Contrib. Je propose sur ce site quelques notes sur SPIP, en général à destination de webmestre.

Il m’arrive également de faire un petit peu de Python, de temps en temps.

Enfin, je tiens un blog de réflexions politiques et religieuses.

Maïeul