Un diagramme GitGraph est un composant de visualisation spécialisé utilisé par les développeurs, les équipes DevOps et les rédacteurs techniques pour communiquer clairement les stratégies de branche Git, la gestion des versions et les flux de développement. Intégré nativement dans Mermaid.js, le gitGraph moteur utilise un modèle de timeline déclaratif et séquentiel. Cela permet de mapper directement les commandes du terminal du monde réel à une carte visuelle de timeline précise, sans nécessiter d’édition manuelle d’images.
Comprendre la matrice de timeline GitGraph
Contrairement aux schémas de flux de système en libre-forme, un diagramme GitGraph suit une logique stricte, séquentielle et basée sur l’ordre d’apparition, modélisant des espaces de travail de contrôle de version réels :
- Branchement racine automatique : Chaque espace de travail de diagramme initialisé crée automatiquement une piste principale de timeline racine. Par défaut, cette piste est nommée
main, et toutes les actions ultérieures s’inscrivent sur celle-ci, sauf si un chemin de branche alternatif propre est créé. - Préférence d’ordre : Les éléments s’affichent selon un axe chronologique de gauche à droite, en fonction de l’ordre d’insertion des commandes dans votre fichier source de code.
Structure de syntaxe de base
Chaque timeline commence par le mot-clé en casse de chameau gitGraph mot-clé de déclaration. Il est suivi d’une colonne séquentielle listant des commandes d’exécution atomiques telles que des validations, des changements de branche et des fusion.
gitGraph
commit
commit
branch feature-login
checkout feature-login
commit
checkout main
merge feature-login
La référence complète des commandes d’action Git
Le moteur de mise en page interprète des commandes d’action spécifiques en minuscules pour faire évoluer les épaisseurs de lignes, diviser les pistes ou fusionner les extrémités ensemble sur la toile de l’espace de travail.
| Jetons de commande Git | Modificateurs d’arguments de paramètre | Comportement technique des actions et de la mise en page |
|---|---|---|
commit |
id: "hash", type: TYPE, tag : "v1.0" |
Ajoute un nouveau nœud de repère directement sur la ligne du chemin de branche cible active. |
branche |
nom, ordre : Entier |
Crée une nouvelle séparation de voie de branche. Vous pouvez forcer sa position de superposition verticale en utilisant un explicite facultatifordre valeur. |
checkout / changer |
nom-de-branche |
Déplace le pointeur d’index d’enregistrement actif vers la ligne de branche cible spécifiée. Les actions ultérieures suivent cette voie. |
fusionner |
nom-de-branche-cible, id : "hachage", tag : "v2" |
Fusionne la voie de branche spécifiée dans la branche actuelle, créant un point d’intersection visuel distinct. |
cherry-pick |
id : "hachage-de-commit", parent : "hachage-parent" |
Duplique un commit spécifique provenant d’une branche externe sur la voie de branche actuelle sans fusionner les voies. |
Fonctionnalité avancée : Types de commits et personnalisation des balises
Pour distinguer entre les correctifs réguliers, les annulations de système ou les versions majeures, vous pouvez attribuer un explicitetype et tag modificateur de chaîne à l’intérieur d’un bloc d’argument utilisant des propriétés clé-valeur de type JSON.
Classifications de forme de validation prises en charge :
type : NORMAL: La configuration par défaut. S’affiche sous la forme d’un nœud circulaire plein le long de la ligne de chronologie.type : REVERSE: Met en évidence un retour arrière architectural ou programmatique. S’affiche sous la forme d’un nœud circulaire plein barré ($X$).type : HIGHLIGHT: Appelle l’attention sur des modifications structurelles critiques ou des correctifs de sécurité. S’affiche sous la forme d’une boîte rectangulaire allongée et remplie.
gitGraph
commit id : "Initial"
commit type : HIGHLIGHT id : "Security-Hotfix" tag : "v1.0.1"
commit type : REVERSE id : "Rollback-Feature-X"
Fonctionnalité avancée : Logique de cherry-pick et contraintes strictes
Le cherry-pick commande copie un nœud isolé spécifique depuis une autre branche vers votre branche active actuelle. Pour exécuter un cherry-pick sans provoquer d’erreurs de disposition du compilateur, vous devez respecter ces exigences strictes de validation de l’espace de travail :
- Contrainte d’exclusion : L’identifiant de validation cible que vous effectuez un cherry-pick *ne doit pas* déjà exister sur la branche que vous suivez actuellement.
- Historique préalable : La ligne de branche active actuelle doit contenir au moins un nœud de validation valide avant d’appeler une action de cherry-pick.
- Exigence de parent de fusion : Si vous effectuez un cherry-pick sur un nœud de fusion, vous devez passer explicitement la chaîne d’identification du parent direct immédiat à l’aide du bloc
parent : "hash"bloc de modificateur.
gitGraph
commit id : "setup"
branch staging
checkout staging
commit id : "feature-patch"
checkout main
commit id : "baseline"
cherry-pick id : "feature-patch"
Fonctionnalité avancée : Configurations des paramètres de frontmatter
Vous pouvez affiner les comportements visuels globaux (comme basculer les étiquettes de branche, modifier les index de ligne ou empiler les chronologies) en déclarant un %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% bloc de directive de configuration en haut absolu de votre script de graphique.
Matrice des paramètres configurables
| Chaîne de clé de configuration | Définition du type | Valeur par défaut | Résultat de modification de l’interface visuelle |
|---|---|---|---|
showBranches |
Booléen | true |
Bascule la visibilité des étiquettes de suivi individuelles de branche sur le côté gauche de la grille du canevas. |
showCommitLabel |
Booléen | true |
Bascule le rendu des titres texte et des hachages alphanumériques directement au-dessus des nœuds individuels de la chronologie. |
mainBranchName |
Chaîne | "main" |
Change le texte de suivi du nom de la branche racine par défaut (par exemple, en remplaçant par "master" ou "trunk"). |
mainBranchOrder |
Entier | 0 |
Définit l’indice de position dans l’ordre de superposition verticale du haut vers le bas pour la voie de suivi principale de la chronologie racine. |
parallelCommits |
Booléen | faux |
Si modifié à vrai, les validations distinctes qui partagent des distances identiques aux étapes parentes s’alignent de manière symétrique sur le même niveau vertical. |
Maquette du monde réel : pipeline de gestion des versions Git-Flow pour entreprise
Cette maquette complète pour entreprise démontre un pipeline de versionnement de production standard. Elle remplace les paramètres de configuration pour renommer la voie racine en trunk, établit une hiérarchie d’ordre fixe des branches, utilise plusieurs voies de branches (develop et feature-auth), exécute des fusionnages, applique des balises personnalisées et déploie des formes de validation à haute priorité.
%%{init: { 'gitGraph': { 'mainBranchName': 'trunk', 'showCommitLabel': true } } }%%
gitGraph
commit id: "Initial-Core" tag: "v1.0.0"
commit id: "Setup-CI"
branch develop
checkout develop
commit id: "Sprint-1-Base"
branch feature-auth
checkout feature-auth
commit id: "JWT-Logic"
commit id: "MFA-Logic" type: HIGHLIGHT
checkout develop
merge feature-auth id: "Merge-Auth"
commit id: "Beta-Compiled"
checkout trunk
merge develop id: "Release-Prod" tag: "v2.0.0"
Péchés courants de syntaxe et contraintes du système
Lors de la compilation de graphiques de contrôle de version précis, gardez ces paramètres de dépannage à l’esprit pour éviter les bogues de calcul du layout :
- Erreurs de sensibilité à la casse : La déclaration d’initialisation principale doit être écrite en camelCase explicite comme
gitGraph. L’écrire entièrement en minuscules commegitgraphprovoquera un plantage du compilateur lors de l’analyse. - Identifiants alphanumériques non entre guillemets : Lors du passage de paramètres de validation personnalisés (par exemple,
id: core_init), les valeurs contenant des traits d’union, des espaces ou des points *doivent* être encloses entre guillemets doubles. Oublier les blocs de guillemets entraînera des erreurs de compilation de validation. - Cibles de checkout non valides : Appel à un
checkout nom_de_brancheaction sur une identité de chaîne qui n’a pas été initialisée auparavant à l’aide de labranche nom_de_branchecommande interrompra instantanément la construction du graphe. - Conflits d’ordre des branches : Lors de l’utilisation de la
ordrebalise de configuration sur les branches, assurez-vous que plusieurs pistes ne soient pas mappées sur des entiers identiques, sauf si vous souhaitez des traces de chemins sur la toile qui se superposent. Gardez les numéros de piste des branches uniques. - Échecs de séparation par espace : Assurez-vous qu’il existe des espaces clairs entre les arguments lors de la séparation des propriétés à l’intérieur des matrices de paramètres parenthésées (par exemple, utilisez
id : "1", type : SOULIGNER). Omettre des virgules ou des espaces manquants peut provoquer des exceptions de parsing.