Gitgraph 圖表

Git Graph 是 Git 提交和 Git 操作（指令）在各個分支上的圖示表示。

這類圖表對於開發人員和 DevOps 團隊分享他們的 Git 分支策略特別有幫助。例如，它可以更容易地視覺化 Git Flow 的運作方式。

Mermaid 可以渲染 Git 圖表

在 Mermaid 中，我們支援基本的 Git 操作，例如：

• commit：表示在目前分支上的新提交。
• branch：建立並切換到新分支，將其設為目前分支。
• checkout：切換到現有分支並將其設為目前分支。
• merge：將現有分支合併到目前分支。

藉助這些關鍵的 Git 指令，您可以非常輕鬆快速地在 Mermaid 中繪製 Gitgraph。實體名稱通常會大寫，雖然沒有公認的標準，而且在 Mermaid 中不是必須的。

注意：checkout 和 switch 可以互換使用。

語法

Gitgraph 的 Mermaid 語法非常直接簡單。它遵循宣告式方法，其中每個提交都按照其在程式碼中的出現順序在圖表的時間軸上繪製。基本上，它遵循每個指令的插入順序。

您要做的第一件事是使用 gitgraph 關鍵字宣告圖表類型。這個 gitgraph 關鍵字告訴 Mermaid 您希望繪製 Gitgraph，並據此解析圖表程式碼。

每個 Gitgraph 都以 main 分支初始化。因此，除非您建立不同的分支，否則預設提交將會進入 main 分支。這是透過 Git 的運作方式來驅動的，一開始您總是從 main 分支開始（以前稱為 master 分支）。預設情況下，main 分支會設為您的 目前分支。

您可以使用 commit 關鍵字在目前分支上註冊提交。讓我們看看這是如何運作的

一個簡單的 Gitgraph，顯示預設 (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

讓我們借助以下圖表看看這是如何運作的

從另一個分支挑選提交 (Cherry Pick)

類似於 'git' 允許你將提交從另一個分支挑選到目前分支，Mermaid 也支援此功能。你也可以使用 cherry-pick 關鍵字從另一個分支挑選提交。

要使用 cherry-pick 關鍵字，你必須使用 id 屬性指定 id，然後加上 : 和你的所需提交 id，並用 "" 引號括起來。例如：

cherry-pick id: "your_custom_id"

這裡，會在目前分支上建立一個代表挑選提交的新提交，並在圖表中視覺化地用櫻桃和一個標籤來突顯，標籤上顯示它所挑選的提交 id。

以下是一些需要注意的重要規則：

1. 你需要為現有的提交提供 id 才能進行挑選。如果給定的提交 id 不存在，將會產生錯誤。為此，請使用宣告提交的 commit id:$value 格式。請參閱上面的範例。
2. 給定的提交不能存在於目前分支上。挑選的提交必須始終來自不同於目前分支的分支。
3. 在你可以挑選提交之前，目前分支必須至少有一個提交，否則會拋出錯誤。
4. 當挑選合併提交時，必須提供父提交 ID。如果省略父屬性或提供了無效的父提交 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 支援三種圖形方向：由左至右 (預設)、由上至下和由下至上。

你可以在 gitGraph 後面加上 LR: (適用於由左至右)、TB: (適用於由上至下) 或 BT: (適用於由下至上) 來設定此項。

由左至右 (預設，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 支援許多預先定義的主題，你可以使用它們來找到適合你的主題。附註：你實際上可以覆寫現有主題的變數以取得自己的自訂主題。在此處深入了解如何設定圖表的主題：這裡。

以下是不同的預先定義主題選項：

• base
• forest
• dark
• default
• neutral

注意：若要變更主題，你可以使用 initialize 呼叫或指令。深入了解指令。讓我們開始使用它們，並看看我們的範例圖表在不同主題中的外觀如何。

Base 主題

Forest 主題

Default 主題

Dark 主題

Neutral 主題

使用主題變數自訂

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 中指定的值。