Mermaid.js GitGraph-Diagram-Syntaxleitfaden

Ein GitGraph-Diagramm ist eine spezialisierte Visualisierungskomponente, die von Entwicklern, DevOps-Teams und technischen Schreibern verwendet wird, um Git-Branching-Strategien, Release-Management und Entwicklungsabläufe klar zu kommunizieren. Integriert nativ in Mermaid.js, die gitGraphEngine verwendet ein deklaratives, sequentielles Zeitachsenmodell. Dies ordnet echte Terminalbefehle direkt einer genauen visuellen Zeitachse zu, ohne manuelle Bildbearbeitung zu erfordern.

Verständnis der GitGraph-Zeitachsen-Matrix

Im Gegensatz zu freiformigen Systemflussdiagrammen folgt ein GitGraph-Diagramm strengen, sequenziellen Logikregeln der Ereignisfolge, die echte Versionskontrollarbeitsbereiche abbilden:

• Automatische Stammbranching: Jeder Diagrammarbeitsbereich, der initialisiert wird, startet automatisch eine primäre Stammzeitachse. Standardmäßig wird diese Spur benannt als main, und alle nachfolgenden Aktionen verfolgen diese, es sei denn, ein sauberer alternativer Branchpfad wird erstellt.
• Reihenfolgepräzedenz: Elemente werden entlang einer chronologischen Achse von links nach rechts basierend auf der Einfügefolge der Befehle in Ihrer Quelldatei gerendert.

Grundlegende Syntaxstruktur

Jede Zeitachse beginnt mit dem camelCase-gitGraphDeklarationsschlüsselwort. Es folgt eine sequenzielle Spaltenliste von atomaren Ausführungsbefehlen wie Commits, Checkouts und Merges.

gitGraph
  commit
  commit
  branch feature-login
  checkout feature-login
  commit
  checkout main
  merge feature-login

Die vollständige Referenz zu Git-Aktionen-Befehlen

Die Layout-Engine interpretiert spezifische, kleine Buchstaben-Befehle, um Linienstärken zu verändern, Spuren zu teilen oder Endpunkte über die Arbeitsbereichsfläche hinweg zu verbinden.

Erweiterte Funktion: Commit-Typen & Tag-Anpassungen

Um zwischen regulären Patches, System-Rückgängigkeiten oder Hauptversionen zu unterscheiden, können Sie einen explizitenTyp und Tag Zeichenfolgenmodifikator innerhalb eines Argumentblocks unter Verwendung von json-ähnlichen Schlüssel-Wert-Eigenschaften.

Unterstützte Commit-Form-Klassifizierungen:

• Typ: NORMAL: Die Standardkonfiguration. Wird als gefüllter, solider Kreis-Knoten entlang der Zeitachsen-Linie gerendert.
• Typ: RÜCKGÄNGIG: Hebt eine architektonische oder programmmäßige Rücksetzung hervor. Wird als durchkreuzter, solider Kreis-Knoten ($X$) gerendert.
• Typ: HIGHLIGHT: Zeigt auf kritische strukturelle Änderungen oder Sicherheitspatches hin. Wird als verlängertes, gefülltes Rechteck-Box gerendert.

gitGraph
  commit id: "Initial"
  commit typ: HIGHLIGHT id: "Security-Hotfix" tag: "v1.0.1"
  commit typ: RÜCKGÄNGIG id: "Rollback-Feature-X"

Erweiterte Funktion: Cherry-Pick-Logik und strenge Einschränkungen

Die Cherry-Pick Befehl kopiert einen bestimmten isolierten Knoten von einer anderen Branch-Linie auf Ihre aktuelle aktive Branch. Um einen Cherry-Pick ohne Compiler-Layout-Fehler auszuführen, müssen Sie diese strengen Anforderungen an die Arbeitsraum-Validierung erfüllen:

• Ausschluss-Beschränkung: Die Ziel-Commit-ID, die Sie cherry-picken, *darf* bereits auf der Branch-Linie, die Sie aktuell verfolgen, nicht existieren.
• Voraussetzungs-Geschichte: Die aktuelle aktive Branch-Linie muss mindestens einen gültigen Commit-Knoten enthalten, bevor eine Cherry-Pick-Aktion aufgerufen wird.
• Merge-Eltern-Anforderung: Wenn Sie einen Merge-Knoten cherry-picken, müssen Sie die sofortige direkte übergeordnete Eltern-Identifikationszeichenfolge explizit übergeben, indem Sie den Eltern: "hash" Modifikatorblock verwenden.

gitGraph
  commit id: "setup"
  branch staging
  checkout staging
  commit id: "feature-patch"
  checkout main
  commit id: "baseline"
  cherry-pick id: "feature-patch"

Erweiterte Funktion: Frontmatter-Parameterkonfigurationen

Sie können globale visuelle Verhaltensweisen (wie das Ein- und Ausschalten von Zweigbeschriftungen, die Änderung von Zeilenindizes oder das Stapeln von Zeitachsen) durch die Angabe einer%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% Konfigurationsanweisungsblock am absoluten Anfang Ihres Graphen-Skripts.

Matrix konfigurierbarer Parameter

Real-World-Blueprint: Enterprise-Git-Flow-Release-Management-Pipeline

Dieses umfassende Enterprise-Blueprint zeigt eine Standard-Produktions-Release-Pipeline. Es überschreibt Konfigurationsparameter, um die Stammbahn in trunk, legt eine feste Branch-Reihenfolge-Hierarchie fest, verwendet mehrere Branch-Linien (develop und feature-auth), führt Merge-Operationen aus, wendet benutzerdefinierte Tags an und stellt Commit-Formen mit hoher Priorität bereit.

%%{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"

Häufige Syntax-Fehler & Systembeschränkungen

Beim Kompilieren präziser Versionskontroll-Graphen sollten diese Fehlerbehebungsparameter berücksichtigt werden, um Layout-Berechnungsfehler zu vermeiden:

• Groß-/Kleinschreibung-Fehler: Die primäre Initialisierungsdeklaration muss explizit in camelCase wie folgt geschrieben werden: gitGraph. Wenn es vollständig in Kleinbuchstaben wie gitgraph geschrieben wird, löst dies einen Compiler-Parsing-Crash aus.
• Nicht-gekennzeichnete alphanumerische Bezeichner: Wenn benutzerdefinierte Commit-Parameter übergeben werden (z. B. id: core_init), müssen Werte, die Bindestriche, Leerzeichen oder Punkte enthalten, in doppelte Anführungszeichen eingeschlossen werden. Das Vergessen von Anführungszeichen führt zu Verlust der Validierungs-Compilierungsfehler.
• Ungültige Checkout-Ziele: Aufrufen eines checkout branch_name Aktion auf einer Zeichenfolgen-Identität, die zuvor nicht mit dem branch branch_name Befehl wird die Graph-Erstellung sofort unterbrechen.
• Zweigreihenfolgen-Kollisionen: Wenn die Verwendung des order Konfigurationstag auf Zweigen, stellen Sie sicher, dass mehrere Spuren nicht auf identische Ganzzahlen abgebildet werden, es sei denn, Sie möchten überlappende Pfadspuren auf der Leinwand. Halten Sie die Zweigspurnummern eindeutig.
• Fehler bei der Leerzeichen-Trennung: Stellen Sie sicher, dass klare Argument-Leerzeichen vorhanden sind, wenn Eigenschaften innerhalb von runden Parametermatrizen getrennt werden (z. B. verwenden Sie id: "1", type: HIGHLIGHT). Das Weglassen fehlender Kommas oder Leerzeichen kann zu Parsing-Ausnahmen führen.