Diagram GitGraph adalah komponen visualisasi khusus yang digunakan oleh pengembang, tim DevOps, dan penulis teknis untuk secara jelas menyampaikan strategi cabang Git, manajemen rilis, dan alur kerja pengembangan. Terintegrasi secara bawaan ke dalam Mermaid.js, gitGraphmesin menggunakan model timeline deklaratif dan berurutan. Ini memetakan perintah terminal dunia nyata secara langsung ke peta timeline visual yang akurat tanpa memerlukan pengeditan gambar secara manual.
Memahami Matriks Timeline GitGraph
Berbeda dengan bagan alir sistem bebas bentuk, diagram GitGraph mengikuti logika berurutan yang ketat, berdasarkan urutan kejadian, yang memodelkan ruang kerja kontrol versi yang sebenarnya:
- Cabang Akar Otomatis:Setiap ruang kerja diagram yang diinisialisasi secara otomatis akan membuat jalur timeline akar utama. Secara default, jalur ini dinamai
main, dan semua tindakan berikutnya akan melacak terhadapnya kecuali jalur cabang alternatif yang bersih dibuat. - Urutan Prioritas:Elemen dirender sepanjang sumbu kronologis dari kiri ke kanan berdasarkan urutan penyisipan perintah dalam file sumber kode Anda.
Struktur Sintaks Dasar
Setiap timeline dimulai dengan kata kunci gitGraphkata kunci deklarasi. Diikuti oleh daftar kolom berurutan dari perintah eksekusi atomik seperti commit, checkout, dan merge.
gitGraph
commit
commit
branch feature-login
checkout feature-login
commit
checkout main
merge feature-login
Referensi Lengkap Perintah Aksi Git
Mesin tata letak menginterpretasi perintah aksi tertentu dalam huruf kecil untuk memperkuat berat garis, membagi jalur, atau menggabungkan titik akhir bersama di seluruh kanvas ruang kerja.
| Token Perintah Git | Pengubah Argumen Parameter | Perilaku Aksi & Tata Letak Teknis |
|---|---|---|
commit |
id: "hash", type: TYPE, tag: "v1.0" |
Menambahkan simpul milestone baru langsung ke garis jalur cabang target aktif. |
cabang |
nama, urutan: Integer |
Menciptakan pemisahan jalur cabang baru. Anda dapat memaksa posisi tumpukan vertikalnya menggunakan opsi eksplisit yang opsionalurutan nilai. |
checkout / ganti |
nama-cabang |
Memindahkan penunjuk indeks rekaman aktif ke garis cabang target yang ditentukan. Tindakan selanjutnya akan dilacak berdasarkan jalur ini. |
gabung |
nama-cabang-tujuan, id: "hash", tag: "v2" |
Menggabungkan jalur cabang yang ditentukan kembali ke cabang saat ini, menciptakan titik persilangan visual yang berbeda. |
cherry-pick |
id: "hash-komit", induk: "hash-induk" |
Menggandakan komit tertentu dari cabang eksternal ke jalur cabang saat ini tanpa mencampurkan jalur-jalur tersebut. |
Fitur Lanjutan: Jenis Komit & Kustomisasi Tag
Untuk membedakan antara patch biasa, pengembalian sistem, atau rilis utama, Anda dapat menetapkan secara eksplisitjenis dan tagmodifikator string di dalam blok argumen menggunakan properti pasangan kunci-nilai seperti json.
Klasifikasi Bentuk Commit yang Didukung:
tipe: NORMAL: Konfigurasi bawaan. Ditampilkan sebagai node lingkaran padat yang terisi di sepanjang jalur waktu.tipe: REVERSE: Menyoroti pengembalian arsitektur atau pemrograman. Ditampilkan sebagai node lingkaran padat yang terpotong ($X$).tipe: HIGHLIGHT: Menarik perhatian pada perubahan struktural kritis atau perbaikan keamanan. Ditampilkan sebagai kotak persegi panjang yang memanjang dan terisi.
gitGraph
commit id: "Awal"
commit tipe: HIGHLIGHT id: "Perbaikan-Keselamatan" tag: "v1.0.1"
commit tipe: REVERSE id: "Pengembalian-Fitur-X"
Fitur Lanjutan: Logika Cherry-Pick & Kendala Ketat
Perintah cherry-pickperintah menyalin node terisolasi tertentu dari jalur cabang yang berbeda ke cabang aktif Anda saat ini. Untuk menjalankan cherry-pick tanpa menyebabkan kesalahan tata letak kompilator, Anda harus mematuhi persyaratan validasi ruang kerja yang ketat berikut:
- Kendala Pengecualian:ID commit target yang Anda cherry-pick *harus tidak* sudah ada di jalur cabang yang sedang Anda lacak saat ini.
- Sejarah Prasyarat:Garis cabang aktif saat ini harus berisi setidaknya satu node commit yang valid sebelum memanggil tindakan cherry-pick.
- Persyaratan Orang Tua Penggabungan:Jika Anda sedang melakukan cherry-pick pada node penggabungan, Anda harus secara eksplisit melewatkan string identifikasi orang tua langsung yang berada di atasnya menggunakan blok modifikator
parent: "hash"blok modifikator.
gitGraph
commit id: "setup"
cabang staging
checkout staging
commit id: "perbaikan-fitur"
checkout main
commit id: "dasar"
cherry-pick id: "perbaikan-fitur"
Fitur Lanjutan: Konfigurasi Parameter Frontmatter
Anda dapat menyesuaikan perilaku visual global (seperti mengaktifkan/menonaktifkan label cabang, memodifikasi indeks baris, atau menumpuk timeline) dengan menyatakan sebuah %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% blok arahan konfigurasi di bagian paling atas skrip grafik Anda.
Matriks Parameter yang Dapat Disesuaikan
| String Kunci Konfigurasi | Definisi Tipe | Nilai Default | Hasil Perubahan Antarmuka Visual |
|---|---|---|---|
showBranches |
Boolean | true |
Mengaktifkan/menonaktifkan visibilitas label pelacakan cabang individu di sisi kiri kisi kanvas. |
showCommitLabel |
Boolean | true |
Mengaktifkan/menonaktifkan rendering judul teks dan hash alfanumerik langsung di atas node timeline individu. |
mainBranchName |
String | "main" |
Mengubah teks pelacakan nama cabang akar awal (misalnya, mengganti ke "master" atau "trunk"). |
mainBranchOrder |
Integer | 0 |
Menetapkan indeks posisi urutan penumpukan vertikal dari atas ke bawah untuk jalur pelacakan timeline akar utama. |
parallelCommits |
Boolean | salah |
Jika dimodifikasi menjadi benar, komitmen terpisah yang memiliki jarak langkah induk yang identik akan sejajar secara simetris pada level vertikal yang sama. |
Rancangan Dunia Nyata: Pipeline Manajemen Rilis Git-Flow Perusahaan
Rancangan perusahaan yang komprehensif ini menunjukkan pipeline rilis produksi standar. Ini menimpa parameter konfigurasi untuk mengganti nama jalur akar menjadi trunk, menetapkan hierarki urutan cabang tetap, menggunakan beberapa jalur cabang (develop dan feature-auth), melakukan penggabungan, menerapkan tag khusus, dan menyebarluaskan bentuk komitmen sorotan prioritas tinggi.
%%{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"
Kesalahan Sintaks Umum & Kendala Sistem
Saat mengompilasi grafik kontrol versi yang akurat, pertimbangkan parameter pemecahan masalah ini untuk mencegah bug perhitungan tata letak:
- Kesalahan Sensitivitas Huruf Besar/Kecil: Deklarasi inisialisasi utama harus ditulis dalam camelCase eksplisit sebagai
gitGraph. Menuliskannya seluruhnya dalam huruf kecil sebagaigitgraphakan memicu kegagalan parsing kompilator. - Identifikasi Alfanumerik Tanpa Tanda Kutip: Saat melewatkan parameter komitmen khusus (misalnya,
id: core_init), nilai yang mengandung tanda hubung, spasi, atau titik *harus* dikelilingi dengan tanda kutip ganda. Lupa menggunakan blok tanda kutip akan menyebabkan kesalahan validasi kompilasi. - Target Checkout Tidak Valid: Memanggil
checkout branch_nametindakan pada identitas string yang belum diinisialisasi sebelumnya menggunakanbranch branch_nameperintah akan langsung menghentikan pembuatan grafik. - Tabrakan Urutan Cabang: Saat menggunakan
urutantag konfigurasi pada cabang, pastikan beberapa trek tidak dipetakan ke bilangan bulat yang sama kecuali Anda ingin jejak lintasan kanvas yang tumpang tindih. Pertahankan nomor trek cabang yang unik. - Kegagalan Pemisahan Spasi: Pastikan ruang argumen yang jelas ada saat memisahkan properti di dalam matriks parameter dalam tanda kurung (misalnya, gunakan
id: "1", type: HIGHLIGHT). Menghilangkan koma atau spasi yang hilang dapat menyebabkan pengecualian pemrosesan.