Gitgraph 图表

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

这类图表对于开发者和 DevOps 团队共享他们的 Git 分支策略尤其有用。例如，它使可视化 Git flow 的工作方式更容易。

Mermaid 可以渲染 Git 图表

Code:

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

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

借助这些关键的 Git 命令，你将能够非常轻松快速地在 Mermaid 中绘制 Gitgraph。实体名称通常大写，尽管对此没有公认的标准，并且在 Mermaid 中不是必需的。

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

语法

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

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

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

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

一个简单的 Gitgraph，在默认（main）分支上显示三个提交：

Code:

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

添加自定义提交 ID

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

让我们看看这如何通过下图来工作：

Code:

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

修改提交类型

在 Mermaid 中，提交可以有三种类型，它们在图表中的渲染略有不同。这些类型是：

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

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

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

让我们看看这些不同的提交类型通过下图是如何显示的：

Code:

在这个例子中，我们为每个提交指定了不同的类型。另外，请注意我们是如何在声明提交时同时包含 id 和 type 的。你可以根据需要混合匹配这些属性。

添加标签

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

让我们看看这如何通过下图来工作：

Code:

在这个例子中，我们为提交提供了自定义标签。另外，请注意我们是如何在一个提交声明中组合所有这些属性的。你可以随意混合匹配这些属性。

创建新分支

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

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

让我们在一个例子中看看：

Code:

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

检出现有分支

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

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

让我们修改之前的例子：

Code:

在这个例子中，我们可以看到我们从默认的 main 分支开始，并在其上推送了两个提交。 然后我们创建了 develop 分支，之后的所有三个提交都放在 develop 分支上，因为它成为当前分支。 之后我们使用 checkout 关键字将当前分支设置为 main，所有后续提交都针对当前分支 main 注册。

合并两个分支

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

使用示例：merge develop

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

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

Code:

在这个例子中，我们可以看到我们从默认的 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

让我们看看这如何通过下图来工作：

Code:

从另一个分支挑选提交

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

要使用 cherry-pick 关键字，你必须使用 id 属性指定 id，后跟 : 和 "" 引号内的所需提交 id。例如：

cherry-pick id: "your_custom_id"

在这里，一个表示 cherry-pick 的新提交在当前分支上创建，并在图表中用 樱桃 和一个标签突出显示，该标签描述了从中挑选它的提交 id。

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

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

让我们看一个例子：

Code:

Gitgraph 特定的配置选项

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

• showBranches：布尔值，默认为 true。如果设置为 false，则图表中不显示分支。
• showCommitLabel：布尔值，默认为 true。如果设置为 false，则图表中不显示提交标签。
• mainBranchName：字符串，默认为 main。默认/根分支的名称。
• mainBranchOrder：main 分支在分支列表中的位置。默认为 0，这意味着默认情况下 main 分支是第一个。
• parallelCommits: 布尔值，默认为 false。如果设置为 true，则距父节点 x 距离的提交在图表中显示在同一级别。

让我们逐一了解它们。

隐藏分支名称和线条

有时你可能想要隐藏图表中的分支名称和线条。你可以使用 showBranches 关键字来实现。默认值为 true。你可以使用指令将其设置为 false。

使用示例：

Code:

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

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

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

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

使用示例：旋转提交标签

Code:

使用示例：水平提交标签

Code:

隐藏提交标签

有时你可能想要隐藏图表中的提交标签。你可以使用 showCommitLabel 关键字来实现。默认值为 true。你可以使用指令将其设置为 false。

使用示例：

Code:

自定义主分支名称

有时你可能想要自定义 main/默认分支的名称。你可以使用 mainBranchName 关键字来实现。默认值为 main。你可以使用指令将其设置为任何字符串。

使用示例：

Code:

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

自定义分支顺序

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

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

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

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

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

使用示例：

Code:

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

使用示例：

Code:

看看图表，在这里，所有没有指定顺序的分支都按其定义顺序绘制。 然后，绘制 test4 分支，因为顺序为 1。 然后，绘制 main 分支，因为顺序为 2。 最后，绘制 test1，因为顺序为 3。

注意：因为我们将 mainBranchOrder 覆盖为 2，所以 main 分支不是在开始时绘制的，而是遵循排序。

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

方向 (v10.3.0+)

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

你可以在 gitGraph 后使用 LR:（对于 从左到右）、TB:（对于 从上到下）或 BT:（对于 从下到上）来设置。

从左到右 (默认, LR:)

在 Mermaid 中，默认方向是提交从左到右运行，分支彼此堆叠。

但是，你可以在 gitGraph 后显式地使用 LR: 来设置。

使用示例：

Code:

从上到下 (TB:)

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

要将图表定向为这种方式，你需要在 gitGraph 后添加 TB:。

使用示例：

Code:

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

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

要将图表定向为这种方式，你需要在 gitGraph 后添加 BT:。

使用示例：

Code:

并行提交 (v10.8.0+)

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

时间提交 (默认, parallelCommits: false)

Code:

并行提交 (parallelCommits: true)

Code:

主题

Mermaid 支持许多预定义的主题，你可以使用它们来找到适合你的主题。附注：你实际上可以覆盖现有主题的变量来创建你自己的自定义主题。在此处了解更多关于主题化图表的信息 here。

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

• base
• forest
• dark
• default
• neutral

注意: 要更改主题，你可以使用 initialize 调用或 指令。了解更多关于 指令 的信息。 让我们将它们投入使用，看看我们的示例图表在不同主题中的外观：

Base 主题

Code:

Forest 主题

Code:

Default 主题

Code:

Dark 主题

Code:

Neutral 主题

Code:

使用主题变量进行自定义

Mermaid 允许你使用主题变量自定义图表，这些变量控制图表的各种元素的外观。

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

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

Code:

重要：

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

自定义分支颜色

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

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

示例：

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

Code:

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

自定义分支标签颜色

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

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

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

Code:

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

自定义提交颜色

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

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

Code:

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

自定义提交标签字体大小

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

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

Code:

请查看提交标签字体大小是如何更改的。

自定义标签标签字体大小

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

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

Code:

请查看标签标签字体大小是如何更改的。

自定义标签颜色

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

Code:

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

自定义突出显示提交颜色

你可以使用 gitInv0 到 gitInv7 主题变量自定义与之相关的分支中的突出显示提交颜色。