GitGraph 図は、開発者、DevOps チーム、技術文書作成者が Git のブランチ戦略、リリース管理、開発ワークフローを明確に伝えるために使用する特殊な可視化コンポーネントです。Mermaid.js にネイティブに統合された、gitGraphエンジンは宣言的で順序付きのタイムラインモデルを利用しています。これにより、実際のターミナルコマンドが手動での画像編集を必要とせずに、正確な視覚的タイムラインマップに直接対応します。
GitGraph タイムラインマトリクスの理解
自由なフォーマットのシステムフローチャートとは異なり、GitGraph 図は、実際のバージョン管理ワークスペースをモデル化する厳密で順序付きの発生順序論理に従います：
- 自動ルートブランチ作成： 図のワークスペースが初期化されると、自動的に主要なルートタイムライントラックが作成されます。デフォルトでは、このトラックの名前は
mainです。すべての後続のアクションは、クリーンな代替ブランチパスが作成されない限り、このトラックに追従します。 - 順序優先順位： 要素は、コードソースファイル内のコマンドの挿入順序に基づいて、左から右へと時系列軸に沿ってレンダリングされます。
基本構文構造
すべてのタイムラインは、キャメルケースのgitGraph宣言キーワードから始まります。その後、コミット、チェックアウト、マージなどの原子的な実行コマンドの順序付き列が続きます。
gitGraph
commit
commit
branch feature-login
checkout feature-login
commit
checkout main
merge feature-login
完全な Git アクションコマンドリファレンス
レイアウトエンジンは、特定の小文字のアクションコマンドを解釈し、線の太さを進める、トラックを分岐させる、またはワークスペースキャンバス上でエンドポイントを統合します。
| Git コマンドトークン | パラメータ引数修飾子 | 技術的アクションおよびレイアウト動作 |
|---|---|---|
commit |
id: "hash", type: TYPE, タグ: "v1.0" |
アクティブなターゲットブランチパスラインの直後に新しいマイルストーンノードを追加します。 |
ブランチ |
名前, 順序: 整数 |
新しいブランチレーンの分岐を作成します。任意の明示的な順序を指定することで、垂直方向の積み重ね位置を強制できます。順序 値。 |
チェックアウト / 切り替え |
ブランチ名 |
アクティブなレコーディングインデックスポインタを指定されたターゲットブランチラインに移動します。以降の操作はこのレーンを対象に実行されます。 |
マージ |
ターゲットブランチ名, id: "ハッシュ", タグ: "v2" |
指定されたブランチレーンを現在のブランチに戻してマージし、明確な視覚的な融合交差点を作成します。 |
チェリーピック |
id: "コミットハッシュ", 親: "親ハッシュ" |
外部ブランチから特定のコミットを現在のブランチレーンに複製しますが、レーンを融合させません。 |
高度な機能: コミットタイプとタグカスタマイズ
通常のパッチ、システムのロールバック、またはメジャーリリースを区別するために、明示的なタイプ および タグJSON風のキー値プロパティを使用した引数ブロック内の文字列修飾子。
サポートされているコミット形状分類：
type: NORMAL: デフォルトの設定。タイムラインのレーンに沿って塗りつぶされた実心の円ノードとしてレンダリングされます。type: REVERSE: アーキテクチャ的またはプログラム的なロールバックを強調します。交差した実心の円ノード（$X$）としてレンダリングされます。type: HIGHLIGHT: 重要な構造的変更やセキュリティ修正に注意を喚起します。縦長の塗りつぶされた長方形ボックスとしてレンダリングされます。
gitGraph
commit id: "初期"
commit type: HIGHLIGHT id: "セキュリティ・ホットフィックス" tag: "v1.0.1"
commit type: REVERSE id: "機能Xのロールバック"
高度な機能：チェリーピック論理と厳格な制約
このチェリーピックコマンドは、別のブランチレーンから特定の孤立したノードを現在のアクティブなブランチにコピーします。コンパイラのレイアウトエラーを発生させずにチェリーピックを実行するには、以下の厳格なワークスペース検証要件を満たす必要があります：
- 除外制約： チェリーピック対象のコミットIDは、現在追跡しているブランチレーン上にすでに存在してはいけません。
- 前提となる履歴： 現在のアクティブなブランチラインには、チェリーピック操作を呼び出す前に、少なくとも1つの有効なコミットノードが存在している必要があります。
- マージ親要件： マージノードをチェリーピックする場合、直近の直接の上流親を識別する文字列を明示的に渡す必要があります。
parent: "hash"修飾子ブロックを使用して。
gitGraph
commit id: "セットアップ"
branch ステージング
checkout ステージング
commit id: "機能パッチ"
checkout main
commit id: "ベースライン"
cherry-pick id: "機能パッチ"
高度な機能：フロントマター・パラメータ設定
グローバルな視覚的動作（ブランチラベルの切り替え、行インデックスの変更、タイムラインの積み重ねなど）を微調整するには、%%{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）を使用し、マージを実行し、カスタムタグを適用し、高優先度のハイライトコミット形状をデプロイします。
%%{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"
一般的な構文の落とし穴とシステム制約
正確なバージョン管理グラフをコンパイルする際には、レイアウト計算のバグを防ぐために、以下のトラブルシューティングパラメータを念頭に置いてください：
- 大文字小文字の区別に関する誤り： 主要な初期化宣言は、明示的にcamelCaseで記述する必要があります。
gitGraph。すべて小文字で記述すると、gitgraphコンパイラのパースクラッシュが発生します。 - 引用符のないアルファベット・数字識別子： カスタムコミットパラメータを渡す際には（例：
id: core_init）、ハイフン、スペース、またはピリオドを含む値は、必ずダブルクォーテーションで囲む必要があります。クォーテーションブロックを忘れると、検証コンパイルエラーが発生します。 - 無効なチェックアウトターゲット： 呼び出しは
checkout branch_name文字列IDに対する操作で、事前に「using the」を使って初期化されていないものbranch branch_nameコマンドはグラフ構築を即座に破壊する。 - ブランチ順序の衝突： の利用時に
orderブランチにorder設定タグを使用する場合、重複するキャンバスパストレースを望まない限り、複数のトラックが同一の整数にマッピングされないようにしてください。ブランチのトラック番号は一意にしてください。 - スペース区切りの失敗：括弧内のパラメータ行列内でプロパティを区切る際には、明確な引数のスペースが存在することを確認してください（例：使用
id: "1", type: HIGHLIGHT）。欠落しているコンマやスペースを省略すると、パース例外が発生する可能性があります。