在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

mermaid-js/mermaid

菜单

Git图

相关源文件

目的与范围

本文档提供了 Mermaid 中 Git Graph 图表的全面概述。Git Graph 图表允许用户可视化 Git 工作流和存储库历史，包括分支、提交、合并和选择性提交。本文档涵盖了 Mermaid 代码库中 Git Graph 图表类型的语法、功能、配置选项和实现细节。

来源： cypress/integration/rendering/gitGraph.spec.js1-10

Git Graph 图表概述

Git Graph 图表代表了 Git 存储库及其提交历史和分支结构。它们有助于可视化

  • 不同分支上的提交序列
  • 分支的创建和管理
  • 分支之间的合并操作
  • 选择性提交 (cherry-picks)
  • 发布标签 (release tagging)

图表可以渲染成不同的方向，以适应各种文档需求。

Git Graph 图表的基本构成

来源： cypress/integration/rendering/gitGraph.spec.js24-33 cypress/integration/rendering/gitGraph.spec.js34-43 cypress/integration/rendering/gitGraph.spec.js814-828

语法和命令

Mermaid 中的 Git Graph 图表以 gitGraph 关键字开头，后面可以选择跟一个方向指示符。

基本结构

gitGraph [orientation]:
  [git commands]

其中方向可以是

  • LR (从左到右，默认)
  • TB (从上到下)
  • BT (从下到上)

核心命令

创建 Git Graph 图表的主要命令包括

命令描述示例语法
commit在当前分支上创建一个提交commit id: "commit-id"
branch创建一个新分支branch branch-name
checkout / switch切换到另一个分支checkout branch-name
merge将一个分支合并到当前分支merge branch-name
cherry-pick从另一个分支选择性地应用 (cherry-pick) 一个提交cherry-pick id: "commit-id"

来源： cypress/integration/rendering/gitGraph.spec.js4-13 cypress/integration/rendering/gitGraph.spec.js44-59 cypress/integration/rendering/gitGraph.spec.js162-181 cypress/integration/rendering/gitGraph.spec.js1461-1488

提交类型和属性

Git Graph 支持不同的提交类型和属性，以增强存储库历史的可视化。

提交类型

Mermaid Git Graph 支持三种提交类型

  1. NORMAL - 标准提交 (默认)
  2. REVERSE - 反向提交，通常用于撤销 (revert)
  3. HIGHLIGHT - 高亮提交，用于重要的更改

示例

commit id: "Normal Commit"
commit id: "Reverse Commit" type: REVERSE
commit id: "Highlight Commit" type: HIGHLIGHT

提交属性

提交可以具有以下属性

属性描述示例
id提交的唯一标识符commit id: "abc123"
类型提交类型commit type: HIGHLIGHT
tag与提交关联的标签commit tag: "v1.0.0"

一个提交可以有多个标签

commit id: "Release" tag: "v1.0.0" tag: "stable"

来源： cypress/integration/rendering/gitGraph.spec.js24-33 cypress/integration/rendering/gitGraph.spec.js34-43 cypress/integration/rendering/gitGraph.spec.js1536-1552

分支管理

Git Graph 图表支持各种分支管理操作，这些操作代表了典型的 Git 工作流。

分支的创建和使用

分支的顺序和位置

您可以在图表中指定分支的顺序

branch branch-name order: 2

这会影响分支在图中的视觉位置。

来源： cypress/integration/rendering/gitGraph.spec.js44-59 cypress/integration/rendering/gitGraph.spec.js60-75 cypress/integration/rendering/gitGraph.spec.js984-997

合并操作

合并是 Git 工作流的基本组成部分，在 Git Graph 图表中得到了很好的支持。

基本合并

一个基本合并操作

checkout main
merge develop

自定义合并提交

合并可以具有自定义提交属性

merge develop id: "release-1.0" tag: "v1.0.0" type: HIGHLIGHT

合并可视化

来源： cypress/integration/rendering/gitGraph.spec.js60-75 cypress/integration/rendering/gitGraph.spec.js297-324

选择性提交 (Cherry-Pick) 操作

选择性提交允许您将一个分支的更改应用到另一个分支，这是 Git 中一项常见的操作，在 Git Graph 图表中得到了很好的表示。

基本选择性提交

cherry-pick id: "commit-id"

带标签的选择性提交

cherry-pick id: "commit-id" tag: "backport"

从合并提交进行选择性提交

选择性提交合并提交需要指定父提交

cherry-pick id: "merge-id" parent: "parent-id"

选择性提交可视化

来源： cypress/integration/rendering/gitGraph.spec.js162-181 cypress/integration/rendering/gitGraph.spec.js183-203 cypress/integration/rendering/gitGraph.spec.js814-828

方向选项

Git Graph 图表支持三种不同的方向，以匹配不同的文档布局。

从左到右 (默认)

gitGraph

或明确指定

gitGraph LR:

从上到下

gitGraph TB:

从下到上

gitGraph BT:

来源： cypress/integration/rendering/gitGraph.spec.js336-353 cypress/integration/rendering/gitGraph.spec.js376-390 cypress/integration/rendering/gitGraph.spec.js1016-1436

配置选项

Git Graph 图表可以使用初始化指令进行配置，以自定义其外观和行为。

初始化语法

%%{init: { "gitGraph": { options } } }%%
gitGraph
  ...

可用的配置选项

选项描述默认示例
rotateCommitLabel旋转提交标签false"rotateCommitLabel": true
showBranches显示分支标签true"showBranches": false
parallelCommits对齐不同分支上的提交false"parallelCommits": true

主题变量

Git Graph 图表也支持主题自定义

%%{init: { "themeVariables": {
  "gitBranchLabel0": "#color",
  "gitBranchLabel1": "#color",
  ...
} } }%%

来源： cypress/integration/rendering/gitGraph.spec.js105-132 cypress/integration/rendering/gitGraph.spec.js134-147 cypress/integration/rendering/gitGraph.spec.js829-865 cypress/platform/gitgraph.html34-56

实现细节

Git Graph Diagram Architecture

布局系统

Git Graph 图使用布局系统来定位分支和提交。当启用 parallelCommits 时，不同分支上的提交将水平（在 LR 方向）或垂直（在 TB/BT 方向）对齐。

来源： cypress/integration/rendering/gitGraph.spec.js829-865 cypress/integration/rendering/gitGraph.spec.js866-905 cypress/integration/rendering/gitGraph.spec.js906-944

常见用例

Feature Branch Workflow

这是一个带有功能分支、开发分支和主分支的常见 Git 工作流

Hotfix Workflow

处理热修复的常用工作流

带 Cherry-Picking 的 Release Branch

来源： cypress/integration/rendering/gitGraph.spec.js77-104 cypress/integration/rendering/gitGraph.spec.js162-224 cypress/integration/rendering/gitGraph.spec.js225-250

Tips and Best Practices

  1. Use consistent commit IDs: For clarity, use descriptive commit IDs that make the flow easy to understand.

  2. Tag important commits: Use tags for significant milestones, especially releases.

  3. Use appropriate commit types: Use HIGHLIGHT for important commits and REVERSE for reverts or rollbacks.

  4. Choose the right orientation:

    • LR (left-to-right) works well for horizontal documentation
    • TB (top-to-bottom) or BT (bottom-to-top) may work better for vertical layouts

  5. Consider parallelCommits: Enable parallelCommits: true for clearer visualization of commits happening in parallel on different branches.

  6. Use custom branch order: When branches overlap visually, use the order parameter to adjust their vertical positioning.

来源： cypress/integration/rendering/gitGraph.spec.js984-997 cypress/integration/rendering/gitGraph.spec.js829-865

有关 Mermaid 中其他图表类型的更多信息，请参阅