Mermaid.js GitGraph 図の構文ガイド

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 アクションコマンドリファレンス

レイアウトエンジンは、特定の小文字のアクションコマンドを解釈し、線の太さを進める、トラックを分岐させる、またはワークスペースキャンバス上でエンドポイントを統合します。

高度な機能: コミットタイプとタグカスタマイズ

通常のパッチ、システムのロールバック、またはメジャーリリースを区別するために、明示的なタイプ および タグ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': { ... } } } }%% 設定ディレクティブブロックをグラフスクリプトの絶対的な先頭に宣言することで

設定可能なパラメータマトリクス

実世界のブループリント：エンタープライズ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）。欠落しているコンマやスペースを省略すると、パース例外が発生する可能性があります。