Mermaid

外观

探索来自 Mermaid 创建者的 Mermaid 白板

Gitgraph 图表 ​

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

这种图表对开发人员和 DevOps 团队分享他们的 Git 分支策略特别有用。例如，它使可视化 Git Flow 的工作方式变得更容易。

Mermaid 可以渲染 Git 图表

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

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

借助这些关键的 Git 命令，您将能够非常轻松快捷地在 Mermaid 中绘制 Git 图表。实体名称通常使用大写字母，尽管这方面没有公认的标准，在 Mermaid 中也不是必须的。

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

语法 ​

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

您要做的第一件事是使用 **gitgraph** 关键字声明您的图表类型。此 gitgraph 关键字告诉 Mermaid 您希望绘制一个 Git 图表，并相应地解析图表代码。

每个 Git 图表都以 **main** 分支初始化。因此，除非您创建不同的分支，否则默认情况下，提交将进入 main 分支。这是由 Git 的工作方式决定的，在开始时，您总是从 main 分支（以前称为 **master** 分支）开始。默认情况下，main 分支被设置为您的 **当前分支**。

您使用 **commit** 关键字在当前分支上注册提交。让我们看看它是如何工作的

一个简单的 Git 图表，显示了默认（**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"

这里，会在当前分支上创建一个新的提交，表示挑选操作，并且会在图表中用一个樱桃和一个标签突出显示，标签表示从哪个提交中挑选的。

这里要注意一些重要的规则

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

让我们看一个示例

Gitgraph 特定的配置选项 ​

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

  • showBranches : 布尔值，默认为 true。 如果设置为 false，则图表中不会显示分支。
  • showCommitLabel : 布尔值，默认为 true。 如果设置为 false，则图表中不会显示提交标签。
  • mainBranchName : 字符串，默认为 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中指定的值的。