Gitgraph 图表 ​

Git图是git提交和git操作（命令）在各个分支上的图形表示。

这类图表对开发人员和运维团队分享他们的Git分支策略特别有帮助。例如，它使得更容易可视化git flow的工作原理。

Mermaid 可以渲染 Git 图表

在Mermaid中，我们支持基本的git操作，例如：

• commit : 表示当前分支上的一个新提交。
• branch : 创建并切换到一个新分支，将其设置为当前分支。
• checkout : 用于检出现有分支并将其设置为当前分支。
• merge : 将现有分支合并到当前分支。

借助这些关键的git命令，您将能够非常轻松快捷地在Mermaid中绘制gitgraph。实体名称通常大写，尽管在这方面没有公认的标准，而且在Mermaid中也不是必需的。

注意: checkout 和 switch 可以互换使用。

语法 ​

Mermaid语法用于gitgraph非常直接和简单。它遵循声明式方法，其中每个提交按照其在代码中出现的顺序在图表的时间线上绘制。基本上，它遵循每个命令的插入顺序。

首先，您需要使用gitgraph关键字声明您的图表类型。这个gitgraph关键字告诉Mermaid您希望绘制一个gitgraph，并相应地解析图表代码。

每个gitgraph都使用main分支进行初始化。因此，除非您创建了不同的分支，否则默认情况下提交将进入主分支。这是由git的工作方式驱动的，在开始时您总是从主分支（以前称为master分支）开始。默认情况下，main分支被设置为您的当前分支。

你使用commit关键字在当前分支上注册一个提交。让我们看看这是如何工作的：

一个简单的gitgraph显示默认分支（main）上的三次提交：

如果你仔细观察前面的例子，你可以看到默认分支 main 以及三个提交。此外，注意到默认情况下每个提交都被赋予了一个唯一的随机ID。如果你想为提交赋予自定义的ID呢？是的，使用Mermaid是可以做到的。

添加自定义提交ID ​

对于给定的提交，您可以在声明时使用id属性指定一个自定义ID，后面跟着:和您在""引号内的自定义值。例如：commit id: "your_custom_id"

让我们通过以下图表来看看这是如何工作的：

在这个例子中，我们为提交分配了自定义ID。

修改提交类型 ​

在Mermaid中，提交可以分为三种类型，这些类型在图表中的呈现略有不同。这些类型是：

• NORMAL : 默认提交类型。在图中用实心圆表示
• REVERSE : 强调提交为反向提交。在图中用带叉的实心圆表示。
• HIGHLIGHT : 用于在图中突出显示特定的提交。在图中用填充的矩形表示。

对于给定的提交，您可以在声明时使用type属性指定其类型，后跟:和上述讨论的所需类型选项。例如：commit type: HIGHLIGHT

注意：如果未指定提交类型，则默认选择NORMAL。

让我们通过以下图表来看看这些不同的提交类型是如何表现的：

在这个例子中，我们为每个提交指定了不同的类型。同时，请注意我们在声明提交时如何同时包含id和type。

添加标签 ​

对于给定的提交，您可以将其装饰为标签，类似于git世界中的标签或发布版本的概念。您可以在声明提交时使用tag属性附加自定义标签，后跟:和您在""引号内的自定义值。例如：commit tag: "your_custom_tag"

让我们通过以下图表来看看这是如何工作的：

在这个例子中，我们为提交赋予了自定义标签。同时，看看我们是如何在单个提交声明中组合所有这些属性的。你可以根据需要混合匹配这些属性。

创建一个新分支 ​

在Mermaid中，为了创建一个新的分支，你需要使用branch关键字。你还需要提供新分支的名称。名称必须是唯一的，不能与现有分支的名称相同。如果分支名称可能与关键字混淆，则必须用""引起来。使用示例：branch develop, branch "cherry-pick"

当Mermaid读取branch关键字时，它会创建一个新分支并将其设置为当前分支。相当于你在Git世界中创建一个新分支并切换到它。

让我们通过一个例子来看看：

在这个例子中，看看我们是如何从默认的main分支开始，并在该分支上推送了两个提交。然后我们创建了develop分支，之后的所有提交都放在了develop分支上，因为它成为了当前分支。

检出现有分支 ​

在Mermaid中，为了切换到现有的分支，你可以使用checkout关键字。你还需要提供一个现有分支的名称。如果没有找到给定名称的分支，将会导致控制台错误。使用示例：checkout develop

当Mermaid读取checkout关键字时，它会找到给定的分支并将其设置为当前分支。相当于在Git世界中检出分支。

让我们看看修改我们之前的例子：

在这个例子中，看看我们是如何从默认的main分支开始，并在该分支上推送了两次提交。然后我们创建了develop分支，之后的所有三次提交都被放在了develop分支上，因为它成为了当前分支。之后，我们使用了checkout关键字将当前分支设置为main，所有后续的提交都记录在当前分支，即main上。

合并两个分支 ​

在Mermaid中，为了合并或加入到一个现有的分支，你需要使用merge关键字。你还需要提供一个现有分支的名称来进行合并。如果没有找到给定名称的分支，将会导致控制台错误。此外，你只能合并两个独立的分支，不能将一个分支与自身合并。在这种情况下，会抛出错误。

使用示例：merge develop

当Mermaid读取merge关键字时，它会找到给定的分支及其头提交（该分支上的最后一次提交），并将其与当前分支上的头提交合并。每次合并都会产生一个合并提交，在图中用填充的双圆圈表示。

让我们修改之前的例子来合并我们的两个分支：

在这个例子中，看看我们是如何从默认的main分支开始，并在该分支上推送了两次提交。然后我们创建了develop分支，之后的所有三次提交都被放在develop分支上，因为它成为了当前分支。之后，我们使用了checkout关键字将当前分支设置为main，所有后续的提交都记录在当前分支，即main上。之后，我们将develop分支合并到当前分支main上，产生了一个合并提交。由于此时当前分支仍然是main，最后两次提交都记录在该分支上。

你也可以像提交时那样，使用类似的属性来装饰你的合并：

• id--> 使用自定义ID覆盖默认ID
• tag--> 为您的合并提交添加自定义标签
• type--> 用于覆盖合并提交的默认形状。在这里，您可以使用前面提到的其他提交类型。

你可以选择不使用、使用部分或全部这些属性。例如：merge develop id: "my_custom_id" tag: "my_custom_tag" type: REVERSE

让我们通过以下图表来看看这是如何工作的：

从另一个分支挑选提交 ​

类似于 'git' 允许你从另一个分支挑选一个提交到当前分支，Mermaid 也支持这一功能。你也可以使用 cherry-pick 关键字从另一个分支挑选一个提交。

要使用cherry-pick关键字，您必须使用id属性指定id，然后在""引号内加上:和您想要的提交id。例如：

cherry-pick id: "your_custom_id"

在这里，代表摘取的新提交在当前分支上创建，并在图中用樱桃和描述其摘取来源的提交ID的标签进行视觉突出显示。

这里需要注意的几个重要规则是：

1. 您需要提供一个现有提交的id来进行cherry-pick。如果提供的提交id不存在，将会导致错误。为此，请使用commit id:$value格式来声明提交。请参阅上面的示例。
2. 给定的提交必须不存在于当前分支上。cherry-picked 的提交必须始终与当前分支不同。
3. 当前分支必须至少有一个提交，才能进行 cherry-pick，否则会抛出错误。
4. 当挑选合并提交时，必须提供父提交ID。如果省略了父属性或提供了无效的父提交ID，将会抛出错误。
5. 指定的父提交必须是正在挑选的合并提交的直接父提交。

让我们看一个例子：

Gitgraph 特定配置选项 ​

在Mermaid中，您可以选择配置gitgraph图表。您可以配置以下选项：

• showBranches : Boolean, 默认为 true。如果设置为 false，则图中不会显示分支。
• showCommitLabel : Boolean, 默认为 true。如果设置为 false，图表中将不显示提交标签。
• mainBranchName : String, 默认为 main。默认/根分支的名称。
• mainBranchOrder : 主分支在分支列表中的位置。默认是 0，意味着默认情况下 main 分支是顺序中的第一个。
• parallelCommits: 布尔值，默认为 false。如果设置为 true，距离父提交 x 距离的提交将在图中显示在同一层级。

让我们逐一来看。

隐藏分支名称和行 ​

有时你可能想隐藏图表中的分支名称和线条。你可以通过使用showBranches关键字来实现这一点。默认情况下，它的值是true。你可以使用指令将其设置为false。

使用示例：

提交标签布局：旋转或水平 ​

Mermaid 支持两种类型的提交标签布局。默认布局是旋转，这意味着标签放置在提交圆圈下方，旋转45度以提高可读性。这对于具有长标签的提交特别有用。

另一个选项是水平，这意味着标签放置在提交圆圈下方，水平居中，并且不旋转。这对于带有短标签的提交特别有用。

你可以通过在指令中使用rotateCommitLabel关键字来更改提交标签的布局。它默认为true，这意味着提交标签是旋转的。

使用示例：旋转的提交标签

使用示例：水平提交标签

隐藏提交标签 ​

有时你可能想从图表中隐藏提交标签。你可以通过使用showCommitLabel关键字来实现这一点。默认情况下，它的值是true。你可以使用指令将其设置为false。

使用示例：

自定义主分支名称 ​

有时您可能希望自定义主/默认分支的名称。您可以通过使用mainBranchName关键字来实现。默认情况下，其值为main。您可以使用指令将其设置为任何字符串。

使用示例：

看看使用Mermaid创建的虚构铁路地图。在这里，我们将默认的主分支名称更改为MetroLine1。

自定义分支排序 ​

在Mermaid中，默认情况下，分支会按照它们在图表代码中的定义或出现顺序显示。

有时你可能想要自定义分支的顺序。你可以通过在分支定义旁边使用order关键字来实现这一点。你可以将其设置为一个正数。

Mermaid 遵循给定的 order 关键字的优先级顺序。

• 主分支总是首先显示，因为它的默认顺序值为0。（除非使用配置中的mainBranchOrder关键字修改并更改了其顺序，使其不再是0）
• 接下来，所有没有order的分支将按照它们在图表代码中出现的顺序显示。
• 接下来，所有带有order的分支将按照它们的order值顺序显示。

要完全控制所有分支的顺序，您必须为所有分支定义order。

使用示例：

请看图表，所有的分支都遵循定义的顺序。

使用示例：

请看图表，这里，所有没有指定顺序的分支都按照它们的定义顺序绘制。然后，test4分支被绘制，因为它的顺序是1。接着，main分支被绘制，因为它的顺序是2。最后，test1被绘制，因为它的顺序是3。

注意：由于我们已经将mainBranchOrder覆盖为2，main分支在开始时不会被绘制，而是遵循排序。

在这里，我们将默认的主分支名称更改为MetroLine1。

方向 (v10.3.0+) ​

Mermaid 支持三种图形方向：从左到右（默认）、从上到下和从下到上。

你可以通过LR:（用于从左到右）、TB:（用于从上到下）或BT:（用于从下到上）在gitGraph之后设置这个。

从左到右（默认，LR:） ​

在Mermaid中，默认的方向是提交从左到右运行，分支则堆叠在一起。

然而，你可以在gitGraph之后使用LR:明确设置这一点。

使用示例：

从上到下 (TB:) ​

在TB（从上到下）方向中，提交从图的顶部到底部运行，分支并排排列。

要以这种方式定向图形，您需要在gitGraph后添加TB:。

使用示例：

从下到上 (BT:) (v11.0.0+) ​

在BT（从下到上）方向中，提交从图的底部运行到顶部，分支并排排列。

要以这种方式定向图形，您需要在 gitGraph 后添加 BT:。

使用示例：

并行提交 (v10.8.0+) ​

Mermaid中的提交默认在gitgraph中显示时间信息。例如，如果两个提交与其父提交相隔一个提交，那么较早进行的提交会渲染得更靠近其父提交。你可以通过启用parallelCommits标志来关闭此功能。

时间提交（默认，parallelCommits: false） ​

并行提交 (parallelCommits: true) ​

主题 ​

Mermaid 支持一系列预定义的主题，您可以使用这些主题来找到适合您的主题。PS：您实际上可以覆盖现有主题的变量来创建自己的自定义主题。了解更多关于图表主题的信息，请点击这里。

以下是不同的预定义主题选项：

• base
• forest
• dark
• default
• neutral

注意: 要更改主题，您可以使用initialize调用或指令。了解更多关于指令的信息。让我们使用它们，看看我们的示例图表在不同主题下的样子：

基础主题 ​

森林主题 ​

默认主题 ​

暗黑主题 ​

中性主题 ​

使用主题变量进行自定义 ​

Mermaid 允许您使用主题变量自定义图表，这些变量控制图表中各个元素的外观和感觉。

为了理解，让我们以一个主题为default的示例图为例，主题变量的默认值会自动从主题中选取。稍后我们将看到如何覆盖主题变量的默认值。

查看如何使用默认主题为分支设置颜色：

重要提示：​

Mermaid 支持主题变量来覆盖默认值，最多支持8个分支，即您可以使用主题变量设置最多8个分支的颜色/样式。超过8个分支后，主题变量将以循环方式重复使用，即第9个分支将使用第1个分支的颜色/样式，或者索引位置为'8'的分支将使用索引位置为'0'的分支的颜色/样式。更多内容将在下一节中介绍。请参阅下面的自定义分支标签颜色示例

自定义分支颜色 ​

您可以使用git0到git7的主题变量来自定义分支颜色。Mermaid允许您为最多8个分支设置颜色，其中git0变量将驱动第一个分支的值，git1将驱动第二个分支的值，依此类推。

注意：这些主题变量的默认值是从所选主题中选取的。如果你想覆盖默认值，可以使用initialize调用来添加你的自定义主题变量值。

示例：

现在让我们覆盖git0到git3变量的默认值：

查看分支颜色如何更改为主题变量中指定的值。

自定义分支标签颜色 ​

您可以使用gitBranchLabel0到gitBranchLabel7主题变量来自定义分支标签颜色。Mermaid允许您设置最多8个分支的颜色，其中gitBranchLabel0变量将驱动第一个分支标签的值，gitBranchLabel1将驱动第二个分支标签的值，依此类推。

让我们看看如何使用默认主题来设置分支标签的颜色：

现在让我们覆盖gitBranchLabel0到gitBranchLabel2变量的默认值：

在这里，你可以看到branch8和branch9的颜色和样式分别从索引位置0（main）和1（branch1）的分支中选取，即分支主题变量是循环重复的。

自定义提交颜色 ​

您可以使用commitLabelColor和commitLabelBackground主题变量分别自定义提交标签的颜色和背景颜色。

示例：现在让我们覆盖commitLabelColor到commitLabelBackground变量的默认值：

查看提交标签颜色和背景颜色如何更改为主题变量中指定的值。

自定义提交标签字体大小 ​

您可以使用commitLabelFontSize主题变量来自定义提交，以更改提交标签的字体大小。

示例：现在让我们覆盖commitLabelFontSize变量的默认值：

查看提交标签字体大小的变化。

自定义标签字体大小 ​

您可以使用tagLabelFontSize主题变量来自定义提交，以更改标签字体的字体大小。

示例：现在让我们覆盖tagLabelFontSize变量的默认值：

查看标签字体大小如何变化。

自定义标签颜色 ​

您可以使用tagLabelColor、tagLabelBackground和tagLabelBorder主题变量分别自定义标签的颜色、标签背景颜色和标签边框。示例：现在让我们覆盖tagLabelColor、tagLabelBackground和tagLabelBorder变量的默认值：

查看标签颜色如何更改为主题变量中指定的值。

自定义高亮提交颜色 ​

您可以使用gitInv0到gitInv7主题变量自定义与分支相关的高亮提交颜色。Mermaid允许您为最多8个分支的特定高亮提交设置颜色，其中gitInv0变量将驱动第一个分支的高亮提交的值，gitInv1将驱动第二个分支的高亮提交标签的值，依此类推。

示例：

现在让我们覆盖git0到git3变量的默认值：

查看第一个分支上高亮显示的提交颜色如何更改为主题变量 gitInv0 中指定的值。