Geekographie Maïeulesque

Stage LaTeX Dunkerque : Git

Maïeul — 2019-06-12T06:00:00Z

Je présente au Stage LaTeX de Dunkerque une initiation à Git. Vous trouverez ci-dessous mon support de présentation.

Présentation sur l'utilisation de Git

Comme d'habitude, les sources sont sur Framagit.

Ma politique de branches avec Git

Maïeul — 2019-06-02T17:39:33Z

En préparant mon intervention sur Git au Stage LaTeX de juin, je me suis dit qu'il pouvait être utile que je résume, succinctement, ma politiquement de branchement avec Git.

Elle n'a rien de très original, mais je la trouve pratique, et je me la suis plus ou moins construite avec le temps, notamment à cause de mon travail sur (r)(e)ledmac.

Principe numéro 1 : la branche `master` doit être utilisable à tout moment

Contrairement à SVN où le trunk sert souvent de branche de développement, la facilité de créer des branches en git fait qu'il vaut mieux garder une branche master toujours prête à fonctionner.

C'est pourquoi je ne commite jamais directement dans master, sauf pour corriger des coquilles dans le manuel.

Principe numéro 2 : une branche par `issue`

Pour chaque issue (ticket) ouvert, je crée une branche homonyme issueXXX où XXX est le numéro de l'issue.

Le premier commit de la branche contient un exemple complet minimal, permettant de cerner le problème.

Le dernier commit contient l'effacement de cet exemple, ainsi que l'enregistrement des logs de changement dans le fichier .dtx. Son message habituel est changelog + fixe #XXX. Le fixe #XXX permet de fermer automatiquement l'issue lors de la fusion dans master.

Je demande à la personne ayant ouvert l'issue de tester à partir de ces branches.

Si la résolution d'un ticket dépend de la résolution d'un autre ticket, je fusionne d'une branche à l'autre.

Si une personne rouvre une issue fermée, deux solutions :

soit je considère qu'il s'agit en fait d'un problème différent, et dans ce cas je demande de rouvrir une nouvelle issue ;
soit j'avais mal résolu le problème, et dans ce cas je crée une branche issueXXX-bis.

Principe numéro 3 : jamais de rebasage ou de fast-forward, toujours de la fusion de branche

Le principe de créer des branches est de pouvoir faire des développements parallèles. Il importe que la trace de ces développements parallèles soit conservée même une fois finis les développements. C'est pourquoi je ne rebase jamais les branches une fois un développement achevé, et je refuse les fast-forward.

Ainsi qu'expliqué ailleurs, le rebasage ne devrait être conservé que pour gérer le cas où mon dépôt distant et mon dépôt local n'ont plus le même historique. Comme je travaille quasiment seul, cela m'arrive rarement.

J'ai donc dans mon .gitconfig global les lignes suivantes :

 [pull] ff = only rebase = preserve [merge] ff = false

Principe numéro 4 : une branche par release

Avant de sortir (« releaser ») une nouvelle version, je crée une branche. Le nom de cette branche correspond au numéro de version de la future release. Dans le cas de reledmac, comme en plus reledpar n'a pas le même numéro de version, j'utilise un tiret pour séparer les deux numéros. Cela donne donc x1.y1.z1-x2-y2-z2.

Dans cette branche :

je fusionne les branches fonctionnelles / de débogage ;
je corrige le cas échéant le changelog, pour adapter à la date effective de sortie ;
je procède aux tests automatiques.

Puis je fusionne avec master, d'où je prépare la sortie effective.

Principe numéro 5 : une branche par version majeure

Avant reledmac, ils y avaient eledmac et ledmac. Dans mon système de codification, reledmac est la version 2, eledmac la version 1 et ledmac la version 0. J'ai donc une branche 1 et une branche 0 pour les rares cas où j'accepte d'intervenir sur ces anciennes versions [1].

Principe numéro 6 : une branche pour la relecture de l'anglais

Comme je demande régulièrement à des personnes de relire l'anglais et le manuel de reledmac/reledpar, j'ai créé une branche english2 [2]. Cette branche contient l'état des fichiers après la dernière relecture par une correcteurtrice. Je m'en sers pour proposer de ne relire que les nouvelles modifications en comparant english2 et master.

Principe numéro 7 : ne pas conserver les branches fusionnées

Une fois une branche fusionnée, je la supprime en local comme en distant.

Appendice : principe de numérotation des tags et des release

J'utilise un système simple de numérotation sur le mode x.y.z

Un changement de x indique une rupture majeure, impliquant de grands changements. Dans le monde LaTeX, je change également le nom, pour faciliter la compatibilité ascendante des documents.
Un changement de y indique de nouvelles fonctionnalités.
Un changement de z indique une correction de bug.
Parfois j'ajoute une lettre (a, b, c, etc.) pour indiquer une simple correction dans le manuel.

Mes tags correspondent simplement au numéro de version (pas de v. devant). Dans le cas de reledmac-reledpar, comme les deux paquets sont liés sur le dépôt et en distribution, mais sont néanmoins distincts, mes tags ont la forme macx1.y1.z1-parx2.y2.z2.

J'ai enfin des tags sur tests abandonnés, que je garde plus pour me dire « si jamais il me revient à l'idée de reprendre ce projet ».

[1] Principalement pour corriger des ruptures de comptabilité apportées par les évolutions de LaTeX.

[2] 2 parce que cela concerne reledmac, cf. plus haut.

Stage LaTeX à Dunkerque

Maïeul — 2019-05-06T16:58:29Z

Comme chaque année, l'IUT de génie thermique de Dunkerque, ou plus exactement Denis Bitouzé, organise un stage d'une journée. Cette année, le stage LaTeX aura lieu le 12 juin prochain.

Le stage nécessite une inscription préalable, et ne coût que 6 € de participation aux frais.

J'y présenterai deux interventions :

biblatex et biber : gérer sa bibliographie avec des outils ﬂexibles et modernes
Gérer son historique de ﬁchiers LaTeX avec Git

Sauvegarder et partager son historique git

Maïeul — 2015-11-28T18:56:30Z

Il y a fort, fort longtemps, j'ai écrit une petite introduction à Git pour expliquer à un.e chercheur.euse utilisant LaTeX comment versionner son travail. Je poursuis ici, en expliquant comment envoyer son historique Git sur un serveur, afin d'avoir d'une part une copie de sauvegarde, et d'autre part de pouvoir travailler avec d'autres personnes.

Objectifs

Contentons-nous d'objectifs simples :

ouvrir un dépôt git distant
y envoyer une copie de notre dépôt local
mettre régulièrement à jour cette copie
la récupérer depuis un autre ordinateur et faire la synchronisation

Principes de base

Avec Git, l'historique du travail est conservé sur l'ordinateur de travail, dans ce qu'on appelle un dépôt git. Il est cependant possible de créer un dépôt git sur un autre ordinateur, et de le synchroniser avec notre propre dépôt. Les avantages sont évidemment multiples :

pour la personne qui travaille sur une seule machine, avoir un copie de sauvegarde en plus de celle de sa machine.
pour la personne qui travaille sur plusieurs machines, pouvoir synchroniser les historiques entre les machines
pour les personnes qui travaillent sur le même projet, pouvoir se synchroniser.

Nous allons prendre un cas simple :

deux dépôts locaux de travail : (A) et (B)
un dépôt distant de synchronisation et sauvegarde (C)

Utiliser un serveur pour synchroniser ses historiques git

XX travaille sur (A). Il y enregistre l'historique de ses modifications. À la fin de sa session de travail, il les envoie sur (C). Au début de sa session de travail, YY récupère l'historique depuis (C) et le met sur (B). À la fin de sa session, il envoie ses modifications sur (C). Quand XX reprend le travail, il récupère depuis (C) vers (A), puis envoie sur (C) ses nouvelles modifications à la fin de sa session, etc.

Je prends un cas simple dans la mesure où je suppose que chaque personne récupère l'historique sur (C) avant de travailler, et renvoie son historique à la fin de son travail. En outre XX et YY ne travaille pas en parallèle. Si bien lorsqu'on travaille tant sur (A) que sur (B), on a forcément tout ce qui existe déjà sur (C).

Git permet de gérer les cas où XX récupère l'historique sur (C) pour le mettre en (A), et pendant qu'il travaille YY envoie des données sur (B). Cependant, je n'aborderai pas, ici en tout cas, ce problème.

Il permet également de travailler avec plusieurs dépôts distants, mais une chose à la fois.

Communication entre les dépôts

Puisque les données de (A) (et de (B)) doivent être envoyées vers le dépôt (C), il nous faut :

Savoir où se trouve le dépôt (C), autrement dit connaître son adresse. Très souvent l'adresse d'un dépôt distant est de la forme git@serveur:utilisateur/nom.git.
référencer ce dépôt distant depuis le dépôt local. Comme il est possible de lier un dépôt local à plusieurs dépôts distants (remote), chaque adresse de dépôt distant se verra ajouter un alias. Pour notre cas, nous allons utiliser un seul dépôt distant, dont l'alias sera « origin », un terme conventionnel.
faire quelques petits réglages pour permettre à votre ordinateur de communiquer avec l'ordinateur sur lequel se trouve le dépôt de manière sécurisée et authentifiée.

Création et réglage d'un compte chez Framasoft

Choix de Framasoft

N'importe quel serveur ayant une installation Git peut héberger un dépôt Git distant. Il vous est donc possible de demander à une institution de rattachement (Université, Centre de Recherche). Il existe cependant des structures proposant non seulement des dépôts Git, mais aussi des interfaces graphiques pour les gérer et d'autres outils.

La plus célèbre de ces structures est l'entreprise Github. Pour ma part, je vous proposerai d'utiliser les services de l'association Framasoft, pour diverses raisons :

pour éviter de concentrer l'internet en quelques pôles, le plus souvent privés.
parce que Framasoft est une association, et non une entreprise.
parce que l'infrastructure proposée tourne sous logiciel libre, et que vous pourrez vous même monter un jour votre propre serveur avec la même interface.
parce qu'elle permet de créer gratuitement des dépôts privés, accessibles à vous seulement, alors que Github ne le propose que contre argent [1].

Création d'un compte

Rendons-nous donc sur la page d'accueil du service Git de Framasoft, choisissons « Sign In » [2]. Remplissez les informations pour créer le compte, dans la rubrique « New user ? Create an account ». Vous recevrez un mail contenant un lien pour confirmer la création de votre compte. Cliquez sur le lien.

Vous êtes automatiquement authentifiés après la validation du compte. Cependant il vous faudra sans doute vous reconnecter les prochaines fois, via « Existing user ? Sign in », en choisissant non pas la connexion « LDAP » mais « Standard ».

Création d'une paire de clef SSH et mise en ligne de la clef publique

Pour que votre ordinateur puisse envoyer et récupérer l'historique sur le serveur de Framasoft, il faut qu'il communique avec lui en lui prouvant qu'il est bien votre ordinateur, et pas celui d'un tiers.

Plusieurs méthodes sont possibles. L'une est de frapper un mot de passe à chaque nouvelle communication, l'autre d'utiliser un système de clefs SSH.

Pour faire court, vous disposerez d'une clef privée, à garder secrète, et d'une clef publique, à fournir au serveur de Framasoft. Nous allons donc générer ces clefs et envoyer la clef secrète sur le serveur. La génération de ces clefs se fait via le Terminal (sous Mac et Linux) ou le Git Shell (sous Windows).

Tout d'abord vérifier qu'il n'y a pas de clefs déjà générées via :

cat ~/.ssh/id_rsa.pub

Si vous n'obtenez rien, alors c'est qu'il n'y a pas de clefs. Il vous faut donc les générer, via :

ssh-keygen -t rsa -C "email@fournisseur"

En remplaçant email@fournisseur par votre adresse courriel.

Après le retour ligne, une nouvelle ligne apparaît, commençant par « Enter file in which to save the key ». Faite alors un simple retour ligne, pour prendre la valeur par défaut.

Ensuite il est proposé « Enter passphrase ». Choisissez une phrase servant à crypter vos clefs. Donc comprenant des espaces. Ne prenez pas une phrase existante [3]. Votre ordinateur stockera normalement cette phrase de passe dans votre trousseau d'accès. Après votre retour ligne, on vous demande de reconfirmer votre phrase de passe. Faites-le donc.

Ouf, les clefs sont générées !

Il vous rester à fournir la clef publique à Framasoft, on ouvrant le fichier ~/.ssh/id_rsa.pub et en copiant le contenu dans le presse papier. Attention, il vous faut bien copier le fichier finissant par .pub, et pas un autre !

Puis sur votre compte Framasoft, vous rendre sur « Profile Settings », puis l'onglet « SSH Keys », et utiliser le formulaire proposé après « Add SSH Keys ».

Création de votre dépôt distant et mis en relation avec le dépôt local

Il vous faut maintenant créer votre dépôt distant, sur votre compte Framasoft. Sur la page de Framasoft, utilisez le « + » en haut à droite pour créer un « New Projects ».

Dans « Projet Path » mettre le nom de votre dépôt. Par exemple « these ». N'oubliez pas non plus de choisir la visibilité : entre Private (privée) / Internal (visible après authentification chez Framasoft) / Public (accessible à tout.es)

Après validation du formulaire, votre dépôt distant est vide. Il vous faut donc lier votre dépôt local au dépôt distant pour y envoyer les informations. Pour cela, suivre les instructions proposées par Framasoft sous « Command line instruction : existing folder or Git repository ».

Donc :

se rendre en ligne de commande à l'emplacement de votre dépôt local.
y copier-coller la ligne proposée par Framasoft commençant par « git remote add origin ». Ceci permet de lier le dépôt distant au dépôt local en appelant le dépôt distant « origin ». Par exemple dans le cas de ma thèse, j'ai mis :
```
git remote add origin git@git.framasoft.org:maieul/these.git
```

Ce qui signifie que je relie le dépôt distant situé à l'adresse git@git.framasoft.org:maieul/these.git à mon dépôt local, en donnant comme alias à ce dépôt distant origin.

Envoyer l'historique sur le serveur distant

Au premier envoi de l'historique sur le serveur distant, il vous faut procéder ainsi [4] :

git push -u origin master

Il se peut que votre ordinateur vous demande à ce moment de frapper la « phrase de passe » de votre clef SSH. Il ne devrait le faire qu'une seule fois, l'enregistrant dans son gestionnaire de mot de passe pour les fois suivantes.

Les envois les fois suivantes peuvent se faire avec juste

git push -u origin master

Récupérer l'historique du serveur distant

Supposons maintenant que vous avez un deuxième ordinateur. Vous souhaitez récupérer le dépôt git distant.

Évidemment pour ce faire il vous faut connaître l'adresse du dépôt distant. Rien de bien sorcier : lorsque vous vous connectez avec votre compte sur l'interface web de Framasoft, celui-ci vous liste « Your projects », c'est à dire vos dépôts [5]. Choisissez le dépôt qui vous intéresse.

Tout en haut de la page de chaque dépôt est indiqué de manière très claire son adresse.

Récupérer l'adresse d'un dépôt distant chez Framasoft

Une fois que vous avez copié l'adresse, Il vous suffit simplement de frapper dans votre terminal :

git clone adressedudepotdistant

Ceci va récupérer l'ensemble de l'historique du dépôt distant et le copier en local en un nouveau dépôt. Ce dépôt sera automatiquement relié au dépôt distant [6]. Vous pourrez donc y envoyer vos modifications de l'historique avec git push.

Il ne vous reste donc plus qu'à récupérer l'historique du dépôt distant dans votre dépôt local avant chaque session de travail, via :

git pull

Partager les tags

Dans mon précédent article, j'expliquais comment ajouter des tags pour marquer les grandes étapes du travail. Il faut savoir que les tags ne sont pas envoyés au serveur via git push. Il vous faut envoyer manuellement les tags via git push --tags. De même pour les récupérer, il faut utiliser git pull --tags.

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

[1] Ce qui est normal, puisqu'il s'agit d'une entreprise à but lucratif.

[2] « S'identifier ».

[3] Vous pouvez, et même devez, prendre quelque chose n'ayant aucun sens comme « Le rat du chat est devenu fou en mangeant des champignons atomiques. ».

[4] Ce qui signifie « envoyer vers le dépôt git la branche master », en disant que la branch « master » local va suivre la branche « master » du dépôt « origin ». Une branche correspond à une succession de commit. Il est possible de d'avoir plusieurs branches, mais ce n'est pas la question.

[5] À l'heure où j'écris ces lignes, Framasoft propose 42 dépôts par compte. Si vous dépassez cela, il est conseillé de monter son propre serveur d'hébergement Git.

[6] Autrement dit le git remote add origin xxx ne sera pas nécessaire.

Hook de pre-commit pour fichier .dtx, .sty et autres fichiers de package

Maïeul — 2015-02-21T19:51:12Z

Dans un précédent article, je parlais de mon hook de pré-commit pour vérifier l'ajout de de % à la fin de chaque ligne dans un fichier .dtxy ou .sty.

J'ai amélioré ce hook pour lui ajouter d'autres fonctions de vérifications utiles lorsqu'on crée des packages LaTeX.

Principe

Les fichiers .dtx permettent de documenter un code LaTeX en même temps qu'on le saisit. Il nécessite cependant une syntaxe rigoureuse, et il m'arrive parfois de faire quelques erreurs.

Installation

Rien ne changer : télécharger le hook, l'installer dans le dossier .git/hook, le renommer pre-commit, et faire un chmod +x dessus.

Fonctionnalité

Fins de ligne

La fonction principale reste, bien sûr : impossibilité de commiter si un ligne non vide ne finit pas par un %, ou si ce % est précédé d'un ou plusieurs espaces.

Commande `\cs{}`

Impossible de commiter si l'argument d'une commande \cs commence par un \

Environnement `macro` et `macrocode`

Impossible de commiter si le début ou la fin de l'environnement n'est pas sur une ligne spécifique.
Vérification du nombre d'espaces entre le % et le \begin ou \end : 1 pour macro et 4 pour macrocode. Impossible de commiter dans le cas contraire.
Vérification des appareillement d'environnement. Attention, on ne vérifie pas les éventuelles suppressions de début/fin d'environnement. Impossible de vérifier dans le cas contraire.
Vérifier que le nom de la macro est bien mentionné après \begin{macro}.


		
		Comme avant, le code est versionné sur Github.



Un hook de pre-commit pour s'assurer d'ajouter des % en fin de ligne
Maïeul — 2014-08-10T19:53:08Z
Lorsqu'on crée une commande LaTeX, il est quasi-obligatoire de mettre un « % » à la fin de chaque ligne pour éviter les espaces indésirables.
Si vous versionnez votre code avec Git, il est possible de vérifier automatiquement la présence de ces %, grâce à un hook de pre-commit. Le hook empêchant l'ajout de ligne sans ce %.
		Pourquoi mettre des % en fin de ligne à la fin des commandes ?
En TeX, les fins de lignes sont considérés comme des simples espaces. Ce qui pose problème si on fait tenir un commande sur plusieurs lignes.
Prenons par exemple la commande suivante, relativement simple :
\newcommand{\nom}[1]{ \index{#1} \textbf{#1}
}
Si on l'appelle ainsi,
La pensée de \nom{Tertullien} a changé au cours des temps.
On constate des espaces indésirables avant et après « Tertullien » (souligné pour les besoins de la démonstration) :


La pensée de _Tertullien_ a changé au cours des temps.

Pour éviter cela, il faut insérer un % à la fin de chaque ligne :
\newcommand{\nom}[1]{% \index{#1}% \textbf{#1}%
}
Ce qui éviter d'avoir des espaces indésirables


La pensée de Tertullien a changé au cours des temps.
Un hook de pre-commit
Un « hook », au sens Git, est un script, écrit dans un language quelconque (perl, python, bash) qui est exécuté lorsque certains actions git ont lieu, dans le cas qui nous intéresse, juste avant un commit.
Le script peut envoyer des informations sur le Terminal, il peut modifier des fichers, il peut aussi faire échouer une action de Git, par exemple le commit.
J'ai donc créé un hook qui vérifie, sur les fichiers de .cls (définition de classe), .sty (définition de package), .dtx (documentation de package et de classe, .bbx, .lbx, .cbx (styles biblatex), qu'il n'y a pas, lors d'un commit, de lignes modifiés finissant sans %, à l'exception des lignes vides.
Le hook ne fonctionne pas sur les .tex car les fonctions devraient être définies dans des .sty, et qu'il ne faudrait pas forcer les % en fin de ligne dans les .tex, comme le prouve l'exemple suivant :
Ce serait une mauvaise%
idée.
Pour faire fonctionner le hook :



 Hook de pre-commit
 Dernière version stable. Licence GPL 3.
 

-* le télécharger
 Le déplacer dans le dossier invisible .git/hooks dans le dépôt git local.
 Le renommer pre-commit.
 Lui donner les droits d'éxecutions (chmod +x).
C'est tout !
Désormais, il vous sera impossible de commiter par erreur une ligne ne finissant pas par %.
		
		Le code est versionné sur Github.


Garder un historique de son travail grâce à Git
Maïeul — 2012-02-05T14:49:04Z
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 (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.

 
 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 :
# On branch master # # Initial commit # # Untracked files: # (use "git add ..." to include in what will be committed) # #	principal.tex
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 :
[master (root-commit) e6328ab] mon fichier principal, avec juste les packages minimum 1 files changed, 6 insertions(+), 0 deletions(-) create mode 100644 principal.tex
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 branch master # Changes not staged for commit: # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # #	modified: principal.tex # no changes added to commit (use "git add" and/or "git commit -a")
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 :
diff --git a/principal.tex b/principal.tex index a61d523..042e384 100644 --- a/principal.tex +++ b/principal.tex @@ -2,5 +2,8 @@ \usepackage{fontspec} \usepackage{xunicode} \usepackage{polyglossia} +\author{Moi} +\title{Mon mémoire} \begin{document} +\maketitle \end{document} \ No newline at end of file
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 :
commit 5c2b1ee8bcd7e1b6d22c13b2703e978b59d1cc81 Author: maieul  Date: Sun Feb 5 14:36:59 2012 +0100 titre et nom de l'auteur commit e6328ab55747c5f673345d64147d6ed806e111a0 Author: maieul  Date: Sun Feb 5 13:30:09 2012 +0100 mon fichier principal, avec juste les packages minimum
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.
		
		Un autre article sur le sujet par Xavier Lüthi.
		
		
[1] Il 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.

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

[3] Il 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.

[4] Si 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.

[5] La 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.

Geekographie Maïeulesque

Stage LaTeX Dunkerque : Git

Ma politique de branches avec Git

Principe numéro 1 : la branche master doit être utilisable à tout moment

Principe numéro 2 : une branche par issue

Principe numéro 3 : jamais de rebasage ou de fast-forward, toujours de la fusion de branche

Principe numéro 4 : une branche par release

Principe numéro 5 : une branche par version majeure

Principe numéro 6 : une branche pour la relecture de l'anglais

Principe numéro 7 : ne pas conserver les branches fusionnées

Appendice : principe de numérotation des tags et des release

Stage LaTeX à Dunkerque

Sauvegarder et partager son historique git

Objectifs

Principes de base

Communication entre les dépôts

Création et réglage d'un compte chez Framasoft

Choix de Framasoft

Création d'un compte

Création d'une paire de clef SSH et mise en ligne de la clef publique

Création de votre dépôt distant et mis en relation avec le dépôt local

Envoyer l'historique sur le serveur distant

Récupérer l'historique du serveur distant

Partager les tags

Hook de pre-commit pour fichier .dtx, .sty et autres fichiers de package

Principe

Installation

Fonctionnalité

Fins de ligne

Commande \cs{}

Environnement macro et macrocode

Un hook de pre-commit pour s'assurer d'ajouter des % en fin de ligne

Pourquoi mettre des % en fin de ligne à la fin des commandes ?

Un hook de pre-commit

Garder un historique de son travail grâce à Git

Versionner, quesaco ?

Pourquoi versionner son travail ?

Quels outils choisir ?

Pré-requis

Notion de bases

Paramètrage de Git

Commencer le versionnage d'un projet

Versionner son premier fichier

Modifier son premier fichier

Consulter l'historique

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

Marquer des étapes : la notion de tag

Conclusion

Principe numéro 1 : la branche `master` doit être utilisable à tout moment

Principe numéro 2 : une branche par `issue`

Commande `\cs{}`

Environnement `macro` et `macrocode`

Marquer des étapes : la notion de `tag`