Gitgraph-Diagramme

Ein Git-Graph ist eine bildliche Darstellung von Git-Commits und Git-Aktionen (Befehlen) auf verschiedenen Branches.

Diese Art von Diagrammen ist besonders hilfreich für Entwickler und DevOps-Teams, um ihre Git-Branching-Strategien zu teilen. Zum Beispiel macht es die Visualisierung des Git-Flows einfacher.

Mermaid kann Git-Diagramme rendern.

Code:

In Mermaid unterstützen wir die grundlegenden Git-Operationen wie:

• commit: Stellt einen neuen Commit auf dem aktuellen Branch dar.
• branch: Zum Erstellen und Wechseln zu einem neuen Branch, der als aktueller Branch festgelegt wird.
• checkout: Zum Auschecken eines bestehenden Branches und Festlegen als aktuellen Branch.
• merge: Zum Mergen eines bestehenden Branches in den aktuellen Branch.

Mit Hilfe dieser wichtigen Git-Befehle können Sie sehr einfach und schnell ein Gitgraph in Mermaid zeichnen. Entitätsnamen werden oft großgeschrieben, obwohl es keinen akzeptierten Standard dafür gibt und es in Mermaid nicht erforderlich ist.

HINWEIS: checkout und switch können austauschbar verwendet werden.

Syntax

Die Mermaid-Syntax für ein Gitgraph ist sehr unkompliziert und einfach. Sie folgt einem deklarativen Ansatz, bei dem jeder Commit in der Reihenfolge seines Auftretens/Vorhandenseins im Code auf der Zeitachse des Diagramms gezeichnet wird. Im Grunde folgt sie der Einfügeordnung für jeden Befehl.

Als Erstes deklarieren Sie Ihren Diagrammtyp mit dem Schlüsselwort gitgraph. Dieses gitgraph-Schlüsselwort teilt Mermaid mit, dass Sie ein Gitgraph zeichnen und den Diagrammcode entsprechend analysieren möchten.

Jedes Gitgraph wird mit dem Branch main initialisiert. Wenn Sie also keinen anderen Branch erstellen, werden die Commits standardmäßig in den main-Branch aufgenommen. Dies wird durch die Funktionsweise von Git gesteuert, bei der Sie am Anfang immer mit dem main-Branch (früher master-Branch genannt) beginnen. Standardmäßig ist der main-Branch als Ihr aktueller Branch festgelegt.

Sie verwenden das Schlüsselwort commit, um einen Commit auf dem aktuellen Branch zu registrieren. Sehen wir uns an, wie das funktioniert:

Ein einfaches Gitgraph, das drei Commits auf dem Standardbranch (main) zeigt:

Code:

Wenn Sie das vorherige Beispiel genau betrachten, sehen Sie den Standardbranch main zusammen mit drei Commits. Beachten Sie auch, dass jedem Commit standardmäßig eine eindeutige und zufällige ID zugewiesen wurde. Was wäre, wenn Sie einem Commit Ihre eigene benutzerdefinierte ID geben wollten? Ja, das ist mit Mermaid möglich.

Hinzufügen einer benutzerdefinierten Commit-ID

Für einen gegebenen Commit können Sie eine benutzerdefinierte ID zum Zeitpunkt seiner Deklaration mit dem Attribut id angeben, gefolgt von : und Ihrem benutzerdefinierten Wert in einem ""-Anführungszeichen. Beispiel: commit id: "Ihre_benutzerdefinierte_ID"

Sehen wir uns an, wie das mit dem folgenden Diagramm funktioniert:

Code:

In diesem Beispiel haben wir unseren Commits benutzerdefinierte IDs zugewiesen.

Ändern des Commit-Typs

In Mermaid kann ein Commit drei Typen haben, die sich im Diagramm etwas unterschiedlich darstellen. Diese Typen sind:

• NORMAL: Standard-Commit-Typ. Im Diagramm durch einen ausgefüllten Kreis dargestellt.
• REVERSE: Um einen Commit als Reverse-Commit hervorzuheben. Im Diagramm durch einen durchgestrichenen ausgefüllten Kreis dargestellt.
• HIGHLIGHT: Um einen bestimmten Commit im Diagramm hervorzuheben. Im Diagramm durch ein ausgefülltes Rechteck dargestellt.

Für einen gegebenen Commit können Sie seinen Typ zum Zeitpunkt seiner Deklaration mit dem Attribut type angeben, gefolgt von : und der oben beschriebenen erforderlichen Typ-Option. Beispiel: commit type: HIGHLIGHT

HINWEIS: Wenn kein Commit-Typ angegeben ist, wird NORMAL als Standard ausgewählt.

Sehen wir uns an, wie diese verschiedenen Commit-Typen mit Hilfe des folgenden Diagramms aussehen:

Code:

In diesem Beispiel haben wir jedem Commit verschiedene Typen zugewiesen. Sehen Sie auch, wie wir sowohl id als auch type gleichzeitig bei der Deklaration unserer Commits einbezogen haben. Sie können diese Attribute beliebig kombinieren.

Hinzufügen von Tags

Für einen gegebenen Commit können Sie ihn als Tag kennzeichnen, ähnlich dem Konzept von Tags oder Release-Versionen in der Git-Welt. Sie können ein benutzerdefiniertes Tag zum Zeitpunkt der Deklaration eines Commits mit dem Attribut tag anhängen, gefolgt von : und Ihrem benutzerdefinierten Wert in ""-Anführungszeichen. Beispiel: commit tag: "Ihr_benutzerdefiniertes_Tag"

Sehen wir uns an, wie das mit dem folgenden Diagramm funktioniert:

Code:

In diesem Beispiel haben wir den Commits benutzerdefinierte Tags zugewiesen. Sehen Sie auch, wie wir all diese Attribute in einer einzigen Commit-Deklaration kombiniert haben. Sie können diese Attribute beliebig mischen und kombinieren.

Erstellen eines neuen Branches

Um in Mermaid einen neuen Branch zu erstellen, verwenden Sie das Schlüsselwort branch. Sie müssen auch einen Namen für den neuen Branch angeben. Der Name muss eindeutig sein und darf nicht mit dem eines bestehenden Branches übereinstimmen. Ein Branch-Name, der mit einem Schlüsselwort verwechselt werden könnte, muss in "" gesetzt werden. Verwendungsbeispiele: branch develop, branch "cherry-pick"

Wenn Mermaid das Schlüsselwort branch liest, erstellt es einen neuen Branch und legt ihn als aktuellen Branch fest. Äquivalent dazu, dass Sie in der Git-Welt einen neuen Branch erstellen und auschecken.

Sehen wir uns ein Beispiel an:

Code:

In diesem Beispiel sehen Sie, wie wir mit dem Standard-main-Branch begonnen haben und zwei Commits darauf vorgenommen haben. Dann haben wir den develop-Branch erstellt, und alle nachfolgenden Commits werden auf den develop-Branch gesetzt, da er zum aktuellen Branch wurde.

Auschecken eines bestehenden Branches

Um in Mermaid zu einem bestehenden Branch zu wechseln, verwenden Sie das Schlüsselwort checkout. Sie müssen auch den Namen eines bestehenden Branches angeben. Wenn kein Branch mit dem angegebenen Namen gefunden wird, wird ein Konsolenfehler ausgegeben. Verwendungsbeispiel: checkout develop

Wenn Mermaid das Schlüsselwort checkout liest, findet es den angegebenen Branch und legt ihn als aktuellen Branch fest. Äquivalent zum Auschecken eines Branches in der Git-Welt.

Lassen Sie uns unser vorheriges Beispiel modifizieren:

Code:

In diesem Beispiel sehen Sie, wie wir mit dem Standard-main-Branch begonnen haben und zwei Commits darauf vorgenommen haben. Dann haben wir den develop-Branch erstellt, und alle drei nachfolgenden Commits werden auf den develop-Branch gesetzt, da er zum aktuellen Branch wurde. Danach haben wir das Schlüsselwort checkout verwendet, um den aktuellen Branch auf main zu setzen, und alle folgenden Commits werden dem aktuellen Branch, d. h. main, zugeordnet.

Mergen zweier Branches

Um in Mermaid einen bestehenden Branch zu mergen oder zusammenzuführen, verwenden Sie das Schlüsselwort merge. Sie müssen auch den Namen eines bestehenden Branches angeben, der gemerged werden soll. Wenn kein Branch mit dem angegebenen Namen gefunden wird, wird ein Konsolenfehler ausgegeben. Sie können auch nur zwei separate Branches mergen und keinen Branch mit sich selbst. In diesem Fall wird ein Fehler ausgegeben.

Verwendungsbeispiel: merge develop

Wenn Mermaid das Schlüsselwort merge liest, findet es den angegebenen Branch und seinen Head-Commit (den letzten Commit auf diesem Branch) und verknüpft ihn mit dem Head-Commit des aktuellen Branches. Jedes Merge führt zu einem Merge-Commit, der im Diagramm mit einem ausgefüllten Doppelkreis dargestellt wird.

Lassen Sie uns unser vorheriges Beispiel modifizieren, um unsere beiden Branches zu mergen:

Code:

In diesem Beispiel sehen Sie, wie wir mit dem Standard-main-Branch begonnen haben und zwei Commits darauf vorgenommen haben. Dann haben wir den develop-Branch erstellt, und alle drei nachfolgenden Commits werden auf den develop-Branch gesetzt, da er zum aktuellen Branch wurde. Danach haben wir das Schlüsselwort checkout verwendet, um den aktuellen Branch auf main zu setzen, und alle folgenden Commits werden dem aktuellen Branch, d. h. main, zugeordnet. Danach mergen wir den develop-Branch in den aktuellen Branch main, was zu einem Merge-Commit führt. Da der aktuelle Branch an diesem Punkt immer noch main ist, werden die letzten beiden Commits diesem zugeordnet.

Sie können Ihr Merge auch mit ähnlichen Attributen wie bei Commits dekorieren, indem Sie verwenden:

• id --> Um die Standard-ID durch eine benutzerdefinierte ID zu überschreiben
• tag --> Um Ihrem Merge-Commit ein benutzerdefiniertes Tag hinzuzufügen
• type --> Um die Standardform des Merge-Commits zu überschreiben. Hier können Sie andere zuvor erwähnte Commit-Typen verwenden.

Und Sie können wählen, ob Sie keines, einige oder alle dieser Attribute zusammen verwenden möchten. Beispiel: merge develop id: "meine_benutzerdefinierte_ID" tag: "mein_benutzerdefiniertes_Tag" type: REVERSE

Sehen wir uns an, wie das mit dem folgenden Diagramm funktioniert:

Code:

Cherry-Pick eines Commits aus einem anderen Branch

Ähnlich wie 'git' es Ihnen ermöglicht, einen Commit von einem anderen Branch in den aktuellen Branch zu cherry-picken, unterstützt Mermaid diese Funktionalität ebenfalls. Sie können einen Commit auch von einem anderen Branch mit dem Schlüsselwort cherry-pick cherry-picken.

Um das Schlüsselwort cherry-pick zu verwenden, müssen Sie die ID mit dem Attribut id angeben, gefolgt von : und Ihrer gewünschten Commit-ID in einem ""-Anführungszeichen. Beispiel:

cherry-pick id: "Ihre_benutzerdefinierte_ID"

Hier wird ein neuer Commit erstellt, der den Cherry-Pick auf dem aktuellen Branch darstellt, und wird im Diagramm visuell mit einer Kirsche und einem Tag hervorgehoben, das die Commit-ID darstellt, von der er gecherry-picked wurde.

Ein paar wichtige Regeln, die hier zu beachten sind:

1. Sie müssen die id für einen bestehenden Commit angeben, der gecherry-pickt werden soll. Wenn die angegebene Commit-ID nicht existiert, führt dies zu einem Fehler. Verwenden Sie dazu das Format commit id:$value zum Deklarieren von Commits. Siehe die Beispiele von oben.
2. Der angegebene Commit darf nicht auf dem aktuellen Branch existieren. Der gecherry-pickte Commit muss immer ein anderer Branch als der aktuelle Branch sein.
3. Der aktuelle Branch muss mindestens einen Commit haben, bevor Sie cherry-picken können, andernfalls wird ein Fehler ausgegeben.
4. Beim Cherry-Picken eines Merge-Commits ist die Angabe einer übergeordneten Commit-ID obligatorisch. Wenn das Attribut parent weggelassen wird oder eine ungültige übergeordnete Commit-ID angegeben wird, wird ein Fehler ausgegeben.
5. Der angegebene übergeordnete Commit muss ein unmittelbarer übergeordneter Commit des gecherry-pickten Merge-Commits sein.

Sehen wir uns ein Beispiel an:

Code:

Gitgraph-spezifische Konfigurationsoptionen

In Mermaid haben Sie die Möglichkeit, das Gitgraph-Diagramm zu konfigurieren. Sie können die folgenden Optionen konfigurieren:

• showBranches: Boolesch, Standard ist true. Wenn auf false gesetzt, werden die Branches nicht im Diagramm angezeigt.
• showCommitLabel: Boolesch, Standard ist true. Wenn auf false gesetzt, werden die Commit-Beschriftungen nicht im Diagramm angezeigt.
• mainBranchName: Zeichenkette, Standard ist main. Der Name des Standard-/Root-Branches.
• mainBranchOrder: Position des Hauptzweigs in der Liste der Zweige. Standard ist 0, d. h. standardmäßig ist der main-Zweig der erste in der Reihenfolge.
• parallelCommits: Boolesch, Standard ist false. Wenn auf true gesetzt, werden Commits x Entfernung vom übergeordneten Element auf der gleichen Ebene im Diagramm angezeigt.

Schauen wir sie uns einzeln an.

Ausblenden von Branch-Namen und -Linien

Manchmal möchten Sie möglicherweise die Branch-Namen und -Linien aus dem Diagramm ausblenden. Sie können dies mit dem Schlüsselwort showBranches tun. Standardmäßig ist sein Wert true. Sie können ihn mit Direktiven auf false setzen.

Verwendungsbeispiel:

Code:

Layout der Commit-Beschriftungen: Gedreht oder horizontal

Mermaid unterstützt zwei Arten von Layouts für Commit-Beschriftungen. Das Standardlayout ist gedreht, d. h. die Beschriftungen werden unter dem Commit-Kreis platziert und um 45 Grad gedreht, um die Lesbarkeit zu verbessern. Dies ist besonders nützlich für Commits mit langen Beschriftungen.

Die andere Option ist horizontal, d. h. die Beschriftungen werden unter dem Commit-Kreis horizontal zentriert platziert und nicht gedreht. Dies ist besonders nützlich für Commits mit kurzen Beschriftungen.

Sie können das Layout der Commit-Beschriftungen mit dem Schlüsselwort rotateCommitLabel in der Direktive ändern. Es ist standardmäßig auf true gesetzt, d. h. die Commit-Beschriftungen werden gedreht.

Verwendungsbeispiel: Gedrehte Commit-Beschriftungen

Code:

Verwendungsbeispiel: Horizontale Commit-Beschriftungen

Code:

Ausblenden von Commit-Beschriftungen

Manchmal möchten Sie möglicherweise die Commit-Beschriftungen aus dem Diagramm ausblenden. Sie können dies mit dem Schlüsselwort showCommitLabel tun. Standardmäßig ist sein Wert true. Sie können ihn mit Direktiven auf false setzen.

Verwendungsbeispiel:

Code:

Anpassen des Hauptbranch-Namens

Manchmal möchten Sie den Namen des Haupt-/Standard-Branches anpassen. Sie können dies mit dem Schlüsselwort mainBranchName tun. Standardmäßig ist sein Wert main. Sie können ihn mit Direktiven auf eine beliebige Zeichenkette setzen.

Verwendungsbeispiel:

Code:

Sehen Sie sich die imaginäre Eisenbahnkarte an, die mit Mermaid erstellt wurde. Hier haben wir den Namen des Standard-Hauptzweigs in MetroLine1 geändert.

Anpassen der Branch-Reihenfolge

In Mermaid werden die Branches standardmäßig in der Reihenfolge ihrer Definition oder ihres Auftretens im Diagrammcode angezeigt.

Manchmal möchten Sie möglicherweise die Reihenfolge der Branches anpassen. Sie können dies mit dem Schlüsselwort order neben der Branch-Definition tun. Sie können es auf eine positive Zahl setzen.

Mermaid folgt der angegebenen Präzedenzreihenfolge des Schlüsselworts order.

• Der Hauptzweig wird immer zuerst angezeigt, da er den Standardwert 0 für die Reihenfolge hat. (es sei denn, seine Reihenfolge wird mit dem Schlüsselwort mainBranchOrder in der Konfiguration geändert und von 0 geändert)
• Als Nächstes werden alle Zweige ohne order in der Reihenfolge ihres Auftretens im Diagrammcode angezeigt.
• Als Nächstes werden alle Zweige mit order in der Reihenfolge ihres order-Werts angezeigt.

Um die Reihenfolge aller Branches vollständig zu steuern, müssen Sie order für alle Branches definieren.

Verwendungsbeispiel:

Code:

Sehen Sie sich das Diagramm an, alle Branches folgen der definierten Reihenfolge.

Verwendungsbeispiel:

Code:

Sehen Sie sich das Diagramm an, hier werden alle Branches ohne angegebene Reihenfolge in ihrer Definitionsreihenfolge gezeichnet. Dann wird der Zweig test4 gezeichnet, weil die Reihenfolge 1 ist. Dann wird der main-Zweig gezeichnet, weil die Reihenfolge 2 ist. Und schließlich wird test1 gezeichnet, weil die Reihenfolge 3 ist.

HINWEIS: Da wir mainBranchOrder auf 2 überschrieben haben, wird der main-Zweig nicht am Anfang gezeichnet, sondern folgt der Reihenfolge.

Hier haben wir den Namen des Standard-Hauptzweigs in MetroLine1 geändert.

Ausrichtung (v10.3.0+)

Mermaid unterstützt drei Graph-Ausrichtungen: Links nach Rechts (Standard), Oben nach Unten und Unten nach Oben.

Sie können dies mit LR: (für Links nach Rechts), TB: (für Oben nach Unten) oder BT: (für Unten nach Oben) nach gitGraph festlegen.

Links nach Rechts (Standard, LR:)

In Mermaid ist die Standardausrichtung, dass Commits von links nach rechts verlaufen und Branches übereinander gestapelt werden.

Sie können dies jedoch explizit mit LR: nach gitGraph festlegen.

Verwendungsbeispiel:

Code:

Oben nach Unten (TB:)

In der Ausrichtung TB (Oben nach Unten) verlaufen die Commits von oben nach unten im Graphen und die Branches werden nebeneinander angeordnet.

Um den Graphen so auszurichten, müssen Sie TB: nach gitGraph hinzufügen.

Verwendungsbeispiel:

Code:

Unten nach Oben (BT:) (v11.0.0+)

In der Ausrichtung BT (Unten nach Oben) verlaufen die Commits von unten nach oben im Graphen und die Branches werden nebeneinander angeordnet.

Um den Graphen so auszurichten, müssen Sie BT: nach gitGraph hinzufügen.

Verwendungsbeispiel:

Code:

Parallele Commits (v10.8.0+)

Commits in Mermaid zeigen standardmäßig zeitliche Informationen in Gitgraph an. Wenn beispielsweise zwei Commits einen Commit von ihrem übergeordneten Commit entfernt sind, wird der Commit, der früher erstellt wurde, näher an seinem übergeordneten Commit gerendert. Sie können dies deaktivieren, indem Sie das Flag parallelCommits aktivieren.

Zeitliche Commits (Standard, parallelCommits: false)

Code:

Parallele Commits (parallelCommits: true)

Code:

Themes

Mermaid unterstützt eine Reihe von vordefinierten Themes, mit denen Sie das richtige für sich finden können. PS: Sie können tatsächlich eine Variable eines bestehenden Themes überschreiben, um Ihr eigenes benutzerdefiniertes Theme zu erstellen. Erfahren Sie mehr über das Thematisieren Ihres Diagramms hier.

Die folgenden sind die verschiedenen vordefinierten Theme-Optionen:

• base
• forest
• dark
• default
• neutral

HINWEIS: Um das Theme zu ändern, können Sie entweder den initialize-Aufruf oder Direktiven verwenden. Erfahren Sie mehr über Direktiven Lassen Sie uns sie verwenden und sehen, wie unser Beispieldiagramm in verschiedenen Themes aussieht:

Base-Theme

Code:

Forest-Theme

Code:

Default-Theme

Code:

Dark-Theme

Code:

Neutral-Theme

Code:

Anpassen mit Theme-Variablen

Mermaid ermöglicht es Ihnen, Ihr Diagramm mit Theme-Variablen anzupassen, die das Erscheinungsbild verschiedener Elemente des Diagramms steuern.

Zum Verständnis nehmen wir ein Beispieldiagramm mit dem Theme default, die Standardwerte der Theme-Variablen werden automatisch aus dem Theme übernommen. Später werden wir sehen, wie man die Standardwerte der Theme-Variablen überschreibt.

Sehen Sie, wie das Standard-Theme verwendet wird, um die Farben für die Branches festzulegen:

Code:

WICHTIG:

Mermaid unterstützt die Theme-Variablen, um die Standardwerte für bis zu 8 Branches zu überschreiben, d. h. Sie können die Farbe/das Styling von bis zu 8 Branches mit Theme-Variablen festlegen. Nach dieser Schwelle von 8 Branches werden die Theme-Variablen zyklisch wiederverwendet, d. h. der 9. Branch verwendet die Farbe/das Styling des 1. Branches, oder der Branch an der Indexposition '8' verwendet die Farbe/das Styling des Branches an der Indexposition '0'. Mehr dazu im nächsten Abschnitt. Siehe Beispiele zu Anpassen der Farben von Branch-Beschriftungen unten

Anpassen von Branch-Farben

Sie können die Branch-Farben mit den Theme-Variablen git0 bis git7 anpassen. Mermaid ermöglicht es Ihnen, die Farben für bis zu 8 Branches festzulegen, wobei die Variable git0 den Wert des ersten Branches steuert, git1 den Wert des zweiten Branches und so weiter.

HINWEIS: Die Standardwerte für diese Theme-Variablen werden aus dem ausgewählten Theme übernommen. Wenn Sie die Standardwerte überschreiben möchten, können Sie den initialize-Aufruf verwenden, um Ihre benutzerdefinierten Theme-Variablenwerte hinzuzufügen.

Beispiel:

Nun überschreiben wir die Standardwerte für die Variablen git0 bis git3:

Code:

Sehen Sie, wie die Branch-Farben in die in den Theme-Variablen angegebenen Werte geändert werden.

Anpassen der Farben von Branch-Beschriftungen

Sie können die Farben der Branch-Beschriftungen mit den Theme-Variablen gitBranchLabel0 bis gitBranchLabel7 anpassen. Mermaid ermöglicht es Ihnen, die Farben für bis zu 8 Branches festzulegen, wobei die Variable gitBranchLabel0 den Wert der Beschriftung des ersten Branches steuert, gitBranchLabel1 den Wert der Beschriftung des zweiten Branches und so weiter.