Mermaid GitGraph 图完全指南从 commit/branch/merge 语法到主题变量的源码级解析【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 仓库的官方语法文档 gitgraph.md 展开系统讲解 Git Graph 图的声明式语法——commit、branch、checkout、merge、cherry-pick五大操作全部gitGraph配置项showBranches、mainBranchName、parallelCommits等、LR/TB/BT方向控制与git0~git7系列主题变量。结合 packages/mermaid/src/diagrams/git/gitGraphAst.ts 等源码你将既会写图也能理解每个语法糖背后的状态机与校验规则。什么是 Git Graph 图Git Graph 是对 Git 提交与 Git 操作命令在各分支上的图形化表示。这类图对开发者和 DevOps 团队分享 Git 分支策略特别有用例如直观展示 Git Flow 的工作方式。一个最基础的示例标题通过 front matter 的title指令设置Mermaid 支持四个基本 Git 操作commit在当前分支上表示一次新提交branch创建并切换到新分支将其设为当前分支等价于 git 中创建分支并 checkoutcheckout切换到已存在的分支并将其设为当前分支checkout与switch可以互换使用merge把一个已存在的分支合并进当前分支。借助这几个关键命令你可以非常快速地在 Mermaid 中画出 Git 图。从源码结构看GitGraph 图由 gitGraphDiagram.ts 注册为标准的DiagramDefinition解析器gitGraphParser.ts由 Jison 生成、数据模型gitGraphAst.ts导出的db对象、渲染器gitGraphRenderer.ts与样式styles.js各司其职。所有状态都收敛在 gitGraphAst.ts 的一个ImperativeState中包含commits提交映射、branches分支到 HEAD 提交的映射、currBranch当前分支、direction方向默认LR与自增序号seq等字段这正是每条命令按书写顺序依次作用这一声明式语义的实现基础。声明式语法与初始状态GitGraph 语法非常直接它是一种声明式写法每个提交按其在代码中出现的顺序依次画在时间线上即按插入顺序逐条执行命令。第一步是用gitGraph关键字声明图类型它告诉 Mermaid 你要画一张 Git 图并按此解析后续代码。每个 Git 图都从main分支初始化因此除非创建其他分支提交默认都会落在main上——这与 Git 本身的工作方式一致最初总是从 main 分支即旧称的 master 分支开始并且main分支默认就是当前分支。三个提交都落在默认main分支上的最小图仔细观察上面的图默认分支main上有三个提交并且每个提交都被赋予了唯一且随机的 ID。源码印证了这一点当未提供id时commit 函数 生成的 ID 是seq - 7位随机串随机串由 getID() 产生。自定义 commit ID声明提交时可以用id属性指定自定义 ID格式为id:加双引号包裹的值例如commit id: your_custom_id在实现中commit会把id与msg统一经过common.sanitizeText清洗若 ID 已存在源码只记录 warnCommit ID ... already exists不会中断渲染。修改 commit 类型Mermaid 中提交有三种类型在图中的图形略有差异NORMAL默认提交类型实心圆表示REVERSE强调某次提交为回退提交带叉的实心圆表示HIGHLIGHT高亮某次提交实心矩形表示。用type属性声明例如commit type: HIGHLIGHT。未指定时默认取NORMAL。三种类型与自定义 ID 组合的示例添加 Tag你可以像 Git 中的 tag/release 概念一样用tag属性给提交打标签commit tag: your_custom_tag。id、type、tag这些属性可以在同一条提交声明中任意混搭创建新分支使用branch关键字并给出新分支名。分支名必须唯一不能与已有分支重名如果分支名容易与关键字混淆需要用引号包裹。用法示例branch develop、branch cherry-pick。Mermaid 读到branch时会创建该分支并将其设为当前分支等价于 Git 中创建并切换。这一点在源码 branch 函数 中可以直接看到它先校验重名抛出 Trying to create an existing branch... 错误然后把新分支的 HEAD 指向当前head最后自动调用checkout(name)起始于默认main分支并推送两个提交创建develop分支后其成为当前分支之后的所有提交都落在develop上。切换checkout已存在分支使用checkout关键字并给出一个已存在的分支名若找不到该分支会报控制台错误。用法示例checkout develop。源码 checkout 函数 的校验逻辑分支不存在时抛出 Trying to checkout branch which is not yet created 错误存在时更新currBranch并把head定位到该分支记录的 HEAD 提交若该分支尚无提交则head置为 null。在上一例基础上用checkout main把当前分支切回main其后的两个提交注册到main上。合并两个分支使用merge关键字并给出要合并进来的分支名。找不到该分支会报错只能合并两个不同的分支不能把一个分支合并到自身会抛错。用法示例merge develop。Mermaid 读到merge时找到目标分支及其 HEAD 提交把它与当前分支的 HEAD 提交连接每次合并都会产生一个合并提交merge commit图中以实心双圆表示。merge 函数 的校验链相当严格与文档描述的规则一一对应当前分支与目标分支是同一分支 → Cannot merge a branch to itself当前分支没有任何提交 → Current branch (...) has no commits目标分支不存在 → Branch to be merged (...) does not exist目标分支没有任何提交 → Branch to be merged (...) has no commits两个分支 HEAD 相同 → Both branches have same head自定义id与已有提交 ID 冲突 → 报错并要求换一个唯一 ID。develop被合并进main产生一个合并提交当前分支仍是main最后两个提交注册到main。合并提交也可以像提交一样装饰属性可以一个都不用、部分用或全用id用自定义 ID 覆盖默认 IDtag给合并提交添加自定义 tagtype覆盖合并提交的默认形状使用前面提到的 commit 类型。例如merge develop id: my_custom_id tag: my_custom_tag type: REVERSE。下面是一个多分支交叉的完整例子最后一行演示了带属性的合并从其他分支 cherry-pick 提交与真实 Git 类似Mermaid 支持用cherry-pick关键字把另一个分支上的提交摘到当前分支。必须用id属性给出要摘取的提交 IDcherry-pick id: your_custom_id。执行后当前分支上会创建一个代表 cherry-pick 的新提交以樱桃图形高亮并带有一个标注来源提交 ID 的 tag。五条重要规则与 cherryPick 函数 的校验逻辑一致必须提供已存在的提交id不存在则报错——因此要先用commit id:...的方式声明提交被摘取的提交不能已存在于当前分支cherry-pick 的提交必须来自其他分支当前分支在执行 cherry-pick 之前必须至少有一个提交否则抛错cherry-pick 合并提交时parent属性必填省略或提供无效父提交 ID 都会抛错指定的父提交必须是该合并提交的直接父提交源码用sourceCommit.parents.includes(parentCommitId)校验。示例源码层面还有一个细节cherry-pick 生成的提交类型是commitType.CHERRY_PICK若未显式提供 tag会自动附加cherry-pick:来源ID合并提交还会带|parent:父ID作为 tag这就是图中樱桃节点上出现来源标注的由来。GitGraph 专属配置项Mermaid 提供一组gitGraph配置项可以在 front matter 的config指令中设置。完整清单配置项类型默认值说明showBranchesBooleantrue设为false时图中不显示分支名与分支线showCommitLabelBooleantrue设为false时图中不显示提交标签mainBranchNameStringmain默认/根分支的名称mainBranchOrderNumber0main 分支在分支列表中的位置默认 0 即排在最前parallelCommitsBooleanfalse设为true时距父提交 x 个距离的提交画在同一层不体现时间先后rotateCommitLabelBooleantrue提交标签是否旋转 45 度详见下文布局小节这组配置的类型定义见 config.type.ts 中的GitGraphDiagramConfig默认值由 schemas/config.schema.yaml 加载defaultConfig.ts 中从 JSON Schema 读取而运行时读取走 getConfig()用cleanAndMerge把默认值与用户通过mermaid.initialize()或 front matter 传入的gitGraph配置合并。单元测试 gitGraph.spec.ts 也逐条断言了showBranches、showCommitLabel、rotateCommitLabel、parallelCommits属性存在。隐藏分支名和分支线用showBranches: false隐藏分支名和线渲染器 gitGraphRenderer.ts 在showBranches为真时才绘制分支元素提交标签布局旋转或水平Mermaid 支持两种提交标签布局默认是旋转rotated标签放在提交圆下方并旋转 45 度便于阅读对长标签特别友好另一种是水平horizontal标签水平居中放在提交圆下方不旋转适合短标签。用rotateCommitLabel关键字切换默认true旋转。旋转布局水平布局仅把rotateCommitLabel改为false图体不变隐藏提交标签用showCommitLabel: false隐藏提交标签。与上一节组合使用的示例showBranches与showCommitLabel同时关闭自定义 main 分支名用mainBranchName把默认分支改成任意字符串。下面把默认分支改名为MetroLine1画了一张想象中的地铁线路图注意这里checkout MetroLine1与merge MetroLine3、merge MetroLine2 tag:MY JUNCTION中的名字都必须与新分支名一致——从源码 状态初始化 可见mainBranchName会同时决定初始currBranch与branchConfig的初始键。自定义分支顺序默认情况下分支按它们在图中定义/出现的顺序展示。用order关键字正整数可以自定义顺序写在分支定义后面Mermaid 遵循order的优先顺序规则main 分支默认 order 为0永远最先展示除非用mainBranchOrder配置改动它未指定order的分支按出现顺序展示指定了order的分支按order值排序展示。要完全控制所有分支的顺序必须为所有分支都定义order。再看一个配合mainBranchOrder: 2的例子排序结果test2、test3未指定 order按定义顺序→test4order 1→mainorder 2因覆盖了mainBranchOrder而不再置顶→test1order 3。排序逻辑的实现在 getBranchesAsObjArray()未显式指定 order 的分支被赋予0.索引形式的浮点数即按出现顺序排在前再与显式 order 一起统一按数值升序排列——这解释了为什么无 order 分支整体排在有 order 分支之前。方向控制LR / TB / BTv10.3.0Mermaid 支持三种图方向Left-to-Right默认、Top-to-Bottom、Bottom-to-Top。写法是在gitGraph关键字后加LR:、TB:或BT:。左到右默认LR:默认方向是提交从左到右展开、分支上下堆叠。也可以显式写出LR:上到下TB:TB方向下提交从上到下展开分支左右并排。在gitGraph后加TB:下到上BT:v11.0.0BT方向下提交从下到上展开分支左右并排。在gitGraph后加BT:方向由解析器回调setDirection写入状态初始值LR渲染器根据direction决定坐标映射。并行提交v10.8.0默认情况下 GitGraph 通过提交的水平位置传达时间信息例如两个提交距父提交同样远时先写的会画得更靠近父提交。开启parallelCommits: true可关闭这种时间差——距父提交 x 个距离的提交会画在同一层。时间顺序模式默认parallelCommits: false并行模式parallelCommits: true主题与主题变量Mermaid 支持预定义主题也可以用主题变量覆盖任何主题的既有取值。GitGraph 可用的预定义主题base、forest、dark、default、neutral。切换主题可以用initialize调用或 front matter 指令directives 说明主题机制详见 theming 文档。以同一张多分支图分别套用不同主题为例theme: base/forest/default/dark/neutral只需替换 front matter 中的theme值用主题变量定制外观主题变量控制图各元素的颜色与排版。以default主题为基准示例覆盖方式统一是 front matter 的themeVariables。重要说明主题变量最多覆盖8 个分支的颜色/样式超出后循环复用——第 9 个分支使用第 1 个分支索引 0的取值。分支颜色git0~git7。git0驱动第 1 个分支git1驱动第 2 个依此类推分支标签颜色gitBranchLabel0~gitBranchLabel7规则相同由于只有 8 组标签变量branch8、branch9会分别复用索引 0main与索引 1branch1的配色——即分支主题变量循环复用。提交标签颜色与字号commitLabelColor、commitLabelBackground、commitLabelFontSizeTag 标签tagLabelColor、tagLabelBackground、tagLabelBorder控制 tag 的文字颜色、背景与边框tagLabelFontSize控制 tag 字号高亮提交颜色gitInv0~gitInv7按分支索引控制各分支上HIGHLIGHT提交的颜色同样最多 8 个、循环复用仓库中的实现与测试索引想在源码层面继续深入 GitGraph可以从以下入口按调用链阅读均在仓库相对路径下gitGraphDiagram.ts图定义注册parser db renderer stylesgitGraphAst.ts命令执行与状态机核心commit/branch/merge/cherryPick/checkout的校验与合并配置逻辑gitGraphParser.ts由 Jison 生成的语法解析器负责把文本切分为命令并回调上述函数gitGraphRenderer.tsSVG 绘制消费showCommitLabel、rotateCommitLabel、parallelCommits、showBranches等配置gitGraphTypes.tsCommit、commitTypeNORMAL/REVERSE/HIGHLIGHT/MERGE/CHERRY_PICK等类型定义config.type.tsGitGraphDiagramConfig配置类型gitGraph.spec.ts单元测试覆盖各命令行为与配置读取e2e/diagrams/gitgraph/100 余个端到端渲染用例.mmd文件覆盖 cherry-pick、merge 属性、order排序等场景是观察各语法实际渲染效果的最好素材本文依据的文档源文件位于 packages/mermaid/src/docs/syntax/gitgraph.mddocs/syntax/gitgraph.md 为其自动生成的站点版本。小结GitGraph 图用不到十行声明式文本就能表达 commit、branch、checkout、merge 与 cherry-pick 构成的完整分支协作流程每个提交支持id/type/tag属性每条branch支持ordergitGraph关键字支持LR:/TB:/BT:方向front matter 的gitGraph配置节与git0~git7、gitBranchLabel*、commitLabel*、tagLabel*、gitInv*主题变量则覆盖布局、命名、排序与外观的全部定制需求。配合源码中的严格校验重名分支、空分支合并、cherry-pick 父提交约束等你在写图时遇到的每个报错都能在 gitGraphAst.ts 中找到对应逻辑。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考