Un générateur de graphe Git
Tags: git, graphviz, bash
Published: 2023-09-28 06:36:16

Afin d'illustrer mes supports de formations avec des graphes Git, j'ai développé un outil que j'ai nommé [gitgraph2dot](https://gitlab.com/csgroup-oss/gitgraph2dot/).

<!--more-->

Il y a environ dix ans, quand j'ai initié mes supports de formation à Git, j'ai assez naturellement récupéré les illustrations du livre [Pro Git](https://git-scm.com/book/en/v2).
Les illustrations étant réalisées avec un outil non libre, je me suis contenté à l'époque des images.
Et lorsque j'ai voulu rajouter des exemples, j'ai bricolé comme j'ai pu.

Mais récemment, j'ai considéré que c'était vraiment trop limitant et que ça me conduisait parfois à un manque d'homogénéité ou tout simplement que ça me freinait dans la créativité.
J'ai alors entrepris un chantier consistant à remettre en cause cet état de fait et partir sur une nouvelle base.

## Les prérequis

Facilitateur DevOps ascendant maniaco-scripteur, hors de question de partir sur un clicodrome où on passe des heures à ajuster le look & feel ou l'alignement.
Au contraire, la solution doit s'appuyer sur une description, de préférence en textuelle, facile à gérer dans Git.

Et des outils pour générer des graphes Git à partir d'une description textuelle, finalement on en trouve pas mal.
Voire, comme toujours, on en trouve trop et il faut identifier le bon.

## Mermaid

Quand on fouille dans ce tas, naturellement on en trouve beaucoup à l'abandon et pas mal dont on ne sait pas prédire l'avenir.
Du coup, il parait naturel de se réorienter vers la solution qui semble faire l'unanimité dans beaucoup de solutions Web : [mermaid](https://mermaid.js.org/).

Et très franchement, son extension [pour les diagrammes Git](https://mermaid.js.org/syntax/gitgraph.html) est vraiment séduisante.
Jugez plutôt : on énumère les commit, les branches, les merges... comme si on saisissait les commandes dans un terminal et l'outil nous génère un graphe.
C'est simple, explicite, facile à relire et à faire évoluer.

Mais... les schémas sont trop orientés « workflow » à mon gout.
Qu'est-ce que j'entends par là ?
Dans les diagrammes généré par mermaid, les branches sont représentées comme des lignes de chemin de fer sur lesquelles viennent se poser des commits, des débranchements et des fusions.

![Un exemple de graphe Git généré avec Mermaid](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q8hpn0ises96iky57c1g.png)

D'un point de vue « workflow » c'est tout à fait acceptable et explicite.
Mais d'un point de vue « formation Git » c'est trompeur, ça laisserait penser qu'un commit *appartient* à une branche.
Or, justement, dans mes formations Git, ce sur quoi j'insiste, c'est que « les branches n'existent pas » ou en tout cas les commits vivent leur vie indépendamment des branches et que ces dernières ne sont qu'un moyen d'accéder au graphe des commits.

## gitgraph2dot

L'outil `gitgraph2dot` reprend les concepts du fichier d'entrée décrivant une séquence de commandes Git mais génère un graphe dans lequel les branches sont présentées, comme dans le livre « Pro Git », comme des références qui pointent des commits.

![Exemple de graphe Git généré avec gitgraph2dot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/stuslcc0dnmmfbp33c47.png)

Et comme j'aime bien la simplicité, il s'agit d'un simple script Bash qui se limite a traduire la description textuelle du graphe Git en instructions pour la commande `dot` du projet [Graphviz](https://graphviz.org/).
« Keep it simple » on vous dit.

## Conclusion

En attendant que mermaid propose un graphe Git dans lequel on puise ajuster la logique de rendu des branches, n'hésitez pas à télécharger ce script et à l'utiliser pour vos schéma, voire venir contribuer au projet, c'est sous GPL.

https://gitlab.com/csgroup-oss/gitgraph2dot/