Gitgraph ダイアグラム
Git グラフは、さまざまなブランチ上の git コミットや git アクション (コマンド) の視覚的表現です。
このようなダイアグラムは、開発者や devops チームが Git のブランチ戦略を共有するのに特に役立ちます。例えば、git flow がどのように機能するかを視覚化するのが簡単になります。
Mermaid は Git ダイアグラムをレンダリングできます。
Code:
Mermaid では、次の基本的な git 操作をサポートしています。
- commit : 現在のブランチに新しいコミットを表します。
- branch : 新しいブランチを作成して切り替え、現在のブランチとして設定します。
- checkout : 既存のブランチをチェックアウトして、現在のブランチとして設定します。
- merge : 既存のブランチを現在のブランチにマージします。
これらの重要な git コマンドの助けを借りて、Mermaid で gitgraph を非常に簡単かつ迅速に描画できるようになります。 エンティティ名は大文字で表記されることが多いですが、これは受け入れられた標準ではなく、Mermaid では必須ではありません。
注: checkout と switch は入れ替えて使用できます。
構文
gitgraph のための Mermaid 構文は非常に簡潔でシンプルです。各コミットはダイアグラム内のタイムライン上に、コード内の発生／存在の順序に従って描画されます。基本的に、各コマンドの挿入順序に従います。
最初に行うことは、gitgraph キーワードを使用してダイアグラムのタイプを宣言することです。この gitgraph キーワードは、Mermaid に gitgraph を描画したいことを伝え、ダイアグラムコードを適切に解析します。
各 gitgraph は main ブランチで初期化されます。したがって、異なるブランチを作成しない限り、コミットはデフォルトでメインブランチに送信されます。これは、git がどのように機能するかに基づいています。最初は常にメインブランチ（以前は master ブランチと呼ばれていました）から始まります。そしてデフォルトで main ブランチが current branch として設定されます。
現在のブランチにコミットを登録するには commit キーワードを使用します。これがどのように機能するか見てみましょう：
デフォルトの (main) ブランチに 3 つのコミットを示す簡単な gitgraph：
Code:
前の例をよく見ると、デフォルトのブランチ main と 3 つのコミットが見えます。また、デフォルトでは各コミットにユニークでランダムな ID が割り当てられていることにも注意してください。コミットに独自のカスタム ID を付けたい場合はどうでしょうか？はい、Mermaid を使用すればそれが可能です。
カスタムコミット ID の追加
特定のコミットについて、宣言時に id 属性を使用してカスタム ID を指定できます。: の後に "" の引用符内にカスタム値を記述します。例えば: commit id: "your_custom_id"
次のダイアグラムの助けを借りて、これがどのように機能するか見てみましょう：
Code:
この例では、コミットにカスタム ID を付けています。
コミットタイプの変更
Mermaid では、コミットはダイアグラムで少し異なってレンダリングされる 3 種類のタイプを持つことができます。これらのタイプは：
NORMAL: デフォルトのコミットタイプ。ダイアグラムでは実線の円で表されます。REVERSE: コミットが逆コミットであることを強調表示します。ダイアグラムでは交差した実線の円で表されます。HIGHLIGHT: 特定のコミットをダイアグラム内で強調表示します。ダイアグラムでは塗りつぶされた長方形で表されます。
特定のコミットについて、宣言時に type 属性を使用してそのタイプを指定することができます。これは、上記で説明した必要なタイプオプションの後に : を付けます。例えば: commit type: HIGHLIGHT
NOTE: コミットタイプが指定されていない場合、NORMAL がデフォルトとして選択されます。
これらの異なるコミットタイプが次のダイアグラムでどのように見えるか見てみましょう：
Code:
この例では、各コミットに異なるタイプを指定しています。さらに、コミット宣言時に id と type を一緒に含めている様子にも注目してください。
タグの追加
特定のコミットに、git 世界におけるタグやリリースバージョンの概念のように タグ として装飾することができます。 コミットを宣言する際に tag 属性を使用してカスタムタグを添付できます。その後に : と、あなたのカスタム値を "" の引用符内に記述します。例えば: commit tag: "your_custom_tag"
次のダイアグラムの助けを借りて、これがどのように機能するか見てみましょう：
Code:
この例では、コミットにカスタムタグを付けています。また、すべての属性を 1 つのコミット宣言に組み合わせた方法にも注意してください。これらの属性を好きなように組み合わせることができます。
新しいブランチを作成する
Mermaid では、新しいブランチを作成するには branch キーワードを使用します。新しいブランチの名前も提供する必要があります。名前は一意であり、既存のブランチと重複してはいけません。キーワードと混同される可能性のあるブランチ名は、"" で囲む必要があります。使用例: branch develop, branch "cherry-pick"
Mermaid が branch キーワードを読み取ると、新しいブランチが作成され、それが現在のブランチとして設定されます。これは、Git 世界で新しいブランチを作成してチェックアウトすることと同等です。
次の例で見てみましょう：
Code:
この例では、デフォルトの main ブランチから始め、2 つのコミットを追加しました。 その後、develop ブランチを作成し、その後のすべてのコミットがそのブランチに追加されました。
既存のブランチをチェックアウトする
Mermaid では、既存のブランチに切り替えるには checkout キーワードを使用します。既存のブランチの名前も提供する必要があります。指定された名前のブランチが見つからない場合は、コンソールエラーが発生します。使用例: checkout develop
Mermaid が checkout キーワードを読み取ると、指定されたブランチが見つかり、現在のブランチとして設定されます。これは Git 世界でブランチをチェックアウトすることと同等です。
前の例を修正してみましょう：
Code:
この例では、デフォルトの main ブランチから始め、2 つのコミットを追加しました。 次に、develop ブランチを作成し、その後の 3 つのコミットは、そのブランチに追加されました。 その後、checkout キーワードを使用して main を現在のブランチとして設定し、その後のすべてのコミットは main に対して登録されます。
2 つのブランチをマージする
Mermaid では、既存のブランチにマージまたは結合するために merge キーワードを使用します。マージ元の既存のブランチの名前も提供する必要があります。指定された名前のブランチが見つからない場合は、コンソールエラーが発生します。また、同じブランチをマージすることはできず、異なる 2 つのブランチのみをマージできます。その場合はエラーが発生します。
使用例: merge develop
Mermaid が merge キーワードを読み取ると、指定されたブランチおよびそのヘッドコミット（そのブランチの最後のコミット）が見つかり、現在のブランチのヘッドコミットと結合します。各マージは merge commit を生成し、ダイアグラムでは 塗りつぶされた二重円 で表されます。
前の例を修正して、2 つのブランチをマージしてみましょう：
Code:
この例では、デフォルトの main ブランチから始め、2 つのコミットを追加しました。 その後、develop ブランチを作成し、その後の 3 つのコミットはそのブランチに追加されました。 次に、checkout キーワードを使用して main を現在のブランチとして設定し、その後のすべてのコミットは main に対して登録されます。 この後、develop ブランチを現在のブランチ main にマージし、マージコミットが生成されます。 この時点でまだ main ブランチなので、最後の 2 つのコミットはそのブランチに追加されます。
マージは、コミットに対して行ったのと同様の属性を使用して装飾することもできます：
id--> デフォルトの ID をカスタム ID に上書きするために使用tag--> マージコミットにカスタムタグを追加するために使用type--> マージコミットのデフォルメを変更するために使用。ここでは、前述の他のコミットタイプを使用できます。
そして、これらの属性をすべて一緒に使用するか、いくつかを使用するか、すべてを使用するか選択できます。 例えば: merge develop id: "my_custom_id" tag: "my_custom_tag" type: REVERSE
次のダイアグラムでこれがどのように機能するか見てみましょう：
Code:
別のブランチからコミットをチェリーピックする
'git' が 別のブランチ から 現在の ブランチにコミットをチェリーピックすることを許可するのと同様に、Mermaid もこの機能をサポートしています。cherry-pick キーワードを使用して、別のブランチからコミットをチェリーピックできます。
cherry-pick キーワードを使用するには、id 属性を指定し、その後に : と希望するコミット ID を "" の引用符内に記述する必要があります。例えば：
cherry-pick id: "your_custom_id"
ここで、チェリーピックを表す新しいコミットが現在のブランチに作成され、ダイアグラム内でその元となるコミット ID を示す チェリー とタグで視覚的に強調されます。
以下の重要なルールに注意してください：
- チェリーピックするためには既存のコミットの
idを提供する必要があります。指定されたコミット ID が存在しない場合はエラーが発生します。これにはcommit id:$valueコミット宣言の形式を使用します。上記の例を参照してください。 - 指定されたコミットは現在のブランチに存在してはいけません。チェリーピックするコミットは常に現在のブランチとは異なるブランチでなければなりません。
- チェリーピックする前に、現在のブランチに少なくとも 1 つのコミットが存在する必要があります。そうでない場合、エラーが発生します。
- マージコミットをチェリーピックする場合は、親コミット ID を指定することが必須です。親属性が省略されるか、無効な親コミット ID が提供されるとエラーが発生します。
- 指定された親コミットは、チェリーピックされるマージコミットの直近の親でなければなりません。
例を見てみましょう：
Code:
Gitgraph 専用の設定オプション
Mermaid では、gitgraph ダイアグラムを構成するオプションがあります。以下のオプションを構成できます。
showBranches: ブール値、デフォルトはtrue。falseに設定すると、ダイアグラムにブランチが表示されなくなります。showCommitLabel: ブール値、デフォルトはtrue。falseに設定すると、ダイアグラムにコミットラベルが表示されなくなります。mainBranchName: 文字列、デフォルトはmain。デフォルト / ルートブランチの名前。mainBranchOrder: ブランチのリスト内のメインブランチの位置。デフォルトは0で、デフォルトではmainブランチが最初に表示されます。parallelCommits: ブール値、デフォルトはfalse。trueに設定すると、親から x 離れたコミットがダイアグラム内で同じレベルに表示されます。
これらを一つずつ見ていきましょう。
ブランチ名とラインを隠す
時には、ダイアグラムからブランチ名やラインを隠したいことがあります。showBranches キーワードを使用することでこれを行うことができます。デフォルトではその値は true です。指示を使用して false に設定できます。
使用例：
Code:
コミットラベルのレイアウト: 回転または水平
Mermaid では、2 種類のコミットラベルレイアウトをサポートしています。デフォルトのレイアウトは 回転 で、これはラベルがコミットサークルの下に配置され、可読性向上のために 45 度回転されます。これは、長いラベルのあるコミットに特に便利です。
もう一つのオプションは 水平 で、これはラベルがコミットサークルの下に水平に中央に配置され、回転しないものです。短いラベルのあるコミットに特に便利です。
rotateCommitLabel キーワードを使用することで、コミットラベルのレイアウトを変更できます。デフォルトでは true で、コミットラベルは回転します。
使用例: 回転したコミットラベル
Code:
使用例: 水平コミットラベル
Code:
コミットラベルを隠す
時には、ダイアグラムからコミットラベルを隠したいことがあります。showCommitLabel キーワードを使用することでこれを行うことができます。デフォルトではその値は true です。指示を使用して false に設定できます。
使用例：
Code:
デフォルトブランチ名のカスタマイズ
時には、メイン／デフォルトブランチの名前をカスタマイズしたい場合があります。これを行うには、mainBranchName キーワードを使用します。デフォルトではその値は main です。指示を使用して任意の文字列に設定できます。
使用例：
Code:
見てください、ここで Mermaid を使用して作成された架空の鉄道地図では、デフォルトのメインブランチ名を MetroLine1 に変更しました。
ブランチの順序のカスタマイズ
Mermaid では、デフォルトでブランチは定義または出現の順序で表示されます。
時には、ブランチの順序をカスタマイズしたい場合があります。これを行うには、ブランチ定義の隣に order キーワードを使用します。正の数に設定できます。
Mermaid は order キーワードの優先順位に従います。
- メインブランチは常に最初に表示され、デフォルトの順序値は
0です。 （デフォルトでは、この値を変更するまで） - 次に、
orderが無いすべてのブランチが、ダイアグラムコード内の出現順序で表示されます。 - 次に、すべての
orderのあるブランチがorder値の順で表示されます。
すべてのブランチの順序を完全に制御するには、すべてのブランチに order を定義する必要があります。
使用例：
Code:
見てください、すべてのブランチが定義された順序に従って表示されています。
使用例：
Code:
見てください、ここでは、指定された順序がないすべてのブランチはだんだんとその定義の順序で描画されます。 次に、test4 ブランチが 1 の順に描画されます。 その後、main ブランチは 2 の順に描画されます。 最後に、test1 は 3 の順に描画されます。
注意: mainBranchOrder を 2 にオーバーライドしたため、main ブランチは表示されません。かわりに、定義の順序に従って表示されます。
向き (v10.3.0+)
Mermaid は 3 つのグラフの向き 左から右 (デフォルト)、上から下、そして 下から上 をサポートしています。
これを gitGraph の後に LR: (ための 左から右)、TB: (ための 上から下)、または BT: (ための 下から上) を使用して設定できます。
左から右 (デフォルト, LR:)
Mermaid では、デフォルトの向きはコミットが左から右に進み、ブランチは積み重ねられています。
ただし、これを明示的に LR: を gitGraph の後に追加することで設定できます。
使用例：
Code:
上から下 (TB:)
TB (上から下) の向きでは、コミットはグラフの上から下に進み、ブランチは横に配置されます。
このようにグラフを向けるには、gitGraph の後に TB: を追加します。
使用例：
Code:
下から上 (BT:) (v11.0.0+)
BT (下から上) の向きでは、コミットはグラフの下から上に進み、ブランチは横に配置されます。
このようにグラフを向けるには、gitGraph の後に BT: を追加します。
使用例：
Code:
並行するコミット (v10.8.0+)
Mermaid では、デフォルトで、一連のコミットにおける時間的情報が表示されます。たとえば、2 つのコミットがそれぞれ親から完全に 1 コミット離れている場合、最初に行われたコミットは親に近く表示されます。この動作をオフにするには parallelCommits フラグを有効にします。
時間的コミット (デフォルト, parallelCommits: false)
Code:
並行コミット (parallelCommits: true)
Code:
テーマ
Mermaid では、数種類のプリセットテーマがサポートされており、あなたに合ったテーマを探すことができます。実際、既存のテーマの変数を上書きしてカスタムテーマを作成することができます。図をテーマ設定する方法を学ぶにはこちらを参照してください。
以下は、異なる事前定義されたテーマオプションです：
baseforestdarkdefaultneutral
注: テーマを変更するには、initialize 呼び出しや _directives_を使用できます。directivesについて詳しく学んでください。 さまざまなテーマでサンプルダイアグラムがどのように表示されるかを見てみましょう：
ベーステーマ
Code:
森のテーマ
Code:
デフォルトテーマ
Code:
ダークテーマ
Code:
ニュートラルテーマ
Code:
テーマ変数を使用してカスタマイズ
Mermaid では、様々なダイアグラム要素の外観や感触を制御するテーマ変数を使用してダイアグラムをカスタマイズできます。
理解のために、サンプルダイアグラムを使用してテーマ default を選び、テーマのデフォルト値を使用しています。後で、テーマ変数のデフォルト値を上書きする方法を見ていきます。
以下のように、デフォルトテーマを使用して、ブランチの色を設定する様子を見せます。
Code:
重要：
Mermaid では、最大 8 つのブランチ のテーマ変数を上書きしてデフォルト値をカスタマイズすることをサポートしています。つまり、最大 8 つのブランチの色やスタイリングを設定できます。8 番目を超えるブランチは、循環によりテーマ変数を再利用します。つまり、9 番目のブランチは 1 番目のブランチの色やスタイリングを使用し、8 番目のブランチは 0 番目のブランチのものを使用します。 次のセクションで、この点について詳しく見て、ブランチラベルの色をカスタマイズする例を見ていきます。
ブランチの色をカスタマイズ
git0 から git7 までのテーマ変数を使用して、ブランチの色をカスタマイズできます。Mermaid では最大 8 つのブランチの色を設定でき、 git0 変数は最初のブランチの値を決定し、git1 は2番目のブランチの値を決定します。
注意: これらのテーマ変数のデフォルト値は、選択されたテーマから取得されます。デフォルト値を上書きしたい場合は、initialize 呼び出しを使用してカスタムテーマ変数の値を追加できます。
例:
次に、git0 から git3 変数のデフォルト値を上書きしてみましょう：
Code:
ブランチの色が、テーマ変数に設定した値に変更された様子が見えます。
ブランチラベルの色をカスタマイズ
gitBranchLabel0 から gitBranchLabel7 までのテーマ変数を使用して、ブランチラベルの色をカスタマイズできます。Mermaid では最大 8 つのブランチラベルの色を設定でき、 gitBranchLabel0 変数が最初のブランチラベルの値を決定し、gitBranchLabel1 変数が 2 番目のブランチラベルの値を決定します。
デフォルトのテーマを使用してブランチのラベルの色を設定する様子を見てみましょう：
次に、gitBranchLabel0 から gitBranchLabel2 までのデフォルト値を上書きしてみましょう：
Code:
ここで、branch8 と branch9 の色やスタイルが、インデックス位置 0 (main) および 1(branch1) のブランチから取得されていることがわかります。ブランチテーマ変数は循環的に繰り返されます。
コミットの色をカスタマイズ
コミットをカスタマイズするには、 commitLabelColor および commitLabelBackground テーマ変数を使用して、コミットラベルの色を変更できます。
例: 次に、commitLabelColor と commitLabelBackground 変数のデフォルト値を上書きしてみましょう：
Code:
コミットラベルの色と背景色が、テーマ変数に設定した値に変更された様子が見えます。
コミットラベルフォントサイズのカスタマイズ
commitLabelFontSize テーマ変数を使用して、コミットラベルのフォントサイズを変更できます。
例: 次に、commitLabelFontSize 変数のデフォルト値を上書きしてみましょう：
Code:
コミットラベルのフォントサイズが変更されたことがわかります。
タグラベルフォントサイズのカスタマイズ
tagLabelFontSize テーマ変数を使用して、タグラベルのフォントサイズを変更できます。
例: 次に、tagLabelFontSize 変数のデフォルト値を上書きしてみましょう：
Code:
タグラベルのフォントサイズが変更されたことがわかります。
タグの色をカスタマイズ
tagLabelColor、tagLabelBackground、および tagLabelBorder テーマ変数を使用して、タグラベルの色、タグラベルの背景色、タグラベルの境界線をそれぞれ変更できます。
例: 次に、tagLabelColor、tagLabelBackground 及び tagLabelBorder 変数のデフォルト値を上書きしてみましょう：
Code:
タグの色がテーマ変数に設定した値に変更された様子が見えます。
ハイライトコミットの色をカスタマイズ
gitInv0 から gitInv7 までのテーマ変数を使用して、それぞれのブランチ上のハイライトコミットの色をカスタマイズできます。Mermaid では最大 8 つのブランチに特有のハイライトコミットの色を設定でき、 gitInv0 変数が最初のブランチのハイライトコミットの値を決定します。
例:
次に、git0 から git3 変数のデフォルト値を上書きしてみましょう：
Code:
最初のブランチでのハイライトコミットの色が gitInv0 で指定された値に変更されたことがわかります。