Submodule: Repo di Dalam Repo

Masalah yang diselesaikan submodule

Project-mu butuh library atau komponen yang dikembangkan di repo terpisah, misalnya theme, shared UI kit, atau firmware vendor. Copy-paste kodenya berarti versi basi selamanya. Submodule menanam repo lain di dalam folder project-mu sebagai referensi ke commit tertentu. Kenapa ini ada? Supaya project utama memakai kode repo lain TANPA menggabungkan riwayatnya, dengan versi yang tercatat eksplisit.

Menambah submodule

git submodule add https://github.com/contoh/ui-kit.git libs/ui-kit

Git melakukan tiga hal: clone repo itu ke libs/ui-kit, mencatat URL dan path di file .gitmodules, dan membuat entri khusus (gitlink) di index yang menunjuk ke commit tertentu dari repo itu. Kamu harus commit ketiganya:

git status --short
# A  .gitmodules
# A  libs/ui-kit
git commit -m "Tambah ui-kit sebagai submodule"

Perhatikan: yang tercatat BUKAN isi file-nya, melainkan pointer ke satu commit. Itulah konsep kunci submodule.

Clone dan update: dua langkah yang sering dilupakan

Orang yang clone project-mu TIDAK otomatis mendapat isi submodule:

git clone https://github.com/kamu/project.git
cd project
ls libs/ui-kit   # kosong!

Isi submodule harus diambil eksplisit:

git submodule init
git submodule update

Atau gabungkan saat clone:

git clone --recurse-submodules https://github.com/kamu/project.git

Untuk memperbarui submodule ke commit terbaru dari repo asalnya, masuk ke foldernya, pull, kembali, lalu commit pointer barunya:

cd libs/ui-kit
git pull origin main
cd ../..
git add libs/ui-kit
git commit -m "Update ui-kit ke versi terbaru"

Langkah git add libs/ui-kit inilah yang paling sering dilupakan: tanpa itu, superproject tetap menunjuk commit lama walau folder lokalmu sudah baru.

Jebakan pemula (wajib hafal)

Jebakan 1: lupa push di dalam submodule. Kamu commit perubahan di libs/ui-kit tapi lupa push repo ui-kit itu sendiri. Rekanmu pull superproject, update submodule, dan mendapat error karena commit yang ditunjuk tidak ada di remote. Aturan: push DALAM submodule dulu, baru commit pointer di superproject.

Jebakan 2: detached HEAD. Isi submodule selalu dalam keadaan detached HEAD di commit yang ditunjuk. Kalau kamu asal commit di dalamnya tanpa buat branch, commit itu menggantung tanpa nama branch dan mudah hilang. Selalu git checkout main (atau branch kerja) dulu sebelum mengubah isi submodule.

Jebakan 3: clone lupa --recurse-submodules. Folder submodule kosong, build gagal dengan error misterius "file not found". Solusinya ya perintah init/update di atas. Jadikan --recurse-submodules kebiasaan saat clone project yang memakai submodule.

Kapan submodule, kapan subtree, kapan monorepo

Submodule cocok ketika: repo komponen punya tim dan siklus rilis sendiri, dan project utama hanya perlu "versi X yang stabil". Kelemahannya: workflow dua langkah yang membingungkan pemula.

Subtree (git subtree) menggabungkan riwayat repo lain KE DALAM repo utamamu sebagai folder biasa. Cocok ketika: kamu ingin kode vendor ikut ter-versioning penuh dan kontributor tidak perlu belajar workflow submodule. Kelemahannya: riwayat jadi besar dan update dari upstream lebih manual.

Monorepo: satu repo raksasa berisi semua project dan library. Cocok ketika: satu tim memiliki semuanya dan ingin refactor lintas project dalam satu commit. Kelemahannya: butuh tooling (build system, CI) yang kuat saat skala membesar.

Untuk project sekolah atau tim kecil, urutan rekomendasi: monorepo dulu (paling sederhana), subtree kalau butuh kode eksternal sesekali, submodule hanya kalau komponennya benar-benar punya repo dan tim sendiri.

Kesalahan umum pemula

Salah: mengubah isi submodule, commit pointer di superproject, tapi lupa push repo submodule-nya, sehingga semua orang mendapat pointer ke commit yang tidak ada. Benar: urutan push selalu dari dalam ke luar: push submodule dulu, baru push superproject.

Salah: mengira git pull di project utama ikut memperbarui isi submodule ke versi terbaru. Benar: git pull hanya memperbarui pointer. Isi submodule baru berubah saat kamu jalankan git submodule update (atau git submodule update --remote untuk mengejar versi terbaru upstream).