Flux de travail git + LaTeX


270

J'écris un très long document dans LaTeX. J'ai mon ordinateur de travail et mon ordinateur portable, et je travaille sur les deux. Je dois garder tous les fichiers synchronisés entre les deux ordinateurs et je voudrais également conserver un historique des révisions. J'ai choisi git comme DVCS et j'héberge mon dépôt sur mon serveur. J'utilise également Kile + Okular pour faire le montage. Kile n'a pas de plugin git intégré. Je ne collabore également avec personne sur ce texte. Je pense également à mettre un autre référentiel privé sur codaset, si mon serveur pour une raison quelconque n'est pas accessible.

Quelle est la pratique de workflow recommandée dans ce cas? Comment la ramification peut-elle être intégrée dans ce schéma de travail? Existe-t-il un moyen de comparer deux versions du même fichier? Et l'utilisation d'une cachette?

Réponses:


390

Modifications de votre flux de travail LaTeX:

La première étape d'une gestion efficace d'un flux de travail Git + LaTeX consiste à apporter quelques modifications à vos habitudes LaTeX.

  • Pour commencer, écrivez chaque phrase sur une ligne distincte . Git a été écrit dans le code source du contrôle de version, où chaque ligne est distincte et a un objectif spécifique. Lorsque vous écrivez des documents dans LaTeX, vous pensez souvent en termes de paragraphes et l'écrivez comme un document fluide. Cependant, dans git, les modifications apportées à un seul mot dans un paragraphe sont enregistrées comme une modification de l'ensemble du paragraphe.

    Une solution est d'utiliser git diff --color-words(voir ma réponse à une question similaire Comment utiliser Mercurial pour le contrôle de version de documents texte? Où je montre un exemple). Cependant, je dois souligner que la division en lignes distinctes est une bien meilleure option (je ne l'ai mentionnée qu'en passant dans cette réponse), car je l'ai trouvée entraînant des conflits de fusion très minimes.

  • Si vous avez besoin de regarder le code diff, utilisez le diff natif de Git. Pour voir la différence entre deux validations arbitraires (versions), vous pouvez le faire avec les shas de chacune des validations. Voir la documentation pour plus de détails et aussi Affichage des fichiers qui ont changé entre deux révisions .

    D'un autre côté, si vous avez besoin de regarder le diff de votre sortie formatée , utilisez latexdiffce qui est un excellent utilitaire (écrit en perl) qui prend deux fichiers latex et produit une sortie diffed nette en pdf comme ceci ( source d'image ):

    Vous pouvez combiner gitet latexdiff(plus latexpandsi nécessaire) dans une seule commande en utilisant git-latexdiff (par exemple git latexdiff HEAD^pour afficher la différence entre votre worktree et la dernière mais une validation).

  • Si vous écrivez un long document dans LaTeX, je suggère de diviser différents chapitres en leurs propres fichiers et de les appeler dans le fichier principal à l'aide de la \include{file}commande. De cette façon, il est plus facile pour vous de modifier une partie localisée de votre travail, et il est également plus facile pour le contrôle de version, car vous savez quelles modifications ont été apportées à chaque chapitre, au lieu d'avoir à le comprendre à partir des journaux d'un grand fichier.

Utiliser Git efficacement:

  • Utilisez des branches! . Il n'y a peut-être pas de meilleur conseil que je puisse donner. J'ai trouvé que les branches étaient très utiles pour garder une trace des "idées différentes" pour le texte ou pour "différents états" du travail. La masterbranche doit être votre corps de travail principal, dans son état "prêt à publier" le plus récent, c'est-à-dire que si parmi toutes les branches, s'il y en a une que vous êtes prêt à mettre votre nom dessus, ce devrait être la branche principale.

    Les succursales sont également extrêmement utiles si vous êtes un étudiant diplômé. Comme tout étudiant diplômé en attestera, le conseiller est tenu de faire de nombreuses corrections, dont la plupart ne sont pas d'accord. Pourtant, on peut s'attendre à ce que vous les changiez au moins pour le moment, même s'ils sont annulés plus tard après les discussions. Ainsi, dans de tels cas, vous pouvez créer une nouvelle branche advisoret apporter des modifications à leur guise, tout en conservant votre propre branche de développement. Vous pouvez ensuite fusionner les deux et choisir ce dont vous avez besoin.

  • Je suggérerais également de diviser chaque section en une branche différente et de ne concentrer que la section correspondant à la branche sur laquelle vous vous trouvez. Générez une branche lorsque vous créez une nouvelle section ou des sections factices lorsque vous effectuez votre commit initial (votre choix, vraiment). Résistez à l'envie de modifier une section différente (disons, 3) lorsque vous n'êtes pas sur sa branche. Si vous devez modifier, validez celui-ci, puis extrayez l'autre avant de créer une branche. Je trouve cela très utile car il conserve l'historique de la section dans sa propre branche et vous indique également en un coup d'œil (à partir de l'arborescence) l'âge d'une section. Peut-être avez-vous ajouté des éléments à la section 3 qui nécessitent des modifications à la section 5… Bien sûr, ceux-ci seront, selon toute probabilité, observés lors d'une lecture attentive, mais je trouve utile de le voir en un coup d'œil afin de pouvoir changer de vitesse si je'

    Voici un exemple de mes branches et fusions d'un article récent (j'utilise SourceTree sous OS X et Git depuis la ligne de commande sous Linux). Vous remarquerez probablement que je ne suis pas l'auteur le plus fréquent du monde et que je ne laisse pas de commentaires utiles tout le temps, mais ce n'est pas une raison pour vous de ne pas suivre ces bonnes habitudes. Le principal message à retenir est que le travail dans les succursales est utile. Mes pensées, mes idées et mon développement se déroulent de manière non linéaire, mais je peux les suivre via des branches et les fusionner lorsque je suis satisfait (j'avais également d'autres branches qui ne menaient nulle part et qui ont ensuite été supprimées). Je peux également «taguer» les commits s'ils signifient quelque chose (par exemple, soumissions initiales à des revues / soumissions révisées / etc.). Ici, je l'ai étiqueté "version 1", où se trouve le brouillon à partir de maintenant. L'arbre représente une semaine '

  • Une autre chose utile à faire serait de faire des modifications à l'échelle du document (comme passer \alphaà \betapartout) par elles-mêmes. De cette façon, vous pouvez annuler les modifications sans avoir à annuler quelque chose d'autre avec lui (il y a des façons de le faire en utilisant git, mais bon, si vous pouvez l'éviter, alors pourquoi pas?). Il en va de même pour les ajouts au préambule.

  • Utilisez un dépôt à distance et envoyez régulièrement vos modifications en amont. Avec des fournisseurs de services gratuits comme GitHub et Bitbucket (les deux vous permettent de créer des dépôts privés avec un compte gratuit), il n'y a aucune raison de ne pas les utiliser si vous travaillez avec Git / Mercurial. À tout le moins, considérez-le comme une sauvegarde secondaire (j'espère que vous en avez une principale!) Pour vos fichiers LaTeX et un service qui vous permet de continuer à éditer d'où vous êtes parti sur une autre machine.


6
@Diego: Il a fallu un peu de temps pour s'y habituer, car votre esprit veut juste le lire en continu. Cependant, c'est en fait plus facile parce que je (et la plupart des gens) regarde la sortie en latex soignée pour voir si les phrases ont du sens et pour les relire. L'utilisation de ces ruptures n'a aucun effet sur la sortie et facilite beaucoup la différence. De plus, vous pouvez lier la sortie latex au fichier source, donc si vous repérez une erreur ou une faute de frappe, tout ce que vous avez à faire est de cliquer dessus et cela vous amènera directement au point correspondant dans la source.
abcd

1
J'utilise une approche similaire, mais comment gérez-vous les chiffres ou autres fichiers binaires, pouvez-vous les gérer également ou existe-t-il une autre approche pour les fichiers qui devraient être inclus dans le dépôt sans suivi de version?
liborw

6
Ce sont des conseils pratiques, sauf un dont je ne vois pas l'utilité: une branche par section. Vous pouvez facilement voir les modifications par fichier, alors pourquoi augmenter la complexité du flux de travail en ajoutant une couche supplémentaire de séparation? git [log|show|add] some_file.textout fonctionne, pas besoin d'ajouter la commutation de branche constante ici. Vous pouvez toujours valider chaque fichier seul si vous le souhaitez.
rubenvb

1
@rubenvb Si vous divisez chaque section en différents fichiers, alors oui. Je travaille généralement (et beaucoup de gens dans les milieux universitaires) avec un seul fichier tex par article. Les fichiers individuels ont un sens pour les livres / thèses, où chaque chapitre contient une grande quantité de matériel. Bien sûr, ce ne sont que des suggestions ... chacun devrait choisir et rejeter les conseils en fonction de ce qui convient à son flux de travail :)
abcd

2
@yoda ah je vois. Oui, alors cela a du sens. J'ai tendance à forcer plusieurs fichiers tex sur les journaux de toute façon ;-).
rubenvb

12

J'ai également un flux de travail similaire. Même si une branche est en cours d'élaboration à la fois, je trouve avantageux d'avoir des branches distinctes pour différents états de travail. Par exemple, imaginez envoyer une bonne ébauche de votre document à votre conseiller. Ensuite, vous avez une idée folle! Vous voulez commencer à changer certains concepts de base, retravailler certaines sections principales, etc. etc. Donc, vous bifurquez et commencez à travailler. Votre branche principale est toujours dans un état «libérable» (ou aussi proche que vous êtes à ce moment-là). Ainsi, alors que votre autre branche est folle et a des changements drastiques, si un autre éditeur veut voir ce que vous avez, ou si vous êtes un étudiant soumettant à une conférence, la branche principale est toujours libérable, prête à partir (ou prête à montrer votre conseiller). Si votre directeur de thèse souhaite voir le projet de texte le matin,

Disons que votre branche principale a l'état "libérable" de votre travail. Vous voulez maintenant le soumettre à plusieurs revues à comité de lecture, chacune ayant des exigences de mise en forme différentes pour le même contenu et vous vous attendez à ce qu'elles reviennent avec plusieurs petites critiques différentes sur la façon dont vous pouvez éditer le papier pour l'adapter à leurs lecteurs, etc. Vous pouvez facilement créer une branche pour chaque journal, apporter des modifications spécifiques au journal, soumettre et, lorsque vous recevez les commentaires, apporter les modifications sur chaque branche distincte.

J'ai également utilisé Dropbox et git pour créer le système que vous décrivez ci-dessus. Vous pouvez créer un référentiel à nu dans votre dossier dropbox. Vous pouvez ensuite pousser / tirer de n'importe quel ordinateur vers votre boîte de dépôt pour rester à jour à toutes les fins. Ce système ne fonctionne généralement que lorsque le nombre de collaborateurs est faible car il existe une possibilité de corruption si les gens essaient de pousser au dépôt Dropbox en même temps.

Techniquement, vous pouvez également simplement conserver UN référentiel dans le dossier Dropbox et faire tout votre travail à partir de là. Je découragerais cependant cela, car les gens ont mentionné que dropbox a du mal à synchroniser les fichiers qui changent constamment (fichiers internes gits).


3
Notez simplement que la soumission d'un article pour examen par des pairs à plusieurs revues / conférences en même temps n'est généralement pas considérée comme éthique!
Supernormal

7

J'ai essayé de l'implémenter comme une fonction bash, je l'ai inclus dans mon ~/.bashrcpour le rendre toujours disponible.

function git-latexdiff {    
    if [[ $# != 2 ]];    
    then      
        printf "\tusage: git-latexdiff <file> <back-revision>  \n";    
    elif [[ $2 -lt 0 ]];     
    then     
        printf "\t<Back-revision> must be positive\n";   
    else      
        dire=$(dirname $PWD/$1);      
        based=$(git rev-parse --show-toplevel);      
        git show HEAD~$2:$(echo $dire| sed 's!'$(echo $based)'/!!')/$1 > $1_diff.tmp;      
        latexdiff $1 $1_diff.tmp > $1_diff.tex;      
        pdflatex $1_diff.tex;     
        okular $1_diff.pdf;      
        rm $1_diff*;   
    fi; 
}

Notez que cette fonction doit latexdiffêtre installée (et se trouver sur le chemin). Il est également important pour lui de trouver pdflatexet okular.

Le premier est ma façon préférée de traiter LaTeX, vous pouvez donc également le modifier latex. Le second est mon lecteur PDF, je suppose que vous voudrez utiliser evincesous gnome, ou une autre solution.

Il s'agit d'une version rapide, faite avec un seul document à l'esprit, et c'est parce qu'avec git, vous perdrez beaucoup de temps et d'efforts pour suivre un document LaTeX multi-fichiers. Vous pouvez également laisser git effectuer cette tâche, mais si vous le souhaitez, vous pouvez également continuer à utiliser\include


Gardez à l'esprit que les références LaTeX ne rentreront pas dans les visualisations générées. Et aussi que le fichier généré est supprimé en fin de fonction. Comme je l'ai dit, c'est une version rapide.
Rafareino

1
La proposition d'utiliser latexdiff appelé comme assistant gif est plus complète dans cette réponse à Utilisation latexdiffavec git
juandesant

Que voulez-vous dire par "gif helper", @juandesant?
Rafareino

1
Désolé, @Rafareino, je voulais dire "git helper": un git helper est un outil qui peut être invoqué par git pour certaines opérations. Dans ce cas, vous pouvez utiliser l' latexdiffoutil de ligne de commande simplement en utilisant git diff, si vous le configurez correctement.
juandesant

3

Une autre option consiste à utiliser Authorea qui est une sorte de Github pour les articles scientifiques. Chaque article dans Authorea est un dépôt Git. Et le LaTeX que vous composez est rendu en HTML5 (ainsi qu'en PDF, lorsque vous compilez).


Il s'agit d'un fil ancien, et l'idée est d'héberger tout sur place. Authorea est cool, mais pas ce que je cherchais.
Ivan

5
Vous devez indiquer clairement que vous êtes un co-fondateur
Authorea

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.