Mermaid.js GitGraph 图表语法指南

GitGraph 图表是一种专门的可视化组件，由开发者、DevOps 团队和技术写作者使用，以清晰地传达 Git 分支策略、发布管理以及开发工作流程。该组件原生集成于 Mermaid.js 中，gitGraph引擎采用声明式、顺序的时间轴模型。这将现实世界中的终端命令直接映射到精确的可视化时间轴图上，而无需手动图像编辑。

理解 GitGraph 时间轴矩阵

与自由形式的系统流程图不同，GitGraph 图表遵循严格的、顺序的、按事件发生顺序的逻辑，用于建模真实的版本控制系统工作区：

  • 自动根分支： 每个图表工作区在初始化时会自动创建一个主根时间轴轨道。默认情况下，该轨道命名为main，并且所有后续操作都以此为基准，除非创建了清晰的替代分支路径。
  • 顺序优先级： 元素根据代码源文件中命令的插入顺序，沿从左到右的时间轴顺序渲染。

基本语法结构

每个时间轴都以驼峰命名法的gitGraph 声明关键字开始。其后是按顺序列出的原子执行命令列，例如提交、检出和合并。

Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
gitGraph
  commit
  commit
  branch feature-login
  checkout feature-login
  commit
  checkout main
  merge feature-login
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

完整的 Git 操作命令参考

布局引擎会解析特定的小写操作命令，以推进线条粗细、拆分轨道，或在工作区画布上合并端点。

Git 命令标记 参数参数修饰符 技术操作与布局行为
commit id: "hash", type: TYPE, 标签："v1.0" 将一个新的里程碑节点直接附加到当前目标分支路径线上。
分支 名称, 顺序：整数 创建一个新的分支车道分裂。您可以使用可选的显式顺序值来强制其垂直堆叠位置。
检出 / 切换 分支名称 将活动录制索引指针移至指定的目标分支线。后续操作将以此车道为基准。
合并 目标分支名称, ID："哈希", 标签："v2" 将指定的分支车道合并回当前分支，创建一个明显的视觉融合交叉点。
挑选提交 ID："提交哈希", 父提交："父哈希" 将外部分支中的特定提交复制到当前分支车道上，而不融合车道。

高级功能：提交类型与标签自定义

为了区分常规补丁、系统回滚或重大发布，您可以分配一个显式的类型和标签使用类似 JSON 的键值对属性的参数块内的字符串修饰符。

支持的提交形状分类：

  • 类型：常规：默认配置。沿时间轴车道渲染为一个实心填充的圆形单元节点。
  • 类型：反转：突出显示架构或程序上的回滚。渲染为一个带交叉线的实心圆形单元节点（$X$）。
  • 类型：高亮：引起对关键结构性更改或安全修复的关注。渲染为一个拉长的实心矩形框。
Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
gitGraph
  commit id: "初始"
  commit type: HIGHLIGHT id: "安全热修复" tag: "v1.0.1"
  commit type: REVERSE id: "回滚功能-X"
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

高级功能：挑选（cherry-pick）逻辑与严格约束

该cherry-pick命令将从另一条分支车道中复制一个特定的孤立节点到您当前激活的分支上。为避免引发编译器布局错误，执行 cherry-pick 操作时必须遵循以下严格的工作区验证要求：

  • 排除约束： 您要挑选的目标提交 ID *不得* 已存在于您当前跟踪的分支车道上。
  • 前置历史要求： 当前激活的分支线在调用挑选操作之前，必须至少包含一个有效的提交节点。
  • 合并父节点要求： 如果您正在挑选一个合并节点，必须显式地使用以下修饰符块传递直接上游父节点的标识字符串：parent: "hash" 修饰符块。
Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
gitGraph
  commit id: "设置"
  branch staging
  checkout staging
  commit id: "功能补丁"
  checkout main
  commit id: "基线"
  cherry-pick id: "功能补丁"
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

高级功能：前端元数据参数配置

您可以通过在图表脚本的绝对顶部声明一个配置指令块，来微调全局视觉行为（例如切换分支标签、修改行索引或堆叠时间轴）%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% 配置指令块

可配置参数矩阵

配置键字符串 类型定义 默认值 视觉界面更改结果
showBranches 布尔值 true 切换画布网格左侧各个分支跟踪标签的可见性。
showCommitLabel 布尔值 true 切换在各个时间轴节点上方直接渲染文本标题和字母数字哈希值。
mainBranchName 字符串 "main" 更改默认起始根分支名称跟踪文本（例如，切换为"master" 或 "trunk").
mainBranchOrder 整数 0 设置主根时间轴跟踪通道的从上到下的垂直堆叠顺序位置索引。
parallelCommits 布尔值 false 如果修改为true，共享相同父级步骤距离的独立提交将在同一垂直层级上对称对齐。

现实世界蓝图：企业级 Git-Flow 发布管理流水线

这个全面的企业蓝图展示了标准的生产发布流水线。它覆盖了配置参数，将根车道重命名为trunk，建立固定的分支顺序层级，使用多个分支车道（develop和feature-auth），执行合并操作，应用自定义标签，并部署高优先级的高亮提交形状。

Mermaid


在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
%%{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"
Edit Mermaid in VPasCode



在 VPasCode 中编辑 Mermaid

常见语法陷阱与系统限制

在编译精确的版本控制图时，请牢记这些故障排除参数，以防止布局计算错误：

  • 大小写敏感性错误： 主要的初始化声明必须明确以驼峰命名法书写为gitGraph。全部小写书写为gitgraph将导致编译器解析崩溃。
  • 未加引号的字母数字标识符： 在传递自定义提交参数时（例如，id: core_init），包含连字符、空格或句点的值必须用双引号括起来。忘记使用引号块将导致验证编译错误。
  • 无效的检出目标： 调用一个检出分支_name 对一个未事先使用以下方式初始化的字符串标识符执行操作分支 branch_name 命令将立即中断图构建。
  • 分支排序冲突： 当使用顺序 分支上的配置标签时，确保多个轨道不会映射到相同的整数，除非您希望画布路径轨迹重叠。请保持分支轨道编号的唯一性。
  • 空格分隔失败： 在括号参数矩阵内分隔属性时，确保清晰的参数空格存在（例如使用id: "1", type: HIGHLIGHT）。省略缺失的逗号或空格可能导致解析异常。
滚动至顶部