GitGraph 圖表是一種專用的可視化組件，由開發人員、DevOps 團隊和技术撰稿人使用，以清晰地傳達 Git 分支策略、發行管理以及開發工作流程。內建於 Mermaid.js 中，gitGraph引擎使用聲明式、順序性的時間軸模型。這可將現實世界中的終端命令直接映射到精確的視覺時間軸地圖上，無需手動編輯圖像。
理解 GitGraph 時間軸矩陣
與自由形式的系統流程圖不同，GitGraph 圖表遵循嚴格的、順序的、按發生順序的邏輯，用以模擬真實的版本控制工作區：
- 自動根分支： 每個圖表工作區在初始化時會自動啟動一個主要的根時間軸軌道。預設情況下，此軌道命名為
main，且所有後續操作都將追蹤此軌道，除非創建了清晰的替代分支路徑。 - 順序優先級： 元素根據代碼來源檔案中命令的插入順序，沿著從左到右的時間軸順序渲染。
基本語法結構
每個時間軸都以駝峰式gitGraph宣告關鍵字開始。其後是按順序排列的原子執行命令列表，例如提交、切換和合併。
gitGraph
提交
提交
分支 feature-login
切換到 feature-login
提交
切換到 main
合併 feature-login
完整的 Git 操作命令參考
佈局引擎會解析特定的小寫操作命令，以推進線條粗細、分割軌道，或在工作區畫布上融合端點。
| Git 命令標記 | 參數引數修飾符 | 技術操作與佈局行為 |
|---|---|---|
提交 |
id: "hash", 類型: TYPE, 標籤："v1.0" |
將新的里程碑節點直接附加到活躍目標分支路徑線上。 |
分支 |
名稱, 順序：整數 |
建立新的分支通道分割。您可以使用可選的明確設定強制其垂直堆疊位置。順序值。 |
切換 / 切換 |
分支名稱 |
將活躍的錄製索引指針移動到指定的目標分支線上。後續操作將以此通道為追蹤對象。 |
合併 |
目標分支名稱, ID："雜湊", 標籤："v2" |
將指定的分支通道合併回目前分支，創造出明顯的視覺融合交叉點。 |
挑選 |
ID："提交雜湊", 父節點："父雜湊" |
將外部分支中的特定提交複製到目前分支通道上，而不融合通道。 |
進階功能：提交類型與標籤自訂
為了區分一般修補、系統回滾或重大發行，您可以指定明確的類型以及標籤使用類似 JSON 的鍵值屬性，在參數區塊內的字串修飾符。
支援的提交形狀分類：
類型：正常：預設設定。沿時間軸軌道顯示為填滿的實心圓形節點。類型：反向：強調架構或程式碼層面的回滾。顯示為交叉的實心圓形節點（$X$）。類型：強調：提醒注意關鍵的結構性變更或安全修復。顯示為拉長的填滿矩形方框。
gitGraph
提交 id："初始"
提交 類型：強調 id："安全熱修補" 標籤："v1.0.1"
提交 類型：反向 id："回滾功能-X"
進階功能：挑選邏輯與嚴格限制
該挑選指令會將來自不同分支軌道的特定孤立節點複製到您目前活躍的分支上。為避免觸發編譯器佈局錯誤，執行挑選時必須遵循以下嚴格的工作區驗證要求：
- 排除限制： 您要挑選的目標提交 ID *不得* 已存在於您目前追蹤的分支軌道上。
- 前置歷史： 目前活躍的分支線在執行挑選動作之前，必須至少包含一個有效的提交節點。
- 合併父節點要求： 如果您要挑選合併節點，必須明確地使用
父節點："雜湊"修飾區塊傳遞即時直接上游父節點識別字串。
gitGraph
提交 id："設定"
分支 staging
切換至 staging
提交 id："功能修補"
切換至 main
提交 id："基線"
挑選 id："功能修補"
進階功能：前置欄位參數設定
您可以透過在圖表腳本的絕對頂端宣告一個配置指令區塊，來微調全域視覺行為（例如切換分支標籤、修改列索引或堆疊時間軸）。%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% 配置指令區塊位於您的圖表腳本的絕對頂端。
可配置參數矩陣
| 配置金鑰字串 | 類型定義 | 預設值 | 視覺介面變更結果 |
|---|---|---|---|
showBranches |
布林值 | true |
切換畫布網格左側個別分支追蹤標籤的可見性。 |
showCommitLabel |
布林值 | true |
切換在個別時間軸節點上方直接渲染文字標題與字母數字雜湊值。 |
mainBranchName |
字串 | "main" |
變更預設起始根分支名稱追蹤文字（例如切換為"master" 或 "trunk"). |
mainBranchOrder |
整數 | 0 |
設定主要根時間軸追蹤軌道的自上而下垂直堆疊順序位置索引。 |
parallelCommits |
布林值 | 錯誤 |
如果修改為正確，共享相同父級步驟距離的獨立提交將在同一垂直層級上對稱對齊。 |
現實世界藍圖：企業級 Git-Flow 發布管理流程
此全面的企業藍圖展示了標準的生產發佈流程。它覆蓋了配置參數，將根路徑重命名為trunk，建立固定的分支順序層級，使用多個分支路徑（develop和feature-auth），執行合併操作，套用自訂標籤，並部署高優先級的強調提交形狀。
%%{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"
常見語法陷阱與系統限制
在編譯精確的版本控制圖形時，請記住這些故障排除參數，以避免佈局計算錯誤：
- 大小寫敏感錯誤： 主要的初始化宣告必須以明確的駝峰式大小寫書寫為
gitGraph。以全小寫書寫為gitgraph將觸發編譯器解析錯誤。 - 未加引號的字母數字識別符： 在傳遞自訂提交參數時（例如，
id: core_init），包含連字符、空格或句點的值必須用雙引號包圍。遺漏引號區塊將導致驗證編譯錯誤。 - 無效的切換目標： 呼叫
切換到分支 branch_name對一個未事先使用「」初始化的字串識別碼執行動作分支 branch_name指令會立即中斷圖形建立。 - 分支排序衝突： 當使用
排序分支上的配置標籤時，請確保多個軌道不會被映射到相同的整數，除非您希望畫布路徑痕跡重疊。請保持分支軌道編號的唯一性。 - 空格分隔失敗： 當在括號參數矩陣內分離屬性時，請確保明確的參數空格存在（例如使用
id: "1", type: HIGHLIGHT）。遺漏逗號或空格可能導致解析異常。