Utiliser Git pour collaborer simplement sur des articles en Latex

Publié le 13 juillet 2018 dans [ latex, git ]

J’ai récemment collaboré avec d’autres chercheurs pour écrire des articles en Latex, versionnés avec Git. Certains collègues me demandant à quel point c’est simple, je me suis dit que j’allais rédiger un petit aide-mémoire des commandes.

Initialisation

On va dans le dossier de l’article (éventuellement déjà commencé), on initialise le dépôt :

$ cd <leDossierDuProjet>
$ git init 
Dépôt Git vide initialisé dans <leDossierDuProjet>/.git/

On ajoute un .gitignore pour que Git ne suive pas les modifications des fichiers temporaires :

$ wget http://raphael.fournier-sniehotta.fr/files/tex.gitignore -O .gitignore
$ git add .gitignore
$ git commit -m"premier commit, avec gitignore latex."

On ajoute les premiers fichiers :

$ vim main.tex # on crée le fichier principal main.tex s'il n'existe pas encore
$ git add main.tex abstract.tex subject.bib # on place en général abstract et bibliographie dans des fichiers séparés
$ git commit -m "premier commit de l'article." # commit simple, pas de long message, une ligne après "-m"

On met en place le lien avec le dépôt distant, sur Bitbucket ou sur le serveur du labo :

$ git remote add origin git@bitbucket.org:<username>/<distantRepo>.git
$ git push origin master

Travail régulier

On revient plusieurs jours après sur l’article. On regarde donc si des collègues ont avancé, et on récupère les modifications éventuelles :

$ git pull

On peut lire les messages de commits décrivant les contributions des collègues avec :

$ git log

On rédige ou édite le texte, on termine ensuite par une validation (commit). On vérifie d’abord quels fichiers ont été modifiés, avec git status :

$ git status

On inclut ceux que l’on veut dans le prochain commit :

$ git add main.tex foo.tex bar.bib
$ git commit

J’omets volontairement le -m après ce git commit, pour rédiger un message long. Une fenêtre d’édition s’ouvre, c’est le moment d’écrire un bon message de commit. La première ligne résume ce que vous avez fait. Les lignes suivantes peuvent donner les détails.

Note : Il est à mon avis préférable de faire de longs messages de commits envoyés automatiquement par mails aux collègues, plutôt que de mauvais messages de commits et des bons mails rédigés ensuite… (dans le premier cas, on fait le travail une fois, et il peut re-servir à ceux qui n’étaient pas initialement dans la boucle de mails).

Une fois qu’on a validé son ou ses commits, il faut envoyer (pousser) ça au dépôt distant :

$ git push

Il suffit ensuite de répéter le cycle git pull, travail, git add, git commit, git push.

Usages avancés

Revenir à une version antérieure

On utilise l’historique pour trouver l’identifiant de la version à laquelle on souhaite revenir :

$ git log 
\* 4f80f0b - Acknowledgements (il y a 8 mois) <UserA>
\* 463f054 - Passe réduction 8 pages (il y a 8 mois) <UserB>
\* 9d36e57 - Modification figures (il y a 8 mois) <UserB>
\* 6e12986 - soumission confA (il y a 9 mois) <UserC>

On ramène le main.tex à la version 9d36e47 :

$ git checkout 9d36e57 main.tex

On travaille dessus, et on valide :

$ vim main.tex
$ git add main.tex
$ git commit

Remarques et astuces

  • on ne parle pas ici de branches, même si c’est l’un des intérêts de git. On peut se contenter de faire du mono-branche.

  • on peut ajouter les lignes suivantes dans le fichier de configuration de git pour améliorer l’ordinaire

[alias]
 co = checkout
 ci = commit
 st = status
 ll = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

On pourra ainsi écrire git add toto.tex ; git ci -m"ajout de toto.tex manquant dans le commit précédent" pour faire des petits commits rapides de correction. Et surtout, git ll au lieu de git log pour naviguer rapidement dans l’historique du dépôt.

  • Conseil : Activez les notifications par mail automatique sur le dépôt distant, pour que tout le monde reçoive une alerte à chaque commit des collègues (avec un “bon message de commit” :-))

  • il existe de nombreuses options pour permettre à git d’afficher des diff entre deux commits tenant compte des mots, comme git diff --word-diff.